docs: 更新 README——任意字段名、TypeInfo 版 Deserialize、18 用例、tests 子包
This commit is contained in:
@@ -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、宽松类型转换。
|
||||
|
||||
## 设计参考
|
||||
|
||||
|
||||
Reference in New Issue
Block a user