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

引言

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

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

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

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

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

模版项目结构详解

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

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` 中为每个公开接口提供详细文档：

```markdown
## 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）
  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

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

# 数据库 # 服务器 # 前端 # 华为
Logo
GitCode 开源社区

新一代开源开发者平台 GitCode，通过集成代码托管服务、代码仓库以及可信赖的开源组件库，让开发者可以在云端进行代码托管和开发。旨在为数千万中国开发者提供一个无缝且高效的云端环境，以支持学习、使用和贡献开源项目。

更多推荐

cover

libmd 实现详解：仓颉语言中的哈希算法库开发实践

avatar GitCode 开源社区

librtp 实现详解：仓颉语言中的 RTP和RTCP 协议库开发实践

在实时音视频通信、流媒体传输、网络监控等场景中，RTP/RTCP 协议是确保数据正确传输和实时反馈的关键技术。RTP 负责传输音视频数据，RTCP 负责传输控制信息，两者配合工作，共同保障实时通信的质量。librtp 库旨在为仓颉语言提供一套完整、高效、易用的 RTP/RTCP 协议处理解决方案，支持 RTP 包的创建、读取和序列化，RTCP 包的创建和解析，NTP 时间戳和 RTP 时间戳的转换

avatar GitCode 开源社区
cover

仓颉三方库实战教程：用 color4cj 处理颜色 [特殊字符]

avatar GitCode 开源社区