This is an automated email from the ASF dual-hosted git repository.
funky-eyes pushed a commit to branch docusaurus
in repository https://gitbox.apache.org/repos/asf/incubator-seata-website.git
The following commit(s) were added to refs/heads/docusaurus by this push:
new 098feb2113d feat(docs):add json-common config docs (#1080)
098feb2113d is described below
commit 098feb2113dfa557ce98478f1056c55f025037aa
Author: legendpei <[email protected]>
AuthorDate: Sat May 30 21:06:35 2026 +0800
feat(docs):add json-common config docs (#1080)
---
.../current/ops/upgrade.md | 19 ++++++
.../current/overview/faq.md | 72 ++++++++++++++++++++++
.../current/ops/upgrade.md | 20 ++++++
.../current/overview/faq.md | 72 ++++++++++++++++++++++
4 files changed, 183 insertions(+)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/ops/upgrade.md
b/i18n/en/docusaurus-plugin-content-docs/current/ops/upgrade.md
index 3fbfe5be9d4..367fb7a4120 100644
--- 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
index 6c7e4a0a89d..ad7e362fa30 100644
--- 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
index 8f775098b9d..f355b9bbd35 100644
--- 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
index 9e3b21b576a..0c7a5086b8a 100644
--- 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`。
+
+---
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
