From 455df5115b02d417021d7bfbad25fd0071aee495 Mon Sep 17 00:00:00 2001
From: xRain <xrain@simcu.com>
Date: Tue, 18 Aug 2026 02:08:00 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=E2=80=94?=
 =?UTF-8?q?=E2=80=94=E4=BB=BB=E6=84=8F=E5=AD=97=E6=AE=B5=E5=90=8D=E3=80=81?=
 =?UTF-8?q?TypeInfo=20=E7=89=88=20Deserialize=E3=80=8118=20=E7=94=A8?=
 =?UTF-8?q?=E4=BE=8B=E3=80=81tests=20=E5=AD=90=E5=8C=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 38 ++++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 55559b3..1f85586 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@ SimApi 全反射 JSON 序列化库（仓颉版），对齐 .NET `System.Text.Jso
 - **注解**：`@SerializerPropertyName` / `@SerializerIgnore`（对齐 `[JsonPropertyName]` / `[JsonIgnore]`）
 - **继承支持**：`@SerializerParent` 宏解决父类字段序列化（Cangjie 反射限制）
 - **API 对齐**：`JsonSerializer.Serialize(obj, JsonOption)` / `Deserialize<T>(json, JsonOption)`
+- **字段名**：`_` 前缀与无下划线字段均支持（`_name` 原样输出 `_name`，`name` 输出 `name`）
 
 ## 快速开始
 
@@ -27,7 +28,7 @@ class User {
     public var _name: String = ""
     public var _age: Int64 = 0
     public var active: Bool = true
-    public var _role: Role = Role.User     // 枚举 → 名字字符串
+    public var _role: Role = Role.Member   // 枚举 → 名字字符串
     public var opt: ?String = None         // Option：Some→值，None→null
     public var _tags: Array<String> = []
     public var addr: Address = Address()   // 嵌套对象
@@ -38,12 +39,14 @@ u._name = "alice"
 u._age = 30
 
 let json = JsonSerializer.Serialize(u)
-// { "_name": "alice", "_age": 30, "active": true, "_role": "User", "opt": null, "_tags": [], "addr": {...} }
+// { "_name": "alice", "_age": 30, "active": true, "_role": "Member", "opt": null, "_tags": [], "addr": {...} }
 
 let u2 = JsonSerializer.Deserialize<User>(json)
 // 全部字段回填
 ```
 
+> 类无需显式 `public init() {}`——编译器自动提供无参构造（反射构造已验证）。
+
 ### 注解
 
 ```cangjie
@@ -88,6 +91,8 @@ let json = JsonSerializer.Serialize(u)
 // 输出包含父类字段：{ "_name": "alice", "_id": "u-1", "_createdAt": "" }
 ```
 
+> 宏支持**任意字段名**（`_` 前缀或无下划线均可），只需有类型注解。
+
 ### 特性
 
 | 特性 | 说明 |
@@ -95,6 +100,7 @@ let json = JsonSerializer.Serialize(u)
 | 自动补 `open` | 非 open 类标注宏后自动可继承 |
 | 多层继承 | 沿 `superClass` 链逐层调用；中间层无宏自动跳过 |
 | 注解生效 | 父类字段的 `@SerializerPropertyName` / `@SerializerIgnore` 同样生效 |
+| 任意字段名 | `_` 前缀与无下划线字段都处理 |
 | 向后兼容 | 无宏的类行为不变 |
 
 ### 宏生成的方法
@@ -121,6 +127,17 @@ opt.maxDepth = 16
 let json = JsonSerializer.Serialize(u, opt)
 ```
 
+### 运行时类型反序列化（框架绑定用）
+
+供框架模型绑定等场景按运行时类型反序列化（无需编译期泛型）：
+
+```cangjie
+import std.reflect.*
+
+let typeInfo = TypeInfo.of<MyDto>()
+let obj: Any = JsonSerializer.Deserialize(typeInfo, jsonString)
+```
+
 ### 命名策略（PropertyNamingPolicy）
 
 | 策略 | 效果 |
@@ -150,7 +167,7 @@ JSON 数字 ↔ 字符串字段自动互转：`Deserialize<String>("42")` → `"
 ## 已知限制
 
 - 父类字段序列化需父类标注 `@SerializerParent`（见上文；Cangjie 反射平台限制）
-- 反序列化要求目标类型**无参构造**、字段为 `var`（`let` 只读字段跳过）
+- 反序列化要求目标类型**无参构造**（编译器自动提供，无需显式写 `init(){}`）、字段为 `var`（`let` 只读字段跳过）
 - 集合/字典元素类型需为支持的类型
 - 泛型父类暂不支持
 
@@ -164,23 +181,24 @@ src/
 │   ├── ReflectionCache.cj      // 字段元数据 + 继承链缓存
 │   └── NamingPolicy.cj         // PropertyNamingPolicy
 ├── json/                       // JSON 序列化
-│   ├── JsonSerializer.cj       // 公开 API
+│   ├── JsonSerializer.cj       // 公开 API（含 TypeInfo 版 Deserialize）
 │   ├── JsonWriter.cj / JsonReader.cj
-│   ├── JsonOption.cj
-│   └── JsonSerializer_test.cj  // 单元测试（cjpm test，16 用例）
-└── macros/                     // @SerializerParent 宏
-    └── SerializerParentMacro.cj
+│   └── JsonOption.cj
+├── macros/                     // @SerializerParent 宏
+│   └── SerializerParentMacro.cj
+└── tests/                      // 单元测试（独立子包）
+    └── JsonSerializer_test.cj  // cjpm test，18 用例
 ```
 
 ## 测试
 
 ```bash
 cjpm test
-# TOTAL: 16, PASSED: 16
+# TOTAL: 18, PASSED: 18
 ```
 
 覆盖：基础类型、对象字段输出、注解、Option、集合、HashMap、枚举、命名策略、
-父类字段（宏）、多层继承、maxDepth、宽松类型转换。
+父类字段（宏）、多层继承、三级继承、maxDepth、宽松类型转换。
 
 ## 设计参考