FastJson2.0实战：从1.x迁移到2.x的完整避坑指南（含Kotlin适配）

FastJson2.0实战：从1.x迁移到2.x的完整避坑指南（含Kotlin适配）

如果你正在维护一个使用了FastJson 1.x的Java或Kotlin项目，最近可能已经注意到官方推出了FastJson2.0版本。这个号称“为下一个十年设计”的JSON库，不仅性能大幅提升，还带来了JSONB、JSONPath等新特性，但同时也伴随着包名变更、API调整等一系列迁移挑战。我在最近的项目升级中，花了整整两周时间踩遍了几乎所有可能的坑，从最初的“这应该很简单”到后来的“原来还有这种问题”，最终总结出了一套相对平滑的迁移方案。

这篇文章就是我的实战记录，不仅会告诉你官方文档里写明的变化，更重要的是分享那些文档里没写、但实际迁移中一定会遇到的“暗坑”。无论你是Java开发者还是Kotlin用户，特别是那些在Spring Boot项目中深度集成FastJson的团队，这篇文章都能帮你少走弯路，高效完成迁移。

1. 迁移前的准备：理解2.0的核心变化

在开始动手修改代码之前，我们需要先搞清楚FastJson2.0到底带来了哪些根本性的变化。很多人以为只是换个依赖版本号，结果一升级项目就崩了，原因就在于没理解这些底层变更。

1.1 包名与Maven坐标的彻底变更

这是最明显也是最先遇到的坑。FastJson2.0不再使用com.alibaba.fastjson这个groupId，而是改成了com.alibaba.fastjson2。这意味着你项目里所有的import语句都需要修改。

1.x时代的依赖配置：

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

2.0时代的正确配置：

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

注意：版本号建议使用最新的稳定版，我写这篇文章时2.0.61是最新版本。你可以在Maven Central上查看最新版本。

这个变化带来的连锁反应是，你代码中所有的import com.alibaba.fastjson.*都需要改为import com.alibaba.fastjson2.*。听起来简单，但在大型项目中，这可能涉及上百个文件。更麻烦的是，有些第三方库可能还在内部使用1.x版本，这就可能产生版本冲突。

1.2 性能架构的底层重构

FastJson2.0在性能上的提升不是简单的优化，而是架构层面的重构。官方基准测试显示，在某些场景下性能提升可达2-3倍。这主要得益于：

• 全新的内存管理策略：减少了GC压力，特别是在处理大JSON时效果明显
• 更高效的序列化算法：对常见数据类型做了特殊优化
• 支持Record类型：对Java 14+的Record类有原生支持
• Compact Strings优化：充分利用了JDK的字符串压缩特性

但性能提升也带来了一些行为上的变化。比如，2.0在某些边界条件下的处理逻辑与1.x不同，这可能导致原本“能跑”的代码在2.0下抛出异常。

1.3 新特性概览：不只是性能提升

除了性能，2.0还引入了一些重要的新特性：

这些新特性意味着，迁移到2.0不仅仅是“保持功能不变”，更是获得新能力的机会。特别是JSONB格式，对于需要频繁传输JSON数据的微服务场景，能显著降低网络开销。

2. 基础迁移步骤：从修改依赖开始

了解了核心变化后，我们开始实际的迁移工作。我建议按照以下顺序进行，这样可以最小化风险。

2.1 依赖管理策略

在大型项目中，直接替换依赖可能会导致不可预知的问题。我推荐采用渐进式迁移策略：

第一步：添加2.0依赖，暂时保留1.x

<!-- 先添加2.0，但先不删除1.x -->
<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.61</version>
</dependency>

<!-- 1.x版本暂时保留，用于兼容性测试 -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version>
    <scope>test</scope>  <!-- 先放到test范围 -->
</dependency>

这样做的目的是让新旧版本在测试环境中共存，方便对比行为差异。等所有测试通过后，再彻底移除1.x依赖。

第二步：使用兼容包（如果需要） 如果你有大量遗留代码，或者迁移时间紧迫，可以考虑使用官方提供的兼容包：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.61</version>  <!-- 注意：这是兼容包，不是1.x -->
</dependency```

这个兼容包使用了1.x的groupId，但内部实现是2.0。它能最大程度减少代码修改，但官方明确说明“不能保证100%兼容”，所以还是需要充分测试。

### 2.2 包名修改的自动化方案

手动修改上百个文件的import语句既枯燥又容易出错。我推荐几种自动化方案：

**方案一：IDE的批量替换**
大多数现代IDE都支持项目级别的查找替换。在IntelliJ IDEA中：
1. 按`Ctrl+Shift+R`（Windows/Linux）或`Cmd+Shift+R`（Mac）打开替换对话框
2. 查找：`import com.alibaba.fastjson`
3. 替换为：`import com.alibaba.fastjson2`
4. 选择“在项目中”范围，然后执行

**方案二：使用sed命令（Linux/Mac）**
```bash
find . -name "*.java" -type f -exec sed -i '' 's/import com\.alibaba\.fastjson/import com.alibaba.fastjson2/g' {} +

方案三：Gradle/Maven插件 如果你使用构建工具，可以考虑编写自定义任务：

// Gradle示例
task replaceFastJsonImports {
    doLast {
        fileTree(dir: 'src', include: '**/*.java').each { file ->
            def text = file.text
            text = text.replaceAll('import com\\.alibaba\\.fastjson', 'import com.alibaba.fastjson2')
            file.write(text)
        }
    }
}

无论用哪种方法，替换后一定要仔细检查，特别是：

• 静态导入是否正确处理：import static com.alibaba.fastjson.JSON.*
• 泛型中的类型引用：TypeReference<T>也需要修改
• 注释中的示例代码（避免误替换）

2.3 基础API的对应关系

包名改完后，你会发现大部分基础API的用法基本没变，但有些细节需要注意：

序列化（对象转JSON）的变化：

// 1.x写法（还能用，但建议改用新API）
String json = JSON.toJSONString(user);

// 2.0推荐写法（性能更好）
String json = JSON.toJSONString(user);
byte[] bytes = JSON.toJSONBytes(user);  // 新增：直接转字节数组

// 带特性的序列化
String json = JSON.toJSONString(user, 
    JSONWriter.Feature.PrettyFormat,      // 美化输出
    JSONWriter.Feature.WriteMapNullValue, // 输出null值
    JSONWriter.Feature.WriteNullListAsEmpty  // 空列表输出为[]
);

反序列化（JSON转对象）的变化：

// 1.x写法
User user = JSON.parseObject(jsonString, User.class);
List<User> users = JSON.parseArray(jsonArrayString, User.class);

// 2.0写法（完全兼容）
User user = JSON.parseObject(jsonString, User.class);
List<User> users = JSON.parseArray(jsonArrayString, User.class);

// 新增：从字节数组解析
User user = JSON.parseObject(jsonBytes, User.class);

JSONObject/JSONArray API变化： 大部分方法都保持兼容，但有些方法被标记为过时（deprecated）。比如：

// 1.x中常用的方法，在2.0中仍然可用
JSONObject obj = JSON.parseObject(jsonString);
String name = obj.getString("name");
int age = obj.getIntValue("age");

// 但建议使用新的fluent API
String name = obj.getString("name", "default");  // 带默认值
Integer age = obj.getInteger("age");  // 返回Intege