CJson：轻量级Json处理库零基础上手指南

CJson是一款基于宏定义实现的高效Json序列化工具，通过简洁的宏标记即可为类自动生成fromJson()和toJson()方法，让数据交换变得简单高效。作为轻量级Json处理库，它不仅支持属性别名、忽略字段等高级特性，还提供灵活的定制化接口，完美适配各类开发场景。

核心能力解析

🔧 自动化序列化实现

通过@JsonSerializable宏标记目标类，无需手动编写序列化代码，工具自动生成完整的Json转换逻辑，大幅减少重复劳动。支持类与结构体两种类型，只需确保目标类型包含无参构造函数即可快速集成。

🛠️ 丰富功能特性

• 属性别名：使用@JsonName指定Json字段名称，解决代码命名规范与Json格式差异问题
• 字段控制：通过@JsonIgnore标记无需序列化的字段，优化数据传输效率
• 默认值支持：为字段设置默认值，在反序列化时自动填充缺失数据
• 泛型兼容：完美支持泛型集合与嵌套结构，满足复杂数据模型需求

💡 性能优势

特性	CJson	传统手动实现
代码量	减少80%	100%手动编写
执行效率	接近原生	依赖开发者水平
维护成本	极低	高
扩展性	内置扩展接口	需要完全重写

项目获取方式

源码克隆

git clone https://gitcode.com/Cangjie-TPC/CJson.git --branch master  # 获取最新稳定版源码

环境准备指南

系统兼容性矩阵

操作系统	最低版本要求	工具链要求
Linux	Ubuntu 18.04+	CJPM ≥ 2.0.0
macOS	10.15+	Xcode Command Line Tools
Windows	Windows 10+	Cangjie SDK ≥ 1.2.0

环境检查流程

1. 验证Cangjie环境版本

   cangjie --version  # 需显示1.2.0及以上版本
   

2. 确认CJPM构建工具

   cjpm --version     # 需显示2.0.0及以上版本
   

⚠️ 常见问题排查：若命令未找到，需将工具链添加到系统PATH。Linux/macOS用户可执行source ~/.profile刷新环境变量。

部署方案详解

方案一：项目依赖集成

在项目根目录的cjpm.toml中添加：

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

方案二：本地编译部署

cd CJson                      # 进入项目目录
cjpm build --release          # 编译发布版本
cjpm test                     # 运行单元测试套件

📌 部署提示：添加--verbose参数可查看详细构建过程，便于排查编译错误。

实用指南

基础使用流程

1. 标记可序列化类

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

2. 序列化操作

   let user = User{name: "Alice", age: 25};
   String json = user.toJson();  // 自动生成的序列化方法
   

3. 反序列化操作

   User user = User.fromJson(json);  // 自动生成的反序列化方法
   

高级特性示例

• 自定义属性名

  @JsonSerializable
  class User {
    @JsonName("user_name")
    String name;
  }
  

• 忽略字段

  @JsonSerializable
  class User {
    String name;
    @JsonIgnore
    String password;  // 不会被序列化
  }
  

社区支持

问题反馈

如遇使用问题，可提交Issue至项目仓库，建议包含以下信息：

• 环境配置详情
• 复现步骤
• 错误日志片段

贡献指南

项目欢迎各类贡献，包括但不限于：

• 功能改进建议
• 代码优化
• 测试用例补充

通过以上指南，您已掌握CJson的核心使用方法。这款轻量级Json处理库将帮助您在项目中高效实现数据序列化需求，减少重复编码工作，提升开发效率。