cangjie_stdx 中的 ToJson 接口:JsonValue 与 DataModel 双向转换实战指南

原创2026-10-14 23:46:371,392 阅读
文章标签:标准库

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 能力,这也为二次开发中"给第三方类型补充序列化能力"提供了可复用的范式。
登录后查看全文
cangjie_stdx