feat(docs):add json-common config docs (#1080)

LegendPei · web-flow · commit 098feb2113df · 2026-05-30T21:06:35.000+08:00
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/ops/upgrade.md b/i18n/en/docusaurus-plugin-content-docs/current/ops/upgrade.md
@@ -6,6 +6,9 @@ description: Seata upgrade.
 
 # Version Upgrade Guide
 
+<a href="#12" target="_self">12. What compatibility matters need to be paid attention to when upgrading to seata 2.7? </a>
+<br/>
+
 <a href="#11" target="_self">11. What compatibility matters need to be paid attention to when upgrading to seata 2.5? </a>
 <br/>
 
@@ -39,6 +42,22 @@ description: Seata upgrade.
 <a href="#1" target="_self">1. How to upgrade versions 0.8 and 0.9 to version 1.0? </a>
 <br/>
 
+------
+<h3 id='12'>12. What compatibility matters need to be paid attention to when upgrading to seata 2.7?</h3>
+<details>
+   <summary><mark>Notes</mark></summary>
+
+   1. Seata 2.7 introduces a unified JSON module, `json-common`, to centralize internal JSON serialization, deserialization, and security control capabilities.
+   2. The default JSON serializer is now `jackson`. If no JSON serializer is explicitly configured, `JsonUtil` resolves to `jackson`.
+   3. The JSON serializer should be switched through the Spring Boot property `seata.json.serializer-type` or the native Seata property `json.serializerType`, with supported values `jackson`, `fastjson`, `fastjson2`, `gson`, and `jackson3`.
+   4. Seata 2.7 adds support for `fastjson2` and `jackson3`. If you plan to enable `jackson3`, the runtime environment must be JDK 17 or later.
+   5. If `jackson3` is configured but its implementation is not available in the current environment, Seata will automatically fall back to `jackson`.
+   6. Seata 2.7 introduces a JSON deserialization allowlist mechanism. If a business object is deserialized from JSON with type information and the target class is not in the allowlist, you may see a `Class not in JSON deserialization allowlist` exception.
+   7. To allow custom business classes, you can extend the allowlist with `seata.json.allowlist=com.example.order.,com.example.dto.,com.example.CustomContext`; a value ending with `.` means package prefix matching, while a value without `.` means exact class name matching.
+   8. The default allowlist already includes common JDK primitive types, collection types, time types, and the package prefixes `org.apache.seata.` and `io.seata.`.
+   9. The old TCC-specific properties `seata.tcc.context-json-parser-type` / `tcc.contextJsonParserType` are still read as a compatibility fallback, but they have been deprecated since 2.7.0. If both old and new properties exist, the new `json.serializerType` takes precedence.
+</details>
+
 ------
 <h3 id='11'>11. What compatibility matters need to be paid attention to when upgrading to seata 2.5?</h3>
 <details>
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/overview/faq.md b/i18n/en/docusaurus-plugin-content-docs/current/overview/faq.md
@@ -147,6 +147,18 @@ Error: A fatal exception has occurred. Program will exit.?</a>
 <a href="#46" target="_self">46. Why does Seata report LockWaitTimeoutException due to table name case sensitivity in global transaction lock reentrancy? </a>
 <br/>
 
+<a href="#47" target="_self">47. What is `json-common` used for?</a>
+<br/>
+
+<a href="#48" target="_self">48. Do I have to switch to `fastjson2` or `jackson3` after upgrading to 2.7?</a>
+<br/>
+
+<a href="#49" target="_self">49. In what scenarios should I pay attention to the JSON deserialization allowlist?</a>
+<br/>
+
+<a href="#50" target="_self">50. When is it appropriate to use `jackson3`?</a>
+<br/>
+
 ---
 
 <h3 id='1'>Q: 1.Can Seata be used in a production environment?</h3>
@@ -773,3 +785,63 @@ public class SetSeataInterceptor implements RequestInterceptor {
 - Remove useOldAliasMetadataBehavior=true from your MySQL JDBC URL or set it to false.
 
 ---
+
+<h3 id='47'>Q: 47. What is `json-common` used for?</h3>
+
+**A:** `json-common` is Seata's unified JSON abstraction layer. It centralizes Seata's internal JSON SPI, utility classes, and security checks. The most direct current use case is JSON serialization and deserialization for TCC `BusinessActionContext`.
+
+It mainly serves three purposes:
+
+1. Unify JSON implementation selection, supporting `fastjson`, `fastjson2`, `jackson`, `jackson3`, and `gson`
+2. Provide a unified entry for internal JSON serialization and deserialization in Seata
+3. Add allowlist-based security control for deserialization with type information
+
+---
+
+<h3 id='48'>Q: 48. Do I have to switch to `fastjson2` or `jackson3` after upgrading to 2.7?</h3>
+
+**A:** No. The default JSON serializer is now `jackson`. The introduction of `json-common` is primarily for capability unification and stronger security controls, not to force an immediate switch to `fastjson2` or `jackson3` during upgrade.
+
+If you want to switch the JSON serializer, Spring Boot applications should use:
+
+```yaml
+seata:
+  json:
+    serializer-type: fastjson2
+```
+
+Native Seata configuration should use:
+
+```properties
+json.serializerType=fastjson2
+```
+
+The old TCC-specific properties `seata.tcc.context-json-parser-type` / `tcc.contextJsonParserType` are still read as a compatibility fallback, but they have been deprecated since 2.7.0.
+
+---
+
+<h3 id='49'>Q: 49. In what scenarios should I pay attention to the JSON deserialization allowlist?</h3>
+
+**A:** Pay special attention in the following scenarios:
+
+1. Custom business objects are stored in the TCC context
+2. Your business relies on type metadata such as `@type` to restore concrete subclasses
+3. Extensions directly use Seata's JSON SPI for deserialization with type information
+
+If you see a `Class not in JSON deserialization allowlist` exception after upgrading, add the corresponding business classes to `seata.json.allowlist`, for example:
+
+```properties
+seata.json.allowlist=com.example.order.,com.example.tcc.,com.example.CustomContext
+```
+
+Here, a value ending with `.` means package prefix matching, while a value without `.` means exact class name matching.
+
+---
+
+<h3 id='50'>Q: 50. When is it appropriate to use `jackson3`?</h3>
+
+**A:** You can consider enabling `jackson3` when your runtime environment is already JDK 17 or later and you want to use the Jackson 3 ecosystem. If you still have JDK 8 or JDK 11 environments, it is better not to switch yet.
+
+If `jackson3` is configured but its implementation is not available in the current environment, Seata will automatically fall back to `jackson`.
+
+---
diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/ops/upgrade.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/ops/upgrade.md
@@ -6,6 +6,9 @@ description: Seata upgrade.
 
 # 版本升级指南
 
+<a href="#12" target="_self">12. 升级到 seata 2.7 有哪些兼容性事项是需要注意的？</a>
+<br/>
+
 <a href="#11" target="_self">11. 升级到 seata 2.5 有哪些兼容性事项是需要注意的？</a>
 <br/>
 
@@ -42,6 +45,23 @@ description: Seata upgrade.
 
 ------
 
+<h3 id='12'>12. 升级到 seata 2.7 有哪些兼容性事项是需要注意的？</h3>
+<details>
+  <summary><mark>注意事项</mark></summary>
+
+  1. Seata 2.7 新增统一 JSON 模块 `json-common`，用于统一 Seata 内部的 JSON 序列化、反序列化和安全控制能力。
+  2. 当前默认 JSON 序列化器为 `jackson`。未显式配置 JSON 序列化器时，`JsonUtil` 会解析为 `jackson`。
+  3. JSON 序列化器推荐通过 Spring Boot 配置 `seata.json.serializer-type` 或 Seata 原生配置 `json.serializerType` 切换，可选值为 `jackson`、`fastjson`、`fastjson2`、`gson`、`jackson3`。
+  4. Seata 2.7 新增 `fastjson2` 和 `jackson3` 支持；如果计划启用 `jackson3`，运行环境需要为 JDK 17 及以上。
+  5. 如果配置了 `jackson3`，但当前环境中 `jackson3` 实现不可用，Seata 会自动降级到 `jackson`。
+  6. Seata 2.7 新增 JSON 反序列化 allowlist 机制。若业务对象通过带类型信息的 JSON 参与反序列化，而目标类不在 allowlist 中，可能出现 `Class not in JSON deserialization allowlist` 异常。
+  7. 如需放行业务自定义类，可通过 `seata.json.allowlist=com.example.order.,com.example.dto.,com.example.CustomContext` 补充 allowlist；以 `.` 结尾表示包前缀匹配，不以 `.` 结尾表示精确类名匹配。
+  8. 默认 allowlist 已包含常见 JDK 基础类型、集合类型、时间类型，以及 `org.apache.seata.` 和 `io.seata.` 包前缀。
+  9. 旧的 TCC 专用配置 `seata.tcc.context-json-parser-type` / `tcc.contextJsonParserType` 仍可作为兼容兜底读取，但从 2.7.0 起已废弃；如果新旧配置同时存在，优先使用新的 `json.serializerType`。
+</details>
+
+------
+
 <h3 id='11'>11. 升级到 seata 2.5 有哪些兼容性事项是需要注意的？</h3>
 <details>
   <summary><mark>注意事项</mark></summary>
diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/overview/faq.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/overview/faq.md
@@ -147,6 +147,18 @@ Error: A fatal exception has occurred. Program will exit.导致 seata-server 无
 <a href="#46" target="_self">46. Seata 全局事务锁重入时，为什么会因表名大小写问题报 LockWaitTimeoutException？ </a>
 <br/>
 
+<a href="#47" target="_self">47. `json-common` 是用来做什么的？</a>
+<br/>
+
+<a href="#48" target="_self">48. 升级到 2.7 后必须切换到 `fastjson2` 或 `jackson3` 吗？</a>
+<br/>
+
+<a href="#49" target="_self">49. 什么场景下需要关注 JSON 反序列化 allowlist？</a>
+<br/>
+
+<a href="#50" target="_self">50. 什么时候适合使用 `jackson3`？</a>
+<br/>
+
 ---
 
 <h3 id='1'>Q: 1.Seata 目前可以用于生产环境吗？</h3>
@@ -770,3 +782,63 @@ public class SetSeataInterceptor implements RequestInterceptor {
 - 从 MySQL JDBC 连接 URL 中移除`useOldAliasMetadataBehavior=true`参数，或将其设置为`false`。
 
 ---
+
+<h3 id='47'>Q: 47. `json-common` 是用来做什么的？</h3>
+
+**A:** `json-common` 是 Seata 的统一 JSON 抽象层，用来统一 Seata 内部的 JSON SPI、工具类和安全校验逻辑。当前最直接的使用场景是 TCC `BusinessActionContext` 的 JSON 序列化与反序列化。
+
+它主要有三个作用：
+
+1. 统一 JSON 实现选择，支持 `fastjson`、`fastjson2`、`jackson`、`jackson3`、`gson`
+2. 统一 Seata 内部 JSON 的序列化和反序列化入口
+3. 为带类型信息的反序列化增加 allowlist 安全控制
+
+---
+
+<h3 id='48'>Q: 48. 升级到 2.7 后必须切换到 `fastjson2` 或 `jackson3` 吗？</h3>
+
+**A:** 不需要。当前默认 JSON 序列化器为 `jackson`。`json-common` 的引入首先是为了统一能力和增强安全控制，不要求用户在升级时立刻切换到 `fastjson2` 或 `jackson3`。
+
+如果需要切换 JSON 序列化器，Spring Boot 应用推荐使用：
+
+```yaml
+seata:
+  json:
+    serializer-type: fastjson2
+```
+
+Seata 原生配置推荐使用：
+
+```properties
+json.serializerType=fastjson2
+```
+
+旧的 TCC 专用配置 `seata.tcc.context-json-parser-type` / `tcc.contextJsonParserType` 仍可作为兼容兜底读取，但从 2.7.0 起已废弃。
+
+---
+
+<h3 id='49'>Q: 49. 什么场景下需要关注 JSON 反序列化 allowlist？</h3>
+
+**A:** 下面这些场景需要重点关注：
+
+1. 业务自定义对象被放入 TCC 上下文
+2. 业务依赖 `@type` 等类型信息恢复具体子类
+3. 扩展模块直接调用 Seata JSON SPI 做带类型反序列化
+
+如果升级后出现 `Class not in JSON deserialization allowlist` 异常，需要把对应业务类加入 `seata.json.allowlist`，例如：
+
+```properties
+seata.json.allowlist=com.example.order.,com.example.tcc.,com.example.CustomContext
+```
+
+其中，以 `.` 结尾表示包前缀匹配，不以 `.` 结尾表示精确类名匹配。
+
+---
+
+<h3 id='50'>Q: 50. 什么时候适合使用 `jackson3`？</h3>
+
+**A:** 当运行环境已经是 JDK 17 及以上，并且希望使用 Jackson 3 生态时，可以考虑启用 `jackson3`。如果仍然存在 JDK 8 或 JDK 11 环境，建议先不要切换。
+
+如果配置了 `jackson3`，但当前环境中 `jackson3` 实现不可用，Seata 会自动降级到 `jackson`。
+
+---
