仓颉三方库开发模版使用指南：从零开始构建你的第一个仓颉库

仓颉三方库开发模版使用指南：从零开始构建你的第一个仓颉库

引言

随着仓颉编程语言生态的不断发展，越来越多的开发者希望为社区贡献自己的力量，开发和分享优质的三方库。然而，从零开始搭建一个标准化、规范化的库项目并不容易。为此，官方提供了一套完整的三方库开发模版，帮助开发者快速启动项目，专注于核心功能的实现，而无需在项目结构和规范上花费过多精力。

本文将详细介绍这个仓颉三方库模版的设计理念、项目结构以及使用方法，帮助你快速上手，开发出高质量的仓颉三方库。

为什么需要标准化的项目模版？

在软件开发中，项目结构的标准化至关重要。一个规范的项目模版能够：

• 降低学习成本：开发者能够快速理解项目结构，找到所需的文件和代码
• 提升代码质量：统一的目录结构和文档规范促进最佳实践的落地
• 便于协作维护：清晰的项目组织使得团队协作更加高效
• 加速开发进程：开箱即用的结构让开发者专注于功能实现
• 提高可信度：规范的项目给使用者更专业、可靠的印象

模版项目结构详解

仓颉三方库模版采用了清晰的分层结构，让我们逐一了解每个部分的作用：

template/
├── README.md              # 项目主文档
├── CHANGELOG.md           # 版本变更记录
├── LICENSE                # 开源协议
├── README.OpenSource      # 开源声明
├── cjpm.toml              # 包管理配置文件
├── doc/                   # 文档目录
│   ├── assets/            # 文档资源（图片、图表等）
│   │   └── example.png
│   ├── design.md          # 设计文档
│   └── feature_api.md     # API 接口文档
├── src/                   # 源码目录
│   └── Template.cj        # 源代码文件
└── test/                  # 测试代码目录
    ├── HLT/               # 高层测试（High Level Test）
    │   └── testcase0001.cj
    └── LLT/               # 低层测试（Low Level Test）
        └── testcase0001.cj

核心文件说明

1. README.md - 项目门面

README 是用户了解你的库的第一窗口，模版提供了完整的章节结构：

• 项目信息徽章：版本号、编译器版本、测试覆盖率、项目状态、应用领域等
• 介绍部分：清晰说明库的功能、解决的问题、应用场景和主要特性
• 项目架构：架构图和模块说明
• 使用说明：编译构建步骤和功能示例
• 约束与限制：环境要求、版本依赖等
• 开源协议和贡献指南

2. cjpm.toml - 包管理配置

这是仓颉包管理器（cjpm）的核心配置文件，定义了：

[package]
  name = "demo"                    # 包名
  version = "1.0.0"                # 版本号
  description = "nothing here"     # 描述
  cjc-version = "1.0.3"           # 编译器版本要求
  output-type = "executable"       # 输出类型
  src-dir = ""                     # 源码目录
  target-dir = ""                  # 目标目录
  compile-option = ""              # 编译选项
  link-option = ""                 # 链接选项

[dependencies]
  # 依赖库配置

3. doc/ - 文档体系

模版提供了完整的文档结构：

• design.md：设计文档，包含类设计、API 定义、架构图、依赖关系等
• feature_api.md：详细的 API 接口文档，每个公开接口都需要完整的描述
• **assets/**：存放文档中使用的图片、图表等资源

4. src/ - 源码目录

存放所有源代码文件（.cj 文件），按模块组织代码结构。

5. test/ - 测试目录

采用分层测试策略：

• LLT（Low Level Test）：低层测试，针对单个函数、类的单元测试
• HLT（High Level Test）：高层测试，针对模块集成、端到端的功能测试

6. CHANGELOG.md - 版本管理

记录每个版本的变更内容，包括：

• 新增功能（Feature）
• 问题修复（Bugfix）
• 删除接口（Remove）

如何使用模版创建你的三方库

第一步：克隆或下载模版

# 方式1：克隆模版仓库
git clone <template-repo-url> my-cangjie-lib
#比如
git clone git@gitcode.com:cj-awaresome/template.git my-cangjie-lib

# 方式2：下载压缩包解压
# 将模版下载到本地并重命名为你的项目名称

第二步：自定义配置

修改 cjpm.toml

根据你的项目需求修改包配置：

[package]
  name = "my-awesome-lib"              # 修改为你的库名
  version = "0.1.0"                    # 设置初始版本
  description = "一个很棒的仓颉库"      # 描述你的库
  cjc-version = "1.0.3"                # 根据需要调整编译器版本
  output-type = "static_library"       # 通常三方库设置为 static_library 或 dynamic_library

更新 README.md

将 README.md 中的占位内容替换为你的项目信息：

1. 修改标题为你的库名
2. 更新徽章信息（版本号、编译器版本等）
3. 填写库的介绍和特性
4. 描述项目架构
5. 提供使用示例
6. 说明依赖和限制
7. 选择开源协议

第三步：开发功能

编写源代码

在 src/ 目录下编写你的核心代码。例如：

// src/MyLib.cj
package my_awesome_lib

// 定义公开的类
public class Calculator {
    // 构造函数
    public init() {}

    // 加法运算
    public func add(a: Int64, b: Int64): Int64 {
        return a + b
    }

    // 减法运算
    public func subtract(a: Int64, b: Int64): Int64 {
        return a - b
    }
}

// 定义公开的函数
public func sayHello(name: String): String {
    return "Hello, ${name}!"
}

编写设计文档

在 doc/design.md 中详细描述你的设计：

# Calculator 库设计

## 描述

提供基础的数学计算功能，包括加减乘除等运算。

## Calculator 类设计

### 类描述

Calculator 是一个简单的计算器类，提供基础的数学运算方法。

### 类 API

```cangjie
public class Calculator {
    public init()
    public func add(a: Int64, b: Int64): Int64
    public func subtract(a: Int64, b: Int64): Int64
}
```

编写 API 文档

在 doc/feature_api.md 中为每个公开接口提供详细文档：

## add 方法

```cangjie
/*
 * 执行两个整数的加法运算
 *
 * 参数 a - 第一个加数
 * 参数 b - 第二个加数
 * 返回值 - 两数之和
 */
public func add(a: Int64, b: Int64): Int64
```

第四步：编写测试

单元测试（LLT）

在 test/LLT/ 目录下编写单元测试：

// test/LLT/calculator_test.cj
import my_awesome_lib.*
import std.unittest.*

@Test
func testAdd() {
    let calc = Calculator()
    @Assert(calc.add(2, 3) == 5, "2 + 3 should equal 5")
}

@Test
func testSubtract() {
    let calc = Calculator()
    @Assert(calc.subtract(5, 3) == 2, "5 - 3 should equal 2")
}

集成测试（HLT）

在 test/HLT/ 目录下编写高层测试，测试多个模块的协作。

第五步：构建和测试

使用 cjpm 进行构建和测试：

# 更新依赖
cjpm update

# 构建项目
cjpm build

# 运行测试
cjpm test

# 查看测试覆盖率
cjpm coverage

第六步：版本管理

每次发布新版本时，更新 CHANGELOG.md：

# [0.1.0] - 2025-11-02

## Feature

- 实现基础的加法功能
- 实现基础的减法功能
- 添加 Calculator 类

## Bugfix

- 无

## Remove

- 无

同时更新 cjpm.toml 中的版本号。

最佳实践建议

1. 代码规范

• 遵循仓颉官方代码风格指南
• 为所有公开接口添加详细注释
• 使用有意义的命名
• 保持函数简洁，单一职责

2. 文档完善

• README 应该让用户 5 分钟内了解如何使用
• 提供丰富的代码示例
• 文档与代码保持同步
• 使用图表增强可读性

3. 测试覆盖

• 追求高测试覆盖率（建议 > 80%）
• 编写有意义的测试用例
• 包含正常和异常场景
• 性能关键路径要有基准测试

4. 版本管理

• 遵循语义化版本规范（Semantic Versioning）
• 及时更新 CHANGELOG
• 做好向后兼容性考虑
• 明确标注破坏性变更

5. 开源协议

• 选择合适的开源协议（MIT、Apache 2.0 等）
• 在 LICENSE 文件中包含完整的协议文本
• 在源代码文件中添加协议头注释

发布你的三方库

当你的库开发完成并经过充分测试后，可以考虑发布到仓颉社区：

1. 完善文档：确保 README、API 文档、示例代码完整准确
2. 代码审查：邀请其他开发者审查代码
3. 测试验证：在不同环境下测试库的功能
4. 提交发布：将代码提交到仓颉三方库平台（TPC）[1]。这个时候你直接在template[2]提交 issue 就可以。我们平台的管理员看到就会处理，或者就是直接在社群沟通，加入社群方式：vx 联系 nut_pie 或者这儿也可以找到联系方式[3]
5. 社区推广：在社区论坛、技术博客中介绍你的库

示例项目参考

为了让你更好地理解如何使用这个模版，这里提供一个简单的完整示例——一个字符串工具库：

项目名称：cangjie-string-utils

功能：提供常用的字符串处理工具函数

核心代码（src/StringUtils.cj）：

package string_utils

public class StringUtils {
    // 反转字符串
    public static func reverse(s: String): String {
        // 实现代码
    }

    // 判断是否为回文
    public static func isPalindrome(s: String): Bool {
        // 实现代码
    }

    // 统计字符频率
    public static func charFrequency(s: String): HashMap<Rune, Int64> {
        // 实现代码
    }
}

使用示例：

import string_utils.*

main() {
    let original = "hello"
    let reversed = StringUtils.reverse(original)
    println("原字符串: ${original}")
    println("反转后: ${reversed}")

    let word = "level"
    if (StringUtils.isPalindrome(word)) {
        println("${word} 是回文")
    }
}

常见问题解答

Q1: 如何设置库的输出类型？

A: 在 cjpm.toml 中设置 output-type：

• static_library：静态库
• dynamic_library：动态库
• executable：可执行程序（用于测试）

Q2: HLT 和 LLT 的区别是什么？

A:

• LLT（Low Level Test）：低层测试，关注单个函数、类的正确性，类似单元测试
• HLT（High Level Test）：高层测试，关注模块间协作、端到端功能，类似集成测试

Q3: 如何管理依赖库？

A: 在 cjpm.toml 的 [dependencies] 部分添加依赖：

[dependencies]
  other-lib = "1.0.0"

Q4: 如何发布不同版本？

A:

1. 修改 cjpm.toml 中的 version
2. 更新 CHANGELOG.md 记录变更
3. 打标签并推送到仓库
4. 提交到官方三方库平台

Q5: 是否必须使用所有模版文件？

A: 核心文件（README.md、cjpm.toml、src/、test/）建议保留，其他可根据项目需要调整。但完整的文档体系会大大提升项目的专业性。

总结

仓颉三方库开发模版为开发者提供了一个坚实的起点，让你可以快速启动标准化的库项目。通过遵循模版的结构和规范，你可以：

• ✅ 节省项目搭建时间
• ✅ 保持代码和文档的高质量
• ✅ 融入仓颉社区的最佳实践
• ✅ 提升库的可维护性和可信度
• ✅ 加速社区生态的繁荣发展

现在，是时候动手创建你的第一个仓颉三方库了！选择一个你感兴趣的方向，利用这个模版，为仓颉社区贡献你的力量。无论是工具类库、算法库、Web 框架，还是其他任何领域，社区都期待你的创新和分享。

相关资源

仓颉标准库：https://gitcode.com/Cangjie/cangjie_runtime/tree/main/stdlib

仓颉扩展库：https://gitcode.com/Cangjie/cangjie_stdx

仓颉命令行工具：https://gitcode.com/Cangjie/cangjie_tools

仓颉语言测试用例：https://gitcode.com/Cangjie/cangjie_test

仓颉语言示例代码：https://gitcode.com/Cangjie/Cangjie-Examples

仓颉鸿蒙示例应用：https://gitcode.com/Cangjie/HarmonyOS-Examples

精品三方库：https://gitcode.com/org/Cangjie-TPC/repos

SIG 孵化库：https://gitcode.com/org/Cangjie-SIG/repos

作者：坚果 日期：2025 年 11 月 2 日 版本：1.0

本文基于仓颉三方库模版项目编写，旨在帮助开发者快速入门仓颉库开发。如有任何问题或建议，欢迎在社区中讨论交流。

快来克隆https://gitcode.com/cj-awaresome/template项目开始贡献自己的三方库吧。

参考资料

[1]

仓颉三方库平台（TPC）: https://gitcode.com/cj-awaresome

[2]

template: https://gitcode.com/cj-awaresome/template/issues

[3]

联系方式: https://gitcode.com/jianguoxu