docs: 更新 README——任意字段名、TypeInfo 版 Deserialize、18 用例、tests 子包

This commit is contained in:
2026-08-18 02:08:00 +08:00
parent 7017b6b027
commit 455df5115b
+28 -10
View File
@@ -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 // OptionSome→值,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 test16 用例)
└── macros/ // @SerializerParent
└── SerializerParentMacro.cj
── JsonOption.cj
├── macros/ // @SerializerParent 宏
└── SerializerParentMacro.cj
└── tests/ // 单元测试(独立子包)
└── JsonSerializer_test.cj // cjpm test18 用例
```
## 测试
```bash
cjpm test
# TOTAL: 16, PASSED: 16
# TOTAL: 18, PASSED: 18
```
覆盖:基础类型、对象字段输出、注解、Option、集合、HashMap、枚举、命名策略、
父类字段(宏)、多层继承、maxDepth、宽松类型转换。
父类字段(宏)、多层继承、三级继承、maxDepth、宽松类型转换。
## 设计参考