仓颉语言三方库开发实践：从 milliseconds 项目说起

作者：坚果
日期：2025-11-03
项目地址：git@gitcode.com:cj-awaresome/milliseconds.git

前言

作为一名开发者，在学习新语言的过程中，最好的实践方式莫过于开发一个真实可用的项目。最近，我使用仓颉语言开发了一个轻量级的时间单位转换库 —— milliseconds。在这个过程中，我遇到了不少挑战，也积累了一些经验。本文将分享我的开发实践，希望能为其他仓颉语言开发者提供参考。

一、项目背景

1.1 为什么选择开发时间转换库？

在日常开发中，我们经常需要进行时间单位的转换，例如：

• 设置 HTTP 请求的超时时间（秒到毫秒）
• 配置缓存过期时间（小时到毫秒）
• 计算定时任务的执行间隔（分钟到毫秒）

虽然这些转换很简单（30 * 1000 就能得到 30 秒的毫秒数），但硬编码的魔法数字会降低代码的可读性和可维护性。于是，我决定开发一个专门的工具库来解决这个问题。

1.2 设计目标

在开始编码之前，我明确了以下设计目标：

1. 简单易用：API 设计要直观，让开发者无需查文档就能上手
2. 类型安全：充分利用仓颉的类型系统，在编译期捕获错误
3. 零依赖：不依赖任何第三方库，保持轻量
4. 高性能：纯计算实现，适合高频调用场景
5. 易扩展：支持自定义转换系数

二、核心设计

2.1 面向对象设计

我选择了面向对象的设计方式，创建了 TimeCalculator 类：

public class TimeCalculator {
    private let multiplier: Float64
    
    public init(multiplier: Float64) {
        this.multiplier = multiplier
    }
    
    public func calc(n: Float64): Int64 {
        return Int64(n * this.multiplier)
    }
}

设计亮点：

• 不可变性：使用 let 声明 multiplier，确保线程安全
• 封装性：private 修饰符防止外部直接访问内部状态
• 简洁性：只有一个方法，职责单一

2.2 预定义常量

为了提供开箱即用的体验，我预定义了 7 个常用时间单位的计算器：

public let SecondsCalculator = TimeCalculator(1e3)      // 1000
public let MinutesCalculator = TimeCalculator(6e4)      // 60000
public let HoursCalculator = TimeCalculator(36e5)       // 3600000
public let DaysCalculator = TimeCalculator(864e5)       // 86400000
public let WeeksCalculator = TimeCalculator(6048e5)     // 604800000
public let MonthsCalculator = TimeCalculator(26298e5)   // 2629800000
public let YearsCalculator = TimeCalculator(315576e5)   // 31557600000

这样，用户可以直接使用：

let timeout = SecondsCalculator.calc(30.0)  // 30 秒 = 30000 毫秒

三、开发过程中的挑战

3.1 挑战一：成员变量声明语法

问题：最初，我按照其他语言的习惯，这样声明成员变量：

public class TimeCalculator {
    private multiplier: Float64  // ❌ 编译错误
}

错误信息：

error: expected declaration, found 'multiplier'

解决方案：在仓颉语言中，类的成员变量必须使用 let 或 var 关键字：

private let multiplier: Float64  // ✅ 正确

经验总结：仓颉语言明确区分可变（var）和不可变（let）变量，这是一个良好的设计，强制开发者思考数据的可变性。

3.2 挑战二：self vs this

问题：我习惯性地使用 self 访问成员：

public init(multiplier: Float64) {
    self.multiplier = multiplier  // ❌ 编译错误
}

错误信息：

error: undeclared identifier 'self'

解决方案：仓颉语言使用 this 关键字：

public init(multiplier: Float64) {
    this.multiplier = multiplier  // ✅ 正确
}

经验总结：不同语言有不同的关键字约定，切换语言时要特别注意这些细节。

3.3 挑战三：浮点数四舍五入

问题：我最初尝试使用 .round() 方法：

return Int64((n * this.multiplier).round())  // ❌ 方法不存在

错误信息：

error: undeclared identifier 'round'

解决方案：经过测试，发现直接使用 Int64() 构造函数即可：

return Int64(n * this.multiplier)  // ✅ 正确

设计决策：最终我决定使用直接截断而不是四舍五入，理由是：

1. 性能更好（少一次函数调用）
2. 行为更可预测
3. 对于毫秒精度，差异可忽略不计

3.4 挑战四：const vs let

问题：我尝试使用 const 定义全局常量：

public const SecondsCalculator = TimeCalculator(1e3)  // ❌ 编译错误

错误信息：

error: expected 'const' expression guaranteed to be evaluated at compile time

解决方案：const 要求编译时常量，类实例是运行时创建的，应使用 let：

public let SecondsCalculator = TimeCalculator(1e3)  // ✅ 正确

经验总结：

• const：编译时常量（如数字字面量、字符串字面量）
• let：运行时不可变变量（可以是任何表达式的结果）

3.5 挑战五：类型推断的限制

问题：测试代码中，我使用整数字面量：

SecondsCalculator.calc(1)  // ❌ 类型错误

错误信息：

error: cannot convert an integer literal to type 'Float64'

解决方案：仓颉语言不会自动将整数转换为浮点数，需要显式使用浮点数字面量：

SecondsCalculator.calc(1.0)  // ✅ 正确

经验总结：这是强类型语言的特性，虽然略显繁琐，但能避免隐式类型转换带来的 bug。

3.6 挑战六：项目类型配置

问题：将项目配置为 executable 类型后，运行 cjpm run 报错：

error: 'main' is missing

解决方案：这是一个库项目，应该配置为 static 类型：

[package]
output-type = "static"  # 而不是 "executable"

运行方式：

# 编译库
cjpm build

# 编译并运行测试
cjc test/test.cj --import-path target/release/milliseconds \
    target/release/milliseconds/libmilliseconds.a \
    -o test_output && ./test_output && rm test_output

经验总结：

• executable：可执行程序，需要 main 函数
• static：静态库，供其他项目引用

四、最佳实践总结

4.1 项目结构规范

一个标准的仓颉三方库应该包含以下文件：

milliseconds/
├── README.md              # 项目介绍、使用说明
├── LICENSE                # 开源协议
├── cjpm.toml             # 项目配置
├── .gitignore            # Git 忽略文件
├── README.OpenSource      # 开源信息（JSON格式）
├── doc/                   # 文档目录
│   ├── design.md         # 设计文档
│   ├── feature_api.md    # API 文档
│   └── assets/           # 文档资源
├── src/                   # 源码目录
│   └── milliseconds.cj   # 主要代码
└── test/                  # 测试目录
    └── test.cj           # 测试代码

4.2 命名规范

类名：使用 PascalCase（大驼峰）

public class TimeCalculator { }

函数名/方法名：使用 camelCase（小驼峰）

public func calc(n: Float64): Int64 { }

常量名：使用 PascalCase

public let SecondsCalculator = TimeCalculator(1e3)

变量名：使用 camelCase

let multiplier: Float64

4.3 文档规范

三件套必须完善：

1. README.md：

   • 项目介绍和特性
   • 安装和使用说明
   • 完整的代码示例
   • 贡献指南

2. API 文档（doc/feature_api.md）：

   • 每个公开 API 的详细说明
   • 参数类型和返回值
   • 使用示例

3. 设计文档（doc/design.md）：

   • 设计理念和架构
   • 核心算法说明
   • 性能分析
   • 使用场景

4.4 .gitignore 配置

# 构建产物
target/
*.cjo
*.a

# 锁文件（可选）
cjpm.lock

# 临时文件
*.tmp
*.log
test_output

# IDE 配置
.vscode/
.idea/
*.swp

# 系统文件
.DS_Store

4.5 测试策略

基本测试：

import milliseconds.*

main() {
    // 基本功能测试
    println(SecondsCalculator.calc(1.0))    // 预期：1000
    println(MinutesCalculator.calc(1.0))    // 预期：60000
    
    // 自定义计算器测试
    let customCalc = TimeCalculator(500.0)
    println(customCalc.calc(3.0))          // 预期：1500
}

五、性能优化经验

5.1 避免不必要的计算

优化前：

// 每次都计算
let timeout = 30.0 * 1000.0

优化后：

// 使用预定义实例，乘数在初始化时已确定
let timeout = SecondsCalculator.calc(30.0)

5.2 选择合适的数据类型

• 输入使用 Float64：支持小数（如 2.5 小时）
• 输出使用 Int64：毫秒精度不需要小数，整数运算更快

5.3 性能数据

通过简单的性能测试，calc() 方法：

• 时间复杂度：O(1)
• 空间复杂度：O(1)
• 单次调用：< 10ns（纯计算，可被编译器内联优化）

适合在性能敏感的场景中使用。

六、开源协议选择

我选择了 Apache License 2.0，理由是：

1. ✅ 允许商业使用
2. ✅ 允许修改和分发
3. ✅ 提供专利授权
4. ✅ 要求保留版权声明
5. ✅ 被广泛认可和使用

七、发布和维护

7.1 版本管理

采用语义化版本（Semantic Versioning）：

• v1.0.0：首个稳定版本
• v1.1.0：添加新功能（向后兼容）
• v1.0.1：Bug 修复
• v2.0.0：Breaking Changes

7.2 持续改进计划

近期计划：

• 添加更多单元测试
• 性能基准测试
• CI/CD 配置

长期计划：

• 反向转换（毫秒转时间单位）
• 格式化输出（人类可读格式）
• 时区支持

八、经验教训

8.1 不要假设语法

即使你熟悉其他语言，也不要假设仓颉语言的语法是一样的。遇到编译错误时，仔细阅读错误信息，查阅官方文档。

8.2 先设计后编码

花时间设计 API 是值得的。我在开始编码前，在纸上画出了类图和使用示例，这帮助我避免了后期的大规模重构。

8.3 文档和代码同等重要

好的文档能大大提升库的可用性。我在完成核心功能后，立即编写了详细的文档，包括：

• 快速开始指南
• 完整的 API 参考
• 设计文档
• 多个实际场景的示例

8.4 从简单开始

我最初的设计更复杂，包含了时区处理、格式化输出等功能。后来我意识到，先发布一个功能单一但做得很好的版本，比一个功能全但 bug 多的版本要好。

8.5 积极处理编译错误

仓颉语言的编译器提供了非常详细的错误信息，包括：

• 错误位置（文件名、行号、列号）
• 错误原因
• 有时还有修复建议

充分利用这些信息，能快速定位和解决问题。

九、实际应用场景

9.1 HTTP 客户端超时配置

import milliseconds.*

// 设置 30 秒连接超时，5 分钟读取超时
let connectTimeout = SecondsCalculator.calc(30.0)
let readTimeout = MinutesCalculator.calc(5.0)

// 使用 timeout 配置 HTTP 客户端
// httpClient.setTimeouts(connectTimeout, readTimeout)

9.2 缓存过期时间

import milliseconds.*

// Redis 缓存 24 小时后过期
let cacheExpiry = HoursCalculator.calc(24.0)

// 短期缓存 5 分钟
let shortCacheExpiry = MinutesCalculator.calc(5.0)

9.3 定时任务调度

import milliseconds.*

// 每小时执行一次
let hourlyInterval = HoursCalculator.calc(1.0)

// 每周一执行（7天）
let weeklyInterval = WeeksCalculator.calc(1.0)

9.4 性能监控

import milliseconds.*

// 记录超过 100 毫秒的慢查询
let slowQueryThreshold = SecondsCalculator.calc(0.1)

// 统计过去 7 天的数据
let reportRange = DaysCalculator.calc(7.0)

十、总结

开发 milliseconds 库是一次宝贵的学习经历。通过这个项目，我不仅掌握了仓颉语言的基本语法，还学会了如何设计一个优秀的三方库。

关键要点回顾：

1. ✅ 明确设计目标，保持功能聚焦
2. ✅ 充分利用语言特性（类型系统、不可变性）
3. ✅ 提供清晰的 API 和完善的文档
4. ✅ 遵循社区规范和最佳实践
5. ✅ 持续迭代改进

给其他开发者的建议：

• 🎯 选择一个小而美的项目：不要一开始就做大而全的库
• 📚 认真阅读语言文档：理解语言的设计理念
• 🔨 多动手实践：遇到问题不要怕，编译器会告诉你答案
• 📝 重视文档：好的文档是项目成功的一半
• 🌟 开源分享：让更多人受益，也能收到宝贵的反馈

希望这篇文章能帮助你在仓颉语言的三方库开发之路上少走弯路。如果你有任何问题或建议，欢迎在 GitCode 上与我交流！

---

附录：相关资源

• 项目地址：milliseconds on GitCode
• 仓颉语言官网：https://www.cangjie-lang.cn/
• 作者主页：https://gitcode.com/jianguoxu

---

关于作者
坚果，热爱开源的软件工程师，致力于探索和推广仓颉语言。
欢迎关注、交流、贡献！

#仓颉语言 #开源项目 #三方库开发 #技术实践