语言: English | 中文

本项目的Issues会被同步沉淀至阿里云开发者社区

FASTJSON 2

FASTJSON 2 是一个性能极致并且简单易用的 Java JSON 库，是 FASTJSON 项目的重要升级，目标是为未来十年提供一个高性能的 JSON 库。

核心特性

极致性能 - 性能远超 Jackson、Gson、org.json 等流行 JSON 库。性能数据
双格式支持 - 原生支持 JSON（文本）和 JSONB（二进制）两种协议
全量/部分解析 - 支持全量解析和通过 JSONPath 进行选择性提取（兼容 SQL:2016 标准）
现代 Java - 深度优化 JDK 8/11/17/21，支持 compact string、Record 和 Vector API
多平台 - 适用于 Java 服务端、Android 8+ 客户端及大数据应用
Kotlin 原生 - 一等公民级 Kotlin 扩展，提供惯用的 DSL 风格 API
JSON Schema - 内置高性能校验支持
安全优先 - AutoType 默认关闭，无硬编码白名单，支持 SafeMode
GraalVM 就绪 - 兼容 GraalVM Native Image

快速开始

添加依赖，即刻开始解析 JSON：

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.61</version>
</dependency>

import com.alibaba.fastjson2.JSON;

// 解析
User user = JSON.parseObject("{\"name\":\"张三\",\"age\":25}", User.class);

// 序列化
String json = JSON.toJSONString(user);

1. 添加依赖

1.1 核心库

FASTJSON 2 的 groupId 与 1.x 不同，为 com.alibaba.fastjson2：

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.61</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.alibaba.fastjson2:fastjson2:2.0.61'
}

可以在 Maven Central 查看最新可用版本。

1.2 Fastjson v1 兼容模块

如果原来使用 fastjson 1.2.x 版本，可以使用兼容包作为直接替换。兼容包不能保证 100% 兼容，请仔细测试验证，发现问题请及时反馈。

Maven:

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.61</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.alibaba:fastjson:2.0.61'
}

1.3 Kotlin 模块

如果项目使用 Kotlin，可以使用 fastjson2-kotlin 模块，提供惯用的 Kotlin 扩展函数：

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-kotlin</artifactId>
    <version>2.0.61</version>
</dependency>

酌情添加标准库（kotlin-stdlib）和反射库（kotlin-reflect）。若使用数据类（data class）或通过构造函数传入参数，则需添加反射库：

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-stdlib</artifactId>
    <version>${kotlin-version}</version>
</dependency>

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-reflect</artifactId>
    <version>${kotlin-version}</version>
</dependency>

Kotlin Gradle:

dependencies {
    implementation("com.alibaba.fastjson2:fastjson2-kotlin:2.0.61")
    implementation("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
    implementation("org.jetbrains.kotlin:kotlin-reflect:$kotlin_version")
}

1.4 Spring 框架集成

如果项目使用 Spring 框架，请使用对应版本的扩展模块。完整配置请参考 Spring 集成指南。

Maven (Spring 5.x):

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension-spring5</artifactId>
    <version>2.0.61</version>
</dependency>

Maven (Spring 6.x):

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension-spring6</artifactId>
    <version>2.0.61</version>
</dependency>

Gradle:

dependencies {
    // 根据 Spring 版本选择：
    implementation 'com.alibaba.fastjson2:fastjson2-extension-spring5:2.0.61'
    // 或
    implementation 'com.alibaba.fastjson2:fastjson2-extension-spring6:2.0.61'
}

2. 简单使用

FASTJSON 2 的 package 与 1.x 不同，为 com.alibaba.fastjson2。从 v1 升级时只需修改包名导入即可。

2.1 将 JSON 解析为 `JSONObject`

Java:

String text = "{\"id\":1,\"name\":\"fastjson2\"}";
JSONObject data = JSON.parseObject(text);

byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
JSONObject data = JSON.parseObject(bytes);

Kotlin:

import com.alibaba.fastjson2.*

val text = """{"id":1,"name":"fastjson2"}"""
val data = text.parseObject()

val bytes: ByteArray = text.toByteArray()
val data = bytes.parseObject() // JSONObject

2.2 将 JSON 解析为 `JSONArray`

Java:

String text = "[{\"id\":1},{\"id\":2}]";
JSONArray data = JSON.parseArray(text);

Kotlin:

import com.alibaba.fastjson2.*

val text = """[{"id":1},{"id":2}]"""
val data = text.parseArray() // JSONArray

2.3 将 JSON 解析为 Java 对象

Java:

String text = "{\"id\":1,\"name\":\"张三\"}";
User user = JSON.parseObject(text, User.class);

Kotlin:

import com.alibaba.fastjson2.*

val text = """{"id":1,"name":"张三"}"""
val user = text.to<User>()          // User
val user = text.parseObject<User>() // User（另一种写法）

2.4 将 Java 对象序列化为 JSON

Java:

User user = new User(1, "张三");
String text = JSON.toJSONString(user);   // String 输出
byte[] bytes = JSON.toJSONBytes(user);   // byte[] 输出

Kotlin:

import com.alibaba.fastjson2.*

val user = User(1, "张三")
val text = user.toJSONString()      // String
val bytes = user.toJSONByteArray()  // ByteArray

2.5 使用 `JSONObject` 和 `JSONArray`

2.5.1 获取简单属性

String text = "{\"id\": 2, \"name\": \"fastjson2\"}";
JSONObject obj = JSON.parseObject(text);

int id = obj.getIntValue("id");
String name = obj.getString("name");

String text = "[2, \"fastjson2\"]";
JSONArray array = JSON.parseArray(text);

int id = array.getIntValue(0);
String name = array.getString(1);

2.5.2 读取 JavaBean

Java:

JSONArray array = ...;
JSONObject obj = ...;

User user = array.getObject(0, User.class);
User user = obj.getObject("key", User.class);

Kotlin:

val array: JSONArray = ...
val obj: JSONObject = ...

val user = array.to<User>(0)
val user = obj.to<User>("key")

2.5.3 转为 JavaBean

Java:

JSONObject obj = ...;
JSONArray array = ...;

User user = obj.toJavaObject(User.class);
List<User> users = array.toJavaList(User.class);

Kotlin:

val obj: JSONObject = ...
val array: JSONArray = ...

val user = obj.to<User>()           // User
val users = array.toList<User>()    // List<User>

2.6 将 JavaBean 序列化为 JSON

Java:

class User {
    public int id;
    public String name;
}

User user = new User();
user.id = 2;
user.name = "FastJson2";

String text = JSON.toJSONString(user);
byte[] bytes = JSON.toJSONBytes(user);

Kotlin:

class User(
    var id: Int,
    var name: String
)

val user = User(2, "FastJson2")
val text = user.toJSONString()      // String
val bytes = user.toJSONByteArray()  // ByteArray

输出结果：

{"id":2,"name":"FastJson2"}

3. 进阶使用

3.1 JSONB 二进制格式

JSONB 是一种高性能的二进制 JSON 格式，提供更快的序列化/反序列化速度和更小的数据体积。详见 JSONB 格式规范。

序列化为 JSONB

User user = ...;
byte[] bytes = JSONB.toBytes(user);
byte[] bytes = JSONB.toBytes(user, JSONWriter.Feature.BeanToArray); // 更紧凑

解析 JSONB

byte[] bytes = ...;
User user = JSONB.parseObject(bytes, User.class);
User user = JSONB.parseObject(bytes, User.class, JSONReader.Feature.SupportArrayToBean);

3.2 JSONPath

JSONPath 支持不完全反序列化即可从 JSON 文档中提取特定字段，非常适合从大型数据中提取部分数据。FASTJSON 2 实现了 SQL:2016 JSONPath 语法。

从 String 中提取

String text = ...;
JSONPath path = JSONPath.of("$.id"); // 缓存起来重复使用能提升性能

JSONReader parser = JSONReader.of(text);
Object result = path.extract(parser);

从 byte[] 中提取

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // 缓存起来重复使用能提升性能

JSONReader parser = JSONReader.of(bytes);
Object result = path.extract(parser);

从 JSONB byte[] 中提取

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // 缓存起来重复使用能提升性能

JSONReader parser = JSONReader.ofJSONB(bytes); // 注意这里使用 ofJSONB 方法
Object result = path.extract(parser);

完整的过滤表达式、聚合函数、数组切片等用法请参阅 JSONPath 文档。

3.3 Feature 配置

FASTJSON 2 通过 JSONWriter.Feature 和 JSONReader.Feature 提供对序列化和反序列化行为的精细控制。所有 Feature 默认关闭。

// 带 Feature 的序列化
String json = JSON.toJSONString(user,
    JSONWriter.Feature.WriteNulls,
    JSONWriter.Feature.PrettyFormat);

// 带 Feature 的反序列化
User user = JSON.parseObject(json, User.class,
    JSONReader.Feature.SupportSmartMatch);

完整的 Feature 列表和从 fastjson 1.x 的迁移映射请参阅 Feature 参考文档。

3.4 注解

使用 @JSONField 和 @JSONType 自定义序列化/反序列化行为：

public class User {
    @JSONField(name = "user_name", ordinal = 1)
    public String name;

    @JSONField(format = "yyyy-MM-dd", ordinal = 2)
    public Date birthday;

    @JSONField(serialize = false)
    public String password;
}

详见注解使用指南。

3.5 自定义序列化/反序列化

实现 ObjectWriter<T> 或 ObjectReader<T> 以自定义序列化逻辑：

// 自定义 Writer
class MoneyWriter implements ObjectWriter<Money> {
    public void write(JSONWriter jsonWriter, Object object, Object fieldName, Type fieldType, long features) {
        Money money = (Money) object;
        jsonWriter.writeString(money.getCurrency() + " " + money.getAmount());
    }
}

// 注册
JSON.register(Money.class, new MoneyWriter());

详见自定义 Reader/Writer 指南。

3.6 过滤器

FASTJSON 2 提供了完善的序列化过滤器体系：

过滤器	用途
`ValueFilter`	转换属性值
`NameFilter`	重命名属性
`PropertyFilter`	条件性包含/排除属性
`AfterFilter` / `BeforeFilter`	注入额外内容
`LabelFilter`	基于场景的序列化
`ContextValueFilter` / `ContextNameFilter`	上下文感知转换

详见过滤器文档。

4. 从 Fastjson 1.x 升级

FASTJSON 2 提供兼容模式（直接替换）和新 API 模式两种升级方式。关键变化：

方面	Fastjson 1.x	Fastjson 2.x
包名	`com.alibaba.fastjson`	`com.alibaba.fastjson2`
GroupId	`com.alibaba`	`com.alibaba.fastjson2`
AutoType	默认通过白名单开启	默认关闭（更安全）
循环引用检测	默认开启	默认关闭
智能匹配	默认开启	默认关闭
默认 Feature	多个 Feature 默认开启	所有 Feature 默认关闭

完整的分步说明、API 映射表和常见问题请参阅升级指南。

5. 文档索引

核心参考

文档	说明
Feature 参考	JSONReader/JSONWriter Feature 完整列表
注解指南	@JSONField、@JSONType、@JSONCreator 使用说明
架构文档	内部架构、设计模式和类层次结构
常见问题	常见问题与排查指南

格式与协议

文档	说明
JSONB 格式	二进制 JSON 格式规范
JSONB vs Hessian/Kryo	与其他二进制格式的性能对比
JSONB 大小对比	数据体积对比
CSV 支持	CSV 读写支持

JSONPath

文档	说明
JSONPath 指南	语法、操作符和示例
多值 JSONPath	多值提取
类型化 JSONPath	类型安全的 JSONPath 提取
JSONPath 性能	性能数据

框架集成

文档	说明
Spring 支持	Spring MVC、WebFlux、Data Redis、Messaging
Kotlin 扩展	Kotlin API 和 DSL
Android 支持	Android 8+ 集成

自定义

文档	说明
自定义 Reader/Writer	实现 ObjectReader/ObjectWriter
MixIn 注解	为第三方类注入注解
AutoType 安全	AutoType 机制和安全配置
JSON Schema	Schema 校验
过滤器	序列化过滤器

升级与性能

文档	说明
v1 到 v2 升级	升级指南与 API 映射
性能优化指南	调优建议与最佳实践
性能测试	完整性能测试结果

6. 参与贡献

我们欢迎各种形式的贡献——Bug 报告、功能请求、文档改进和代码贡献。

参阅 CONTRIBUTING.md 了解开发环境搭建、编码规范和 PR 流程
参阅 CODE_OF_CONDUCT.md 了解社区行为准则
参阅 SECURITY.md 了解安全漏洞报告流程

Uh oh!

FilesExpand file tree

README_cn.md

Latest commit

History

README_cn.md

File metadata and controls

语言: English | 中文

本项目的Issues会被同步沉淀至阿里云开发者社区

FASTJSON 2

核心特性

目录

快速开始

1. 添加依赖

1.1 核心库

1.2 Fastjson v1 兼容模块

1.3 Kotlin 模块

1.4 Spring 框架集成

2. 简单使用

2.1 将 JSON 解析为 JSONObject

2.2 将 JSON 解析为 JSONArray

2.3 将 JSON 解析为 Java 对象

2.4 将 Java 对象序列化为 JSON

2.5 使用 JSONObject 和 JSONArray

2.5.1 获取简单属性

2.5.2 读取 JavaBean

2.5.3 转为 JavaBean

2.6 将 JavaBean 序列化为 JSON

3. 进阶使用

3.1 JSONB 二进制格式

序列化为 JSONB

解析 JSONB

3.2 JSONPath

从 String 中提取

从 byte[] 中提取

从 JSONB byte[] 中提取

3.3 Feature 配置

3.4 注解

3.5 自定义序列化/反序列化

3.6 过滤器

4. 从 Fastjson 1.x 升级

5. 文档索引

核心参考

格式与协议

JSONPath

框架集成

自定义

升级与性能

6. 参与贡献

Star History

2.1 将 JSON 解析为 `JSONObject`

2.2 将 JSON 解析为 `JSONArray`

2.5 使用 `JSONObject` 和 `JSONArray`