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