如何使用CJson实现高效Json序列化与反序列化

CJson是一款专为Cangjie语言设计的高效Json序列化/反序列化工具，通过宏标记自动为类添加fromJson()和toJson()方法，让目标类具备原生数据转换能力。本文将从环境配置、基础使用到高级功能，全面介绍如何快速掌握这款工具的核心用法。

1. 认识CJson：让Json处理变得简单

CJson作为Cangjie生态中的数据转换工具，核心优势在于其"零侵入"设计。通过@JsonSerializable宏标记，开发者无需手动编写序列化逻辑，即可让类或结构体获得Json数据的双向转换能力。支持属性别名、字段忽略、默认值设置等实用功能，同时提供IJsonSerializable<T>接口满足定制化需求。

1.1 核心功能一览

• ✨ 宏驱动：一行注解实现完整序列化能力
• 🛠️ 灵活配置：支持字段重命名、忽略策略
• 🔄 双向转换：同时提供fromJson()与toJson()方法
• 🧩 泛型支持：完美适配集合类型与嵌套结构

2. 快速配置指南：5分钟搭建开发环境

2.1 环境要求清单

• 操作系统：Linux/macOS/Windows（需支持Cangjie工具链）
• 工具链：CJPM构建工具（Cangjie Package Manager）
• 运行时：Cangjie语言环境 ≥ 1.2.0

2.2 获取项目源码

通过以下命令克隆官方仓库：

git clone https://gitcode.com/Cangjie-TPC/CJson.git --branch master

2.3 两种集成方式

方式一：源码依赖集成

在项目根目录的cjpm.toml中添加依赖配置：

[dependencies]
CJson = { git = "https://gitcode.com/Cangjie-TPC/CJson.git", branch = "master" }

方式二：本地编译安装

# 进入项目目录
cd CJson

# 编译项目
cjpm build

# 运行单元测试
cjpm test

# 执行演示程序
cjpm run

3. 基础使用教程：从标记到序列化的完整流程

3.1 标记可序列化类

使用@JsonSerializable宏标记需要序列化的类或结构体：

@JsonSerializable
class User {
    String name;
    Int age;
    Bool isActive;
}

3.2 基本序列化操作

// 创建对象
var user = User {
    name = "Alice",
    age = 30,
    isActive = true
};

// 序列化为Json字符串
var jsonStr = user.toJson();

// 从Json字符串反序列化
var parsedUser = User.fromJson(jsonStr);

4. 高级功能详解：定制你的序列化策略

4.1 字段重命名技巧

使用@JsonName宏为字段指定Json别名：

@JsonSerializable
class Product {
    @JsonName("product_id")
    String id;
    
    @JsonName("product_name")
    String name;
}

4.2 忽略特定字段

通过@JsonIgnore宏排除不需要序列化的字段：

@JsonSerializable
class User {
    String username;
    String password;
    
    @JsonIgnore
    String tempToken;
}

4.3 设置默认值

使用@DefaultValue宏定义字段默认值：

@JsonSerializable
class Config {
    @DefaultValue("UTF-8")
    String encoding;
    
    @DefaultValue("3000")
    Int timeout;
}

5. 项目结构解析：了解CJson内部机制

CJson项目采用模块化设计，核心代码位于src/jsonmacro/目录，主要包含：

• ClassJsonSerilizer.cj：序列化逻辑实现
• ClassJsonDeserilizer.cj：反序列化逻辑实现
• JsonSerializable.cj：核心宏定义
• JsonName.cj/JsonIgnore.cj：属性控制注解

测试用例位于src/test/目录，包含各类场景的验证代码，如Serialization_test.cj、CustomName_test.cj等。

6. 常用命令速查：提升开发效率

命令	功能描述
cjpm build	编译项目生成库文件
cjpm test	运行所有单元测试
cjpm run	执行示例程序
cjpm clean	清理构建产物

7. 实际应用场景：解决开发中的常见问题

7.1 处理嵌套对象

CJson自动支持嵌套对象的序列化：

@JsonSerializable
class Address {
    String street;
    String city;
}

@JsonSerializable
class User {
    String name;
    Address address;
}

7.2 集合类型处理

支持数组、列表等集合类型的序列化：

@JsonSerializable
class Group {
    String name;
    List<User> members;
}

8. 问题排查与性能优化

8.1 常见错误解决

• 无参构造函数要求：被序列化的类必须提供无参构造函数
• 类型不匹配：确保Json数据类型与类属性类型一致
• 循环引用：避免序列化包含循环引用的对象结构

8.2 性能优化建议

• 对于大型数据集，考虑使用Perf_test.cj中的性能测试工具进行瓶颈分析
• 合理使用字段忽略功能，减少不必要的序列化数据量

通过本文介绍，您已经掌握了CJson的核心用法和高级特性。这款工具通过宏驱动的设计理念，极大简化了Json数据处理流程，让开发者能够专注于业务逻辑实现。无论是小型项目还是大型应用，CJson都能提供高效可靠的Json序列化解决方案。