Fastjson2：阿里下一代高性能 JSON 库接入与使用指南

项目官方信息

项目背景与定位

FASTJSON 2 是一个性能极致并且简单易用的 Java JSON 库，是 FASTJSON 项目的重要升级，目标是为未来十年提供一个高性能的 JSON 库。老版本 fastjson 在国内 Java 生态使用极广，但历史上也因 AutoType 反序列化漏洞多次成为安全焦点；FASTJSON 2 从零重写了内核，把「快」和「安全」同时作为首要目标，而不是在老代码上打补丁。项目头部用一组徽章展示工程状态：Java CI 流水线、Codecov 测试覆盖率、Maven Central 版本号、GitHub Release、Java 8+ 支持徽章、Apache 2.0 协议徽章、Gitpod 一键开发环境、最新 SNAPSHOT、星标、Fork、被依赖仓库数与贡献者数。README 同时说明，本项目的 Issues 会被同步沉淀至阿里云开发者社区，中文问题可以直接在社区获得解答。

核心特性逐条解读

官方 README 列出九项核心特性，完整翻译展开如下。这九项可以归为四类：性能类（极致性能）、能力类（双格式、全量/部分解析、JSON Schema、多平台）、语言类（现代 Java、Kotlin 原生）、安全与部署类（安全优先、GraalVM 就绪）：

• 极致性能：性能远超 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：内置高性能 Schema 校验支持；
• 安全优先：AutoType 默认关闭，不使用硬编码白名单，支持 SafeMode；
• GraalVM 就绪：兼容 GraalVM Native Image，适合云原生原生镜像部署。

快速开始

添加依赖后即刻可以开始解析 JSON，整个上手过程不超过一分钟：先在 Maven 或 Gradle 里加上核心依赖，再 import com.alibaba.fastjson2.JSON，调用 JSON.parseObject 把 JSON 文本绑定成 Bean，或 JSON.toJSONString 把 Bean 序列化出去。README 给出的起步示例：

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

import com.alibaba.fastjson2.JSON;

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

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

一、添加依赖（全部方式）

官方 README 把依赖拆成四条路径：核心库、v1 兼容模块、Kotlin 模块、Spring 集成模块。普通 Java 项目只需要核心库；从 1.x 平移的项目优先考虑兼容模块；Kotlin 项目用 Kotlin 模块获得扩展函数；Spring 项目必须按 Spring 大版本选对应扩展包，否则 MVC 消息转换器不会生效。

1.1 核心库

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

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

Gradle 写法：

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

最新版本号请在 Maven Central 查看。

1.2 Fastjson v1 兼容模块

如果原来用的是 fastjson 1.2.x，可以用兼容包作为直接替换，包名仍保持 com.alibaba.fastjson，业务代码几乎不用动。官方提醒：兼容包不保证 100% 兼容，请仔细测试验证，发现问题及时反馈。Maven：

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

Gradle：

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

1.3 Kotlin 模块

Kotlin 项目使用 fastjson2-kotlin 模块，提供惯用扩展函数，例如直接对字符串调 text.parseObject()、对 Bean 调 user.toJSONString()，避免手写 Java 风格的静态调用。Maven：

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

按需再添加 Kotlin 标准库与反射库；使用数据类或通过构造函数传参时必须加反射库：

<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.66")
    implementation("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
    implementation("org.jetbrains.kotlin:kotlin-reflect:$kotlin_version")
}

1.4 Spring 框架集成

Spring 项目使用对应扩展模块，完整配置见 Spring 集成指南。注意必须按 Spring 大版本选包，否则 MVC / WebFlux 的消息转换器不会生效。Spring 5.x 用：

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

Spring 6.x 用：

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

Gradle 按 Spring 版本二选一：

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

二、简单使用

FASTJSON 2 的包名为 com.alibaba.fastjson2，从 v1 升级时只需修改包名导入。

这一组最常用的 API 覆盖了日常开发的全部典型场景：拿到一段 JSON 文本，要么解析成 JSONObject/JSONArray 这种「松散」容器按字段取数，要么直接绑定成强类型 Java Bean；反过来，把内存里的对象写成 JSON 文本或字节数组。下面按 README 顺序逐条翻译展开。

解析为 JSONObject：Java 支持从字符串或 UTF-8 字节数组解析；Kotlin 直接对字符串/字节数组调 parseObject() 扩展函数。

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

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

解析为 JSONArray：

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

解析为 Java 对象：

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

Kotlin 中可以写成 text.to<User>() 或 text.parseObject<User>() 两种形式。

序列化 Java 对象为 JSON：同时支持 String 与 byte[] 两种输出：

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

操作 JSONObject/JSONArray：用 getIntValue、getString 取简单属性，避免类型转换异常；用 getObject(索引或键, User.class) 直接读成 JavaBean；用 toJavaObject / toJavaList 把整个容器转成 Bean 或 List。Kotlin 侧对应 to<User>(索引) 与 toList<User>() 扩展函数。

序列化 JavaBean：定义一个带 public 字段的 User，直接调 JSON.toJSONString 即可输出，不需要任何额外注解；如果字段需要改名、排序、日期格式化或屏蔽（如 password 不输出），再用 @JSONField 定制。输出结果为 {"id":2,"name":"FastJson2"}。

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);

输出结果为 {"id":2,"name":"FastJson2"}。

三、进阶使用

基础 API 能满足绝大多数业务，进阶能力则面向性能敏感与定制场景：JSONB 解决二进制序列化体积与速度，JSONPath 解决大报文局部提取，Feature 开关解决行为微调，注解与自定义序列化解决个性化字段处理，过滤器体系解决统一加工输出。

JSONB 二进制格式：JSONB 是高性能二进制 JSON 格式，序列化/反序列化更快、数据体更小，适合 RPC 内部传输、缓存与消息体这类对体积和延迟敏感的场景。序列化为 JSONB 用 JSONB.toBytes(user)，加 JSONWriter.Feature.BeanToArray 可更紧凑；解析用 JSONB.parseObject(bytes, User.class)，配 JSONReader.Feature.SupportArrayToBean 支持数组转 Bean。

JSONPath：不必完整反序列化就能从大文档里选择性提取字段，非常适合从大报文里只取个别字段。FASTJSON 2 实现了 SQL:2016 JSONPath 语法。无论输入是 String、byte[] 还是 JSONB 字节，都先 JSONPath.of("$.id") 构造路径（建议缓存复用提升性能），再用 JSONReader.of(...) 或 JSONReader.ofJSONB(bytes) 构造解析器调 extract(parser)；过滤表达式、聚合函数、数组切片等完整用法见 JSONPath 文档。

Feature 配置：通过 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 列表与从 1.x 的迁移映射见 Feature 参考文档。

注解：用 @JSONField 与 @JSONType 自定义行为，例如改字段名、设置排序 ordinal、格式化日期、屏蔽密码字段：

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;
}

自定义序列化/反序列化：实现 ObjectWriter<T> 或 ObjectReader<T>，再用 JSON.register(类, 实例) 注册即可。

过滤器体系：序列化侧提供一整套过滤器——ValueFilter 转换属性值、NameFilter 重命名属性、PropertyFilter 条件包含/排除属性、AfterFilter/BeforeFilter 注入额外内容、LabelFilter 按场景序列化、ContextValueFilter/ContextNameFilter 上下文感知转换。

四、从 Fastjson 1.x 升级

FASTJSON 2 同时提供兼容模式（直接替换）与新 API 模式两条升级路径。官方特意用一张表把关键差异列清楚，翻译如下：

这张表对老项目最关键的提醒是「默认行为变了」：1.x 里默认开启的循环引用检测、智能匹配和若干 Feature，在 2.x 里默认全部关闭。如果业务原来依赖这些默认行为（例如靠循环引用检测避免对象自引用导致的栈溢出，或靠智能匹配容忍下划线/驼峰字段名差异），升级后需要显式打开对应 Feature，否则可能出现反序列化失败或输出变化。完整分步说明、API 映射表与常见问题见 升级指南。

五、文档索引

README 维护了一张完整文档导航表，这里按类翻译。这张表本身就是 fastjson2 区别于普通 JSON 库的地方：它不是一个只提供 parse/toJSONString 的小工具，而是围绕 JSON 处理建了一整套文档体系，覆盖二进制格式、JSONPath、注解、Spring、Kotlin、Android、GraalVM、安全与性能调优。

核心参考包括 Feature 参考、注解指南、架构文档、FAQ；格式与协议类包括 JSONB 格式、JSONB 与 Hessian/Kryo 对比、JSONB 体积对比、CSV 支持；JSONPath 类包括语法指南、多值提取、类型化提取与性能数据；框架集成类包括 Spring 支持（Spring MVC、WebFlux、Data Redis、Messaging）、Kotlin 扩展、Android 8+ 支持；自定义类包括自定义 Reader/Writer、MixIn 注解注入、AutoType 安全配置、JSON Schema 校验、过滤器体系；升级与性能类包括 v1 到 v2 升级指南、性能优化指南与基准测试结果。

六、参与贡献

官方欢迎各种形式的贡献——Bug 报告、功能请求、文档改进与代码贡献。开发环境搭建、编码规范与 PR 流程见 CONTRIBUTING.md；社区行为准则见 CODE_OF_CONDUCT.md；安全漏洞报告流程见 SECURITY.md。由于 fastjson 历史上多次成为安全事件焦点，官方把安全漏洞的私下上报流程单独写成 SECURITY.md，发现可疑反序列化问题时应按该流程走，而不是直接公开 issue。

常见问题 FAQ

问：fastjson2 的 groupId 和 1.x 一样吗？ 答：不一样。核心库 groupId 是 com.alibaba.fastjson2，包名也同步换成 com.alibaba.fastjson2；只有 v1 兼容模块仍用 com.alibaba:fastjson，专门用来老项目零改动替换。

问：从 1.x 升级要改包名吗？ 答：新 API 模式需要把 com.alibaba.fastjson 改成 com.alibaba.fastjson2；想零改动替换，用兼容模块 com.alibaba:fastjson:2.0.66，但官方提醒不保证 100% 兼容，务必测试。

问：示例里写的 2.0.66 是固定版本吗？ 答：不是，2.0.66 只是 README 编写时的示例版本号，最新版本号以 Maven Central 为准，生产项目建议锁定具体版本号。

问：AutoType 默认开启吗？安全吗？ 答：默认关闭，官方明确「安全优先」：无硬编码白名单、支持 SafeMode，相比 1.x 默认白名单开启的模式更安全，历史上的反序列化漏洞面被大幅收敛。

问：支持 Kotlin 吗？ 答：支持，有独立的 fastjson2-kotlin 模块，提供 DSL 风格扩展 API；用数据类需要再加 kotlin-reflect，否则构造函数参数绑定会失败。

问：能跑在 GraalVM Native Image 上吗？ 答：README 特性明确「GraalVM 就绪」，兼容 Native Image，适合云原生 Serverless 与原生镜像部署场景，不用为反射加额外配置。

问：Spring 项目用哪个包？ 答：Spring 5.x 用 fastjson2-extension-spring5，Spring 6.x 用 fastjson2-extension-spring6，按大版本二选一，不要混用。

问：JSONB 和普通 JSON 文本怎么选？ 答：README 把双格式列为核心特性：普通 JSON 文本可读、通用、跨语言；JSONB 是二进制格式，序列化/反序列化更快、体积更小，适合 RPC 内部传输、缓存、消息体这类对体积和延迟敏感的场景，必要时用 BeanToArray Feature 进一步压缩。

问：什么是 Feature 开关？为什么默认全关？ 答：JSONWriter.Feature 与 JSONReader.Feature 用来精细控制行为，例如是否输出 null 字段、是否格式化输出、是否智能匹配。2.x 默认全部关闭，避免 1.x 时代多个行为隐式开启带来的兼容问题，需要时显式打开。

问：怎么对第三方类做字段定制？ 答：用注解 @JSONField / @JSONType 标在自己的类上；第三方类改不了源码时，README 文档体系里提供了 MixIn 注解注入方案。

问：项目支持哪些 JDK？ 答：README 要求 Java 8+，并深度优化 JDK 8/11/17/21，利用 compact string、Record、Vector API 等现代 Java 特性。

问：解析大报文时只需要个别字段怎么办？ 答：用 JSONPath 做部分解析，不必把整个文档反序列化，JSONPath.of("$.id") 构造后可缓存复用，支持 String、byte[] 与 JSONB 三种输入。

问：想给 Money 这种类型自定义输出格式怎么办？ 答：实现 ObjectWriter<T> 或 ObjectReader<T>，再用 JSON.register(类, 实例) 注册；字段级的改名、排序、日期格式化、屏蔽某字段不输出，用 @JSONField 注解即可，例如 @JSONField(name="user_name", ordinal=1) 控制输出顺序。

问：fastjson2 是 GPL 协议吗？商用行不行？ 答：不是 GPL，是 Apache License 2.0，商用友好，允许修改与再分发。

问：fastjson2 和 Jackson、Gson 比优势在哪？ 答：README 用「极致性能」打头，性能远超 Jackson、Gson、org.json，并提供了公开基准测试结果，同时还多了 JSONB 二进制格式与 JSONPath 局部提取这两项能力。

问：企业内部已有 1.2.x 老项目，怎么迁移最稳？ 答：README 给两条路：一是用兼容模块 com.alibaba:fastjson:2.0.66 直接替换，零改包名，但官方提醒不保证 100% 兼容，必须回归测试；二是改包名到 com.alibaba.fastjson2 走新 API，并对照升级指南里的默认行为差异（循环引用检测、智能匹配、Feature 默认开关）逐项确认，避免隐式行为变化导致线上问题。

跳转链接

• 项目仓库：github.com/alibaba/fastjson2
• Maven 中央仓：fastjson2
• 在线文档：alibaba.github.io/fastjson2
• 性能测试：benchmark wiki
• 升级指南：fastjson_1_upgrade_cn.md
• 问题反馈：Issues