FastJson2 完整使用指导文档（Java 后端企业级实战版）

以下是一份专为 Java 后端开发者设计的 FastJson2 详细使用指导说明文档，涵盖定义、作用、必要性、核心功能、与主流工具对比、企业级实战建议，并附带带详细中文注释的代码示例，助你和团队高效落地。

---

📄 FastJson2 完整使用指导文档（Java 后端企业级实战版）

适用人群：Java 后端开发者、架构师、技术负责人
目标：全面掌握 FastJson2 的核心能力，替代旧版 FastJson / Jackson / GSON，提升序列化性能与安全性，推动团队标准化落地

---

一、FastJson2 是什么？

FastJson2 是阿里巴巴开源的下一代高性能 JSON 库，是 FastJson 1.x 的彻底重构版本，于 2022 年正式发布。它在性能、安全性、标准兼容性、扩展性等方面实现了质的飞跃，是目前 Java 生态中性能最优、安全最强、功能最全的 JSON 序列化/反序列化工具之一。

✅ 官方地址：https://github.com/alibaba/fastjson2
✅ 当前最新稳定版：2.0.54+（2025 年推荐使用）

---

二、FastJson2 有什么作用？

FastJson2 的核心作用是：

作用	说明
序列化（Serialize）	将 Java 对象（POJO）转换为 JSON 字符串，用于 API 响应、缓存存储、日志记录等
反序列化（Deserialize）	将 JSON 字符串还原为 Java 对象，用于 API 请求解析、配置加载、消息队列消费等
高效处理复杂结构	支持嵌套对象、List、Map、Date、Enum、自定义类型、循环引用等复杂场景
零拷贝优化	在内存使用和 CPU 消耗上大幅优化，适合高并发、低延迟系统

🌐 在企业级系统中，JSON 是前后端通信、微服务间调用、Redis 缓存存储的事实标准格式。FastJson2 是处理该格式的高性能引擎。

---

三、为什么需要使用 FastJson2？

1. 安全漏洞修复（重大原因）

• FastJson 1.x 曾因反序列化漏洞（如 CVE-2020-8840）被广泛曝出远程代码执行风险，企业禁用 1.x 已成行业共识。
• FastJson2 从架构层面彻底移除 autoType 机制默认开启，并引入白名单、类加载隔离、反序列化沙箱等安全策略，默认安全。

2. 性能碾压竞品

根据官方基准测试（2024）：

工具	序列化速度（ops/s）	反序列化速度（ops/s）	内存占用
FastJson2	~2,100,000	~1,800,000	最低
Jackson	~850,000	~780,000	中等
GSON	~600,000	~550,000	较高

💡 在 QPS 10,000+ 的电商订单系统中，使用 FastJson2 可降低 30%+ 的 CPU 负载，节省服务器成本。

3. 标准兼容性更强

• 完全支持 JSON Schema、ISO 8601 日期格式、BigDecimal 精确序列化
• 支持 Java 8+ 新特性：LocalDateTime、Optional、Stream、Record（Java 16+）
• 支持 JSON Pointer、JSON Patch（RFC 6902）

4. 企业级功能完备

• 多种序列化策略（字段过滤、忽略空值、大小写转换）
• 自定义序列化器/反序列化器
• 支持注解驱动（@JSONField、@JSONType）
• 支持 JSONPath 查询（类似 XPath）
• 支持 二进制 JSON（BSON） 格式（用于高性能存储）

---

四、FastJson2 vs 其他 JSON 工具对比

特性	FastJson2	Jackson	GSON	FastJson 1.x
性能	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐（但有漏洞）
安全性	⭐⭐⭐⭐⭐（默认安全）	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐（高危漏洞）
标准兼容	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐
注解支持	✅ @JSONField	✅ @JsonProperty	✅ @SerializedName	✅ @JSONField
循环引用处理	✅（自动）	✅（需配置）	✅	❌（易栈溢出）
Java 8+ 支持	✅ 完整	✅ 完整	✅ 完整	❌ 不完整
社区活跃度	⭐⭐⭐⭐⭐（阿里主力维护）	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐（已停止维护）
企业推荐度	✅ 强烈推荐	✅ 推荐	⚠️ 仅限轻量项目	❌ 禁用

✅ 结论：新项目首选 FastJson2；老项目必须从 FastJson 1.x 迁移；Jackson 适合对配置复杂度容忍度高的团队。

---

五、FastJson2 核心功能详解

1. 基础序列化与反序列化（最常用）

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONObject;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

// 定义实体类（POJO）
@Data
public class User {
    private Long id;
    private String name;
    private String email;
    private LocalDateTime createTime; // Java 8 时间类型支持
}

// 【实战示例1】序列化对象为 JSON 字符串
public class FastJSON2Demo {
    public static void main(String[] args) {
        // 创建对象
        User user = new User(1001L, "张三", "zhangsan@company.com", LocalDateTime.now());

        // ✅ 序列化：Java对象 → JSON字符串（默认格式化，可读性强）
        String jsonString = JSON.toJSONString(user);
        System.out.println("序列化结果：\n" + jsonString);
        // 输出：{"id":1001,"name":"张三","email":"zhangsan@company.com","createTime":"2025-10-15T10:30:45"}

        // ✅ 反序列化：JSON字符串 → Java对象
        User parsedUser = JSON.parseObject(jsonString, User.class);
        System.out.println("\n反序列化结果：");
        System.out.println("ID: " + parsedUser.getId());
        System.out.println("姓名: " + parsedUser.getName());
        System.out.println("邮箱: " + parsedUser.getEmail());
        System.out.println("创建时间: " + parsedUser.getCreateTime());

        // ✅ 支持 Map 和 List 的序列化
        List<User> userList = List.of(user, new User(1002L, "李四", "lisi@company.com", LocalDateTime.now()));
        String userListJson = JSON.toJSONString(userList);
        System.out.println("\n用户列表JSON：\n" + userListJson);

        // ✅ 支持 JSON 数组反序列化
        List<User> parsedList = JSON.parseArray(userListJson, User.class);
        System.out.println("\n反序列化用户列表数量：" + parsedList.size());
    }
}

✅ 注释要点：

• JSON.toJSONString()：默认输出格式化 JSON，可读性强，适合日志、调试
• JSON.parseObject(jsonStr, Class<T>)：安全反序列化，不会自动加载任意类（安全机制）
• JSON.parseType("List<User>")：泛型类型解析，避免类型擦除问题

---

2. 使用注解控制序列化行为（企业级必备）

import com.alibaba.fastjson2.annotation.JSONField;

public class Order {
    @JSONField(name = "order_id", serialize = true, deserialize = true)
    private Long orderId;

    @JSONField(name = "total_amount", serialize = true, deserialize = true, format = "###,##0.00")
    private BigDecimal totalAmount;

    @JSONField(name = "create_time", serialize = true, deserialize = true, format = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @JSONField(serialize = false) // 不序列化到 JSON
    private String internalRemark;

    @JSONField(serialize = false, deserialize = false) // 忽略字段
    private transient String password;

    // 构造函数、getter/setter 省略...

    public Order(Long orderId, BigDecimal totalAmount, LocalDateTime createTime, String internalRemark, String password) {
        this.orderId = orderId;
        this.totalAmount = totalAmount;
        this.createTime = createTime;
        this.internalRemark = internalRemark;
        this.password = password;
    }
}

// 使用示例
public class AnnotationDemo {
    public static void main(String[] args) {
        Order order = new Order(
            5001L,
            new BigDecimal("12345.67"),
            LocalDateTime.of(2025, 10, 15, 10, 30, 45),
            "内部备注：VIP客户",
            "123456"
        );

        String json = JSON.toJSONString(order);
        System.out.println("注解控制后的 JSON：\n" + json);
        // 输出：
        // {
        //   "order_id": 5001,
        //   "total_amount": "12,345.67",  // 格式化金额
        //   "create_time": "2025-10-15 10:30:45"  // 自定义日期格式
        // }
        // 注意：internalRemark 和 password 被完全忽略！

        // 反序列化同样生效
        Order parsed = JSON.parseObject(json, Order.class);
        System.out.println("\n反序列化后：");
        System.out.println("订单ID：" + parsed.getOrderId());
        System.out.println("金额：" + parsed.getTotalAmount());
        System.out.println("时间：" + parsed.getCreateTime());
        System.out.println("内部备注：" + parsed.getInternalRemark()); // 仍为 null（未反序列化）
    }
}

✅ 注释要点：

• name：自定义 JSON 字段名（适配前端命名规范，如 snake_case）
• format：日期/数字格式化（避免前端解析异常）
• serialize = false：生产环境强烈建议对敏感字段（密码、token）禁用序列化
• transient 关键字与 serialize = false 效果一致，建议统一使用注解以提高可维护性

---

3. 高级配置：全局序列化策略（企业级统一规范）

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONWriter;

import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

public class GlobalConfigDemo {
    public static void main(String[] args) {
        // ✅ 设置全局配置：推荐在 Spring Boot 启动类或配置类中初始化一次
        JSONWriter.Feature[] features = {
            JSONWriter.Feature.WriteNulls,           // 输出 null 值字段（默认不输出）
            JSONWriter.Feature.WriteMapNullValue,    // Map 中的 null 值也输出
            JSONWriter.Feature.WriteClassName,       // 序列化时写入类名（仅调试用，生产环境禁用！）
            JSONWriter.Feature.WriteDateUseDateFormat, // 使用 format 格式化日期
            JSONWriter.Feature.WriteNonStringKeyAsString // Map 的非字符串 Key 自动转为字符串
        };

        // 创建配置对象
        JSONWriter.Feature[] disableFeatures = {
            JSONWriter.Feature.WriteClassName // 生产环境必须关闭！防止反序列化攻击
        };

        // ✅ 设置默认写入配置（推荐在项目初始化时调用）
        JSONWriter.config(JSONWriter.Feature.WriteDateUseDateFormat, true);
        JSONWriter.config(JSONWriter.Feature.WriteNulls, false); // 生产环境：不输出 null 字段，减少传输体积
        JSONWriter.config(JSONWriter.Feature.WriteMapNullValue, false);

        // ✅ 自定义日期格式（统一标准）
        JSONWriter.config(JSONWriter.Feature.WriteDateUseDateFormat, true);
        JSONWriter.config(JSONWriter.Feature.WriteDateAsJSONString, false); // 不输出为 ISO 字符串，改用自定义格式

        // 使用配置序列化
        User user = new User(1001L, "王五", "wangwu@company.com", LocalDateTime.now());
        String json = JSON.toJSONString(user);
        System.out.println("全局配置后输出：\n" + json);
        // 输出：{"id":1001,"name":"王五","email":"wangwu@company.com","createTime":"2025-10-15 10:30:45"}
        // 注意：没有 null 字段，日期格式统一为 "yyyy-MM-dd HH:mm:ss"
    }
}

✅ 企业级建议：

• 生产环境禁止 WriteClassName，防止反序列化攻击
• 推荐关闭 WriteNulls，减少网络传输体积（前端可默认处理 null）
• 统一日期格式：建议使用 yyyy-MM-dd HH:mm:ss，避免前端解析歧义
• 所有配置应在项目启动时一次性设置，避免分散配置导致不一致

---

4. 自定义序列化器（处理复杂类型）

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONWriter;
import com.alibaba.fastjson2.writer.ObjectWriter;
import com.alibaba.fastjson2.writer.ObjectWriterProvider;

import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

// 自定义 BigDecimal 序列化器：统一保留两位小数，不使用科学计数法
public class BigDecimalSerializer implements JSONWriter.ObjectSerializer {
    public static final BigDecimalSerializer INSTANCE = new BigDecimalSerializer();

    @Override
    public void write(JSONWriter jsonWriter, Object object, Object fieldName, java.lang.reflect.Type fieldType, long features) {
        if (object instanceof BigDecimal bd) {
            // 强制保留两位小数，避免 1.0E+4 这类科学计数
            jsonWriter.write(bd.setScale(2, java.math.RoundingMode.HALF_UP).toPlainString());
        } else {
            jsonWriter.writeNull();
        }
    }
}

// 注册自定义序列化器（推荐在 Spring 配置中注册）
public class CustomSerializerDemo {
    public static void main(String[] args) {
        // 注册自定义序列化器
        ObjectWriterProvider provider = new ObjectWriterProvider();
        provider.put(BigDecimal.class, BigDecimalSerializer.INSTANCE);

        // 使用自定义 Provider
        JSONWriter writer = new JSONWriter(provider);
        Order order = new Order(5001L, new BigDecimal("12345.6789"), LocalDateTime.now(), null, null);

        String json = writer.toJSONString(order);
        System.out.println("自定义序列化结果：\n" + json);
        // 输出：{"order_id":5001,"total_amount":"12345.68","create_time":"2025-10-15 10:30:45"}
        // 注意：金额精确保留两位小数，无科学计数
    }
}

✅ 适用场景：

• 金融系统：金额必须精确格式化
• 外部 API：要求字段格式严格符合规范
• 统一日志格式：如时间戳统一为 Unix 毫秒

---

六、企业级实战建议（Practical Recommendations）

场景	推荐做法
API 接口响应	使用 JSON.toJSONString(obj)，关闭 WriteNulls，统一日期格式
Redis 缓存存储	使用 JSON.toJSONString(obj)，避免使用 Java 原生序列化（跨语言兼容性差）
微服务间调用	使用 FastJSON2 + HTTP Header Content-Type: application/json，避免使用 XML 或 Protobuf（除非极高性能要求）
配置文件读取	使用 JSON.parseObject(configJson, Config.class)，支持嵌套对象
日志记录	所有业务对象日志输出统一使用 JSON.toJSONString(obj, JSONWriter.Feature.WriteDateUseDateFormat)
安全规范	✅ 禁用 autoType；✅ 禁用 WriteClassName；✅ 对敏感字段使用 serialize=false
性能优化	✅ 复用 JSONWriter / JSONReader 实例（线程安全）；✅ 避免频繁 new JSON()
团队协作	✅ 制定《JSON 序列化规范文档》；✅ 使用 Lombok 简化 POJO；✅ 单元测试覆盖序列化边界值

---

七、迁移建议：从 FastJson 1.x 到 FastJson2

问题	解决方案
JSON.parseObject() 报错	替换为 com.alibaba.fastjson2.JSON（包名变更）
autoType 开启报错	删除所有 JSON.parseObject(json, Object.class)，必须指定具体类型
SerializerFeature 不存在	替换为 JSONWriter.Feature
Date 格式不一致	统一使用 JSONWriter.Feature.WriteDateUseDateFormat + format 注解
依赖冲突	Maven 中排除旧版 FastJson：<exclusion><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId></exclusion>

---

八、依赖配置（Maven / Gradle）

Maven

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.54</version> <!-- 推荐使用最新稳定版 -->
</dependency>

Gradle

implementation 'com.alibaba.fastjson2:fastjson2:2.0.54'

✅ 强烈建议：锁定版本号，避免自动升级引入不兼容变更。

---

九、总结：为什么 FastJson2 是你的首选？

维度	FastJson2 优势
性能	行业第一，适合高并发系统
安全	默认安全，无历史漏洞
标准	支持 Java 8+、ISO 8601、BigDecimal
易用	注解驱动，API 简洁，学习成本低
维护	阿里巴巴官方持续维护，社区活跃
企业落地	支持统一规范、可审计、可监控

✅ 结论：
FastJson2 是 Java 后端开发中 JSON 处理的“黄金标准”。
从今天起，淘汰 FastJson 1.x，统一使用 FastJson2，提升系统性能与安全性，推动团队技术升级。

---

🔚 附录：快速参考表（团队速查）

操作	代码示例
序列化对象	JSON.toJSONString(obj)
反序列化对象	JSON.parseObject(json, User.class)
序列化数组	JSON.toJSONString(list)
反序列化数组	JSON.parseArray(json, TargetClass.class)
忽略 null 字段	JSONWriter.Feature.WriteNulls, false
自定义日期格式	@JSONField(format = "yyyy-MM-dd HH:mm:ss")
禁用字段	@JSONField(serialize = false)
全局配置	JSONWriter.config(...)（启动时调用）

---

📌 团队落地建议：

1. 在团队 Wiki 建立《FastJson2 使用规范》文档
2. 在代码审查中强制检查：是否使用 JSON.toJSONString 而非 toString()
3. 对所有 Controller 返回对象添加 @JSONField 注解规范字段名
4. 每月进行一次安全扫描，确认无 FastJson 1.x 依赖残留

---