CJson 工具使用指南

2026-04-02 09:29:25作者：傅爽业Veleda

如何快速掌握 CJson 的核心功能优势

CJson 是一款高效的 Json 序列化/反序列化（将对象与 JSON 格式相互转换的过程）工具，通过宏标记自动为类添加 fromJson() 和 toJson() 方法，使目标类具备原生序列化能力。

🚀 核心优势一：便捷的宏标记机制
通过 @JsonSerializable 宏快速标记可序列化类，无需手动编写序列化代码，极大减少重复劳动。

🚀 核心优势二：丰富的高级功能支持
提供属性别名、忽略字段、默认值、泛型等实用功能，满足复杂业务场景下的序列化需求。

🚀 核心优势三：灵活的接口设计
提供定制化序列化接口 IJsonSerializable<T>，兼容类和结构体，只需确保目标类型拥有无参构造函数即可使用。

3 步完成 CJson 环境准备工作

系统兼容性矩阵

操作系统	工具链要求	运行时环境要求
Linux	CJPM 构建工具	Cangjie 语言环境 ≥ 1.2.0
macOS	CJPM 构建工具	Cangjie 语言环境 ≥ 1.2.0
Windows	支持 Cangjie 工具链的版本	Cangjie 语言环境 ≥ 1.2.0

💡 操作提示：在终端执行以下命令检查工具链版本

cjpm --version

✅ 验证方式：命令输出应显示 CJPM 版本号及 Cangjie 环境版本信息

2 种获取 CJson 项目的方式

方式一：源码集成

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

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

方式二：直接克隆仓库

💡 操作提示：使用 git 命令克隆项目

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

✅ 验证方式：检查当前目录下是否创建 CJson 文件夹

新手与高级双路径部署指南

新手引导路径

1️⃣ → 进入项目目录

cd CJson

2️⃣ → 编译项目

cjpm build

✅ 验证方式：检查 target 目录下是否生成编译产物

3️⃣ → 运行单元测试

cjpm test

✅ 验证方式：测试结果显示全部通过

4️⃣ → 执行演示程序

cjpm run

✅ 验证方式：程序正常输出示例运行结果

高级配置路径

对于有特殊需求的用户，可以进行自定义配置： 1️⃣ → 编辑 cjpm.toml 文件，添加自定义编译选项 2️⃣ → 执行带参数的构建命令

cjpm build --release --features "advanced-json"

3️⃣ → 运行性能测试

cjpm test --benchmark

CJson 实用工具与脚本

常用脚本命令

脚本命令	功能描述
`cjpm build`	编译项目
`cjpm test`	运行单元测试
`cjpm run`	执行演示程序
`cjpm clean`	清理构建产物

自定义脚本模板

在项目根目录创建 scripts/format.sh 文件：

#!/bin/bash
# 批量格式化代码
find src -name "*.cj" | xargs cjfmt -i
echo "代码格式化完成"

💡 操作提示：添加执行权限并运行

chmod +x scripts/format.sh
./scripts/format.sh

常见问题速查

Q: 编译时提示 "缺少无参构造函数" 怎么办？
A: CJson 需要目标类/结构体提供无参构造函数，请确保所有标记 @JsonSerializable 的类型都有默认构造函数。

Q: 如何忽略某个字段不参与序列化？
A: 使用 @JsonIgnore 宏标记需要忽略的字段即可。

Q: 可以自定义属性的 JSON 键名吗？
A: 可以，使用 @JsonName("custom_name") 宏为属性指定别名。