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;
@Data
public class User {
private Long id;
private String name;
private String email;
private LocalDateTime createTime;
}
public class FastJSON2Demo {
public static void main(String[] args) {
User user = new User(1001L, "张三", "[email protected]", LocalDateTime.now());
String jsonString = JSON.toJSONString(user);
System.out.println("序列化结果:\n" + jsonString);
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;
}
}
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) {
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 依赖残留