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]`)
|
- **注解**:`@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 // Option:Some→值,None→null
|
public var opt: ?String = None // Option:Some→值,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 test,16 用例)
|
├── macros/ // @SerializerParent 宏
|
||||||
└── macros/ // @SerializerParent 宏
|
│ └── SerializerParentMacro.cj
|
||||||
└── SerializerParentMacro.cj
|
└── tests/ // 单元测试(独立子包)
|
||||||
|
└── JsonSerializer_test.cj // cjpm test,18 用例
|
||||||
```
|
```
|
||||||
|
|
||||||
## 测试
|
## 测试
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cjpm test
|
cjpm test
|
||||||
# TOTAL: 16, PASSED: 16
|
# TOTAL: 18, PASSED: 18
|
||||||
```
|
```
|
||||||
|
|
||||||
覆盖:基础类型、对象字段输出、注解、Option、集合、HashMap、枚举、命名策略、
|
覆盖:基础类型、对象字段输出、注解、Option、集合、HashMap、枚举、命名策略、
|
||||||
父类字段(宏)、多层继承、maxDepth、宽松类型转换。
|
父类字段(宏)、多层继承、三级继承、maxDepth、宽松类型转换。
|
||||||
|
|
||||||
## 设计参考
|
## 设计参考
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user