FASTJSON 2

September 2, 2026 · View on GitHub

Java CI Codecov Maven Central GitHub release Java support License Gitpod Ready-to-Code Last SNAPSHOT GitHub Stars GitHub Forks user repos GitHub Contributors

语言: English | 中文
本项目的Issues会被同步沉淀至阿里云开发者社区

FASTJSON 2

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

fastjson logo

核心特性

  • 极致性能 - 性能远超 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.65</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.65</version>
</dependency>

Gradle:

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

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

1.2 Fastjson v1 兼容模块

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

Maven:

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

Gradle:

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

1.3 Kotlin 模块

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

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-kotlin</artifactId>
    <version>2.0.65</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.65")
    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.65</version>
</dependency>

Maven (Spring 6.x):

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

Gradle:

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

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.xFastjson 2.x
包名com.alibaba.fastjsoncom.alibaba.fastjson2
GroupIdcom.alibabacom.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 SchemaSchema 校验
过滤器序列化过滤器

升级与性能

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

6. 参与贡献

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

Star History

Star History Chart