cangjie_stdx 中的 ToJson 接口:JsonValue 与 DataModel 双向转换实战指南
cangjie_stdx 中的 ToJson 接口:JsonValue 与 DataModel 双向转换实战指南
导读:本文围绕 cangjie_stdx 中
stdx.encoding.json包的ToJson接口展开,深入解析其如何打通 JSON 数据(JsonValue)与中间数据模型(DataModel)之间的双向转换。读者将掌握ToJson接口的定义、DataModel扩展实现的底层映射逻辑,并学会借助 serialization 包完成"自定义类型 ⇄ JSON 字符串"的完整序列化闭环。
1. ToJson 接口概览
在 stdx.encoding.json 包中,ToJson 接口承担着"桥梁"角色:它定义了 JsonValue 与 DataModel 之间的双向转换协议。该接口声明位于源码 src/stdx/encoding/json/to_json.cj,完整签名如下:
public interface ToJson {
static func fromJson(jv: JsonValue): DataModel
func toJson(): JsonValue
}
接口包含两个成员,职责恰好相反:
| 成员 | 签名 | 方向 | 功能 |
|---|---|---|---|
fromJson(jv) |
static func fromJson(jv: JsonValue): DataModel |
JSON → 数据模型 | 将 JsonValue 转换为 DataModel 对象 |
toJson() |
func toJson(): JsonValue |
数据模型 → JSON | 将自身转换为 JsonValue |
在 json 包总览文档 的 API 列表中,ToJson 是全包唯一的接口类型,被明确标注为"用于实现 JsonValue 和 DataModel 的相互转换"。理解这两个概念,是掌握该接口的前提:
- JsonValue:
stdx.encoding.json包对 JSON 数据格式的封装,覆盖 object、array、string、number、true、false、null 七种形态,其抽象基类与JsonKind枚举定义于 src/stdx/encoding/json/json_value.cj,具体实现类包括JsonObject、JsonArray、JsonString、JsonInt、JsonFloat、JsonBool、JsonNull。 - DataModel:
stdx.serialization.serialization包中的抽象中间数据层,定义于 src/stdx/serialization/serialization/data_model.cj,其子类DataModelNull、DataModelBool、DataModelInt、DataModelFloat、DataModelString、DataModelSeq、DataModelStruct分别对应标量、序列与结构体三类数据形态,与Serializable<T>接口(serializable.cj)配合,构成"自定义类型 → DataModel"的通用序列化模型。
2. 接口成员详解
2.1 static func fromJson(JsonValue)
static func fromJson(jv: JsonValue): DataModel
- 参数:
jv—— 待转换的 JsonValue 实例。 - 返回值:转换得到的 DataModel 对象。
- 语义:作为静态方法,它接收一个已解析完成的 JsonValue(典型来源是
JsonValue.fromStr(s),见 json_value.cj),将其整体"降级"为与序列化框架统一的 DataModel 表示。
2.2 func toJson()
func toJson(): JsonValue
- 返回值:转换得到的 JsonValue。
- 异常:转换失败时抛出 JsonException(该类定义于 src/stdx/encoding/json/json_exception.cj,带可选的
message参数)。 - 语义:作为实例方法,它把当前 DataModel 对象包装成对应的 JsonValue,供后续
toString()/toJsonString()等输出方法消费。
3. DataModel 的 ToJson 扩展实现
接口本身只有声明,真正可用的转换逻辑来自 extend DataModel <: ToJson 扩展。该扩展同样位于 src/stdx/encoding/json/to_json.cj,声明形式为:
extend DataModel <: ToJson
其父类型为 ToJson 接口本身。通过扩展,所有 DataModel 及其子类实例无需修改 serialization 包,即可直接获得 JSON 双向转换能力——这正是"以 json 包为桥梁、以扩展机制为手段"的模块解耦设计。
3.1 扩展实现:fromJson 的映射规则
public static func fromJson(jv: JsonValue): DataModel 的核心是 match 模式匹配,把七种 JsonValue 形态逐一映射到 DataModel 子类:
public static func fromJson(jv: JsonValue): DataModel {
match (jv) {
case jb: JsonBool => DataModelBool(jb.getValue())
case ji: JsonInt => DataModelInt(ji.getValue())
case jf: JsonFloat => DataModelFloat(jf.getValue())
case js: JsonString => DataModelString(js.getValue())
case ja: JsonArray => buildDMSeq(ja)
case jo: JsonObject => buildDMStruct(jo)
case _ => DataModelNull()
}
}
对应的完整映射表(依据 to_json.cj 源码):
| JsonValue 形态 | 映射结果 | 说明 |
|---|---|---|
JsonBool |
DataModelBool |
布尔值直通 |
JsonInt |
DataModelInt |
64 位整数直通 |
JsonFloat |
DataModelFloat |
浮点数直通 |
JsonString |
DataModelString |
字符串直通 |
JsonArray |
DataModelSeq |
走 buildDMSeq(ja) 递归 |
JsonObject |
DataModelStruct |
走 buildDMStruct(jo) 递归 |
其他(含 JsonNull) |
DataModelNull |
兜底为 null |
递归处理容器是 fromJson 的关键设计:
buildDMSeq(ja)(to_json.cj):创建DataModelSeq,遍历JsonArray的每一项元素并递归调用fromJson,将结果加入序列;转换前先list.reserve(ji.size)预分配容量,避免列表扩容开销。buildDMStruct(jo)(to_json.cj):创建DataModelStruct,遍历JsonObject的键值对,每个键值递归转换为Field(str, dm)后加入字段列表;若遇到无法匹配的 JsonValue 类型,则抛出JsonException("Internal error: unmatched JsonValue type.")。
从源码结构可以看出,fromJson 对嵌套 JSON(数组套对象、对象套数组)具备天然的支持能力,这与 json_value_sample.md 中展示的深层嵌套 JSON 解析场景相印证。
3.2 扩展实现:toJson 的映射规则
public func toJson(): JsonValue 是 fromJson 的逆操作,同样基于 match:
public func toJson(): JsonValue {
match (this) {
case _: DataModelNull => return JsonNull()
case dmb: DataModelBool => return JsonBool(dmb.getValue())
case dmi: DataModelInt => return JsonInt(dmi.getValue())
case dmf: DataModelFloat => return JsonFloat(dmf.getValue())
case dmstr: DataModelString => return JsonString(dmstr.getValue())
case dmseq: DataModelSeq => return toJson(dmseq)
case dms: DataModelStruct => return toJson(dms)
case _ => throw JsonException("Internal error: unmatched DataModel type.")
}
}
映射表(依据 to_json.cj 源码):
| DataModel 形态 | 映射结果 | 说明 |
|---|---|---|
DataModelNull |
JsonNull() |
空值 |
DataModelBool |
JsonBool(...) |
布尔值直通 |
DataModelInt |
JsonInt(...) |
整数直通 |
DataModelFloat |
JsonFloat(...) |
浮点数直通 |
DataModelString |
JsonString(...) |
字符串直通 |
DataModelSeq |
JsonArray |
走私有 toJson(dmseq) |
DataModelStruct |
JsonObject |
走私有 toJson(dms) |
| 其他 | 抛 JsonException |
兜底报错 |
容器方向的逆递归同样成对存在:
toJson(dmseq)(to_json.cj):遍历DataModelSeq的 items,逐个调用元素自身的toJson()后add进JsonArray。toJson(dms)(to_json.cj):遍历DataModelStruct的字段列表,将Field的键名与递归转换后的值通过jo.put(fie.getName(), value)写入JsonObject。
需要特别注意的是 DataModelStruct.toJson() 对字段值的处理:字段值本身就是 DataModel,直接调用 fie.getData().toJson() 即可,因此任意深度的嵌套结构体都能被完整还原为 JSON。
4. 实战:自定义类型与 JSON 字符串的完整转换闭环
仅看接口本身不足以体现价值,将 ToJson 与 serialization 包的 Serializable<T> 接口串联,才能实现真正的业务闭环。完整示例来自 json_samples/to_json_sample.md,其工作流可概括为:
JSON 字符串 → JsonValue.fromStr → JsonValue → DataModel.fromJson → DataModel
→ Person.deserialize → 自定义类型实例 → person.serialize → DataModel
→ DataModel.toJson → JsonValue → toJsonString → JSON 字符串
4.1 定义实现 Serializable 的自定义类型
首先为业务类实现 Serializable<T> 接口(该接口定义于 serializable.cj,要求实现 serialize(): DataModel 与 static deserialize(dm: DataModel): T):
import stdx.serialization.serialization.*
import stdx.encoding.json.*
// 定义 Location 类,实现 Serializable 接口
class Location <: Serializable<Location> {
var country: String = ""
var province: String = ""
public func serialize(): DataModel {
return DataModelStruct().add(field<String>("country", country)).add(field<String>("province", province))
}
public static func deserialize(dm: DataModel): Location {
let dms = match (dm) {
case data: DataModelStruct => data
case _ => throw Exception("this data is not DataModelStruct")
}
let result = Location()
result.country = String.deserialize(dms.get("country"))
result.province = String.deserialize(dms.get("province"))
return result
}
}
// 定义 Person 类,实现 Serializable 接口(含嵌套 Location 字段)
class Person <: Serializable<Person> {
var name: String = ""
var age: Int64 = 0
var loc: Option<Location> = Option<Location>.None
public func serialize(): DataModel {
return DataModelStruct()
.add(field<String>("name", name))
.add(field<Int64>("age", age))
.add(field<Option<Location>>("loc", loc))
}
public static func deserialize(dm: DataModel): Person {
let dms = match (dm) {
case data: DataModelStruct => data
case _ => throw Exception("this data is not DataModelStruct")
}
let result = Person()
result.name = String.deserialize(dms.get("name"))
result.age = Int64.deserialize(dms.get("age"))
result.loc = Option<Location>.deserialize(dms.get("loc"))
return result
}
}
可以看到,serialize() 借助 field<K>("键名", 值) 构造字段,deserialize() 则用 dms.get("键名") 取值并调用对应类型的 deserialize 还原。Option<Location> 这类容器类型同样具备 Serializable 扩展(见 serializable.cj),因此嵌套与可空字段都能被正确处理。
4.2 反序列化:JSON 字符串 → 自定义类型
main() {
// 准备 JSON 字符串
let jsonString = ##"{
"name": "A",
"age": 30,
"loc": {
"country": "China",
"province": "Beijing"
}
}"##
// 从 JSON 字符串转换为自定义类型(反序列化)
let jsonValue = JsonValue.fromStr(jsonString) // String → JsonValue
let dataModel = DataModel.fromJson(jsonValue) // JsonValue → DataModel(ToJson 静态方法)
let person = Person.deserialize(dataModel) // DataModel → Person(Serializable 静态方法)
println("反序列化结果:")
println("姓名: ${person.name}")
println("年龄: ${person.age}")
println("国家: ${person.loc.getOrThrow().country}")
println("省份: ${person.loc.getOrThrow().province}")
}
三段转换各自职责清晰:JsonValue.fromStr 负责语法解析,DataModel.fromJson(即 ToJson 扩展)负责语义降级,Person.deserialize 负责业务还原。运行输出:
反序列化结果:
姓名: A
年龄: 30
国家: China
省份: Beijing
4.3 序列化:自定义类型 → JSON 字符串
// 从自定义类型转换为 JSON 字符串(序列化)
println("\n序列化结果:")
let serializedDataModel = person.serialize() // Person → DataModel(Serializable)
let jsonObject = serializedDataModel.toJson().asObject() // DataModel → JsonValue(ToJson 实例方法)
println(jsonObject.toJsonString()) // JsonValue → 格式化 JSON 字符串
这里 serializedDataModel.toJson() 调用的正是 ToJson 扩展的实例方法;asObject() 是 JsonValue 的类型断言方法,将结果收窄为 JsonObject 以便调用 toJsonString()。运行输出为带缩进的格式化 JSON:
序列化结果:
{
"name": "A",
"age": 30,
"loc": {
"country": "China",
"province": "Beijing"
}
}
5. ToJson 在仓库其他模块中的应用
ToJson 并非孤立设计,仓库内已有真实调用方,可作为功能正确性的佐证:
- unittest 数据策略(src/stdx/unittest/data/json_strategy.cj):
JsonStrategy<T>读取 JSON 文件后,先用JsonValue.fromStr解析,再通过DataModel.fromJson(data) as DataModelSeq转为数据模型,供SerializableProvider做参数化测试——这是fromJson在测试框架中的实际落地。 - json_stream 流式读写(src/stdx/encoding/json/stream/json_deserializable.cj 与 json_reader.cj):流式 API 中
JsonDeserializable<T>的T.fromJson(r)、ArrayList<T>.fromJson(r)等实现,体现了"类型 → JSON"转换思想在流式场景下的延伸(以JsonReader/JsonWriter替代JsonValue)。
6. 小结与最佳实践
- 职责定位:
ToJson只管JsonValue ⇄ DataModel的中间层转换;String ⇄ JsonValue由JsonValue.fromStr/toJsonString负责,DataModel ⇄ 自定义类型由Serializable<T>负责。三段式管线各司其职,可通过 json 包总览 与 serialization 包文档 对照理解。 - 完整链路:自定义类型反序列化用
JsonValue.fromStr→DataModel.fromJson→T.deserialize;序列化用t.serialize→DataModel.toJson→toJsonString。嵌套结构(数组、对象、Option等)在两层递归转换下均可无损往返。 - 异常处理:
toJson/fromJson在遇到不可转换的类型时抛出 JsonException,业务代码建议对转换失败路径做try-catch兜底。 - 扩展机制:
extend DataModel <: ToJson展示了仓颉扩展特性在跨包能力注入上的价值——不侵入 serialization 包,即可让既有数据模型获得 JSON 能力,这也为二次开发中"给第三方类型补充序列化能力"提供了可复用的范式。