FastJson2 完整使用指南（Java 后端企业级实战）

FastJson2 完整使用指南（Java 后端企业级实战） | 极客日志

FastJson2 完整使用指南

一、FastJson2 是什么？

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

二、FastJson2 有什么作用？

FastJson2 的核心作用是：

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

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

三、为什么需要使用 FastJson2？

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

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

2. 性能碾压竞品

根据官方基准测试：

工具	序列化速度（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 lombok.Data;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Arrays;

// 定义实体类（POJO）
@Data
public class User {
    private Long id;
    private String name;
    private String email;
    private LocalDateTime createTime;
}

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

        // 序列化：Java 对象 → JSON 字符串（默认格式化，可读性强）
        String jsonString = JSON.toJSONString(user);
        System.out.println("序列化结果：\n" + jsonString);

        // 反序列化：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());

        
        List<User> userList = Arrays.asList(user,  (, , , LocalDateTime.now()));
           JSON.toJSONString(userList);
        System.out.println( + userListJson);

        
        List<User> parsedList = JSON.parseArray(userListJson, User.class);
        System.out.println( + parsedList.size());
    }
}

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

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

import com.alibaba.fastjson2.annotation.JSONField;
import java.math.BigDecimal;
import java.time.LocalDateTime;

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)
    private String internalRemark;

    @JSONField(serialize = false, deserialize = false)
    private transient String password;

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

    // Getter/Setter 省略
}

// 使用示例
public class AnnotationDemo {
    public static void main(String[] args) {
        Order order = new Order(5001L, new BigDecimal(), LocalDateTime.of(, , , , , ), , );
           JSON.toJSONString(order);
        System.out.println( + json);

           JSON.parseObject(json, Order.class);
        System.out.println();
        System.out.println( + parsed.getOrderId());
        System.out.println( + parsed.getTotalAmount());
        System.out.println( + parsed.getCreateTime());
        System.out.println( + parsed.getInternalRemark());
    }
}

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

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

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONWriter;
import java.time.LocalDateTime;

public class GlobalConfigDemo {
    public static void main(String[] args) {
        // 设置全局配置：推荐在 Spring Boot 启动类或配置类中初始化一次
        JSONWriter.Feature[] features = {
            JSONWriter.Feature.WriteNulls,
            JSONWriter.Feature.WriteMapNullValue,
            JSONWriter.Feature.WriteClassName,
            JSONWriter.Feature.WriteDateUseDateFormat,
            JSONWriter.Feature.WriteNonStringKeyAsString
        };

        JSONWriter.Feature[] disableFeatures = {
            JSONWriter.Feature.WriteClassName
        };

        // 设置默认写入配置（推荐在项目初始化时调用）
        JSONWriter.config(JSONWriter.Feature.WriteDateUseDateFormat, true);
        JSONWriter.config(JSONWriter.Feature.WriteNulls, false);
        JSONWriter.config(JSONWriter.Feature.WriteMapNullValue, false);

        // 自定义日期格式（统一标准）
        JSONWriter.config(JSONWriter.Feature.WriteDateUseDateFormat, true);
        JSONWriter.config(JSONWriter.Feature.WriteDateAsJSONString, false);

        User user = new User(1001L, "王五", "[email protected]", LocalDateTime.now());
        String json = JSON.toJSONString(user);
        System.out.println("全局配置后输出：\n" + json);
    }
}

企业级建议：生产环境禁止 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;

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) {
            jsonWriter.write(bd.setScale(2, java.math.RoundingMode.HALF_UP).toPlainString());
        } else {
            jsonWriter.writeNull();
        }
    }
}

public class CustomSerializerDemo {
    public static void main(String[] args) {
        ObjectWriterProvider provider = new ObjectWriterProvider();
        provider.put(BigDecimal.class, BigDecimalSerializer.INSTANCE);

        JSONWriter writer = new (provider);
            (,  (), LocalDateTime.now(), , );
           writer.toJSONString(order);
        System.out.println( + json);
    }
}

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

六、企业级实战建议

场景	推荐做法
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 fastjson

八、依赖配置（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 优势
性能	行业第一，适合高并发系统
安全	默认安全，无历史漏洞
标准	支持 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(...)（启动时调用）

团队落地建议

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

FastJson2 完整使用指南（Java 后端企业级实战）