Ramda 跨端三方库仓颉适配全流程

本文记录 Ramda 0.32.0 适配仓颉（Cangjie）的完整过程。适配目标是得到一个可以被仓颉项目直接依赖的跨端三方库，并在终端中用真实示例验证集合、对象、字符串、数值、函数组合和 Option 等能力。

这类适配与 OpenHarmony 原生三方库不同：仓颉版本不依赖 ArkTS、HAP、设备传感器或系统权限，而是通过 cjpm 组织源码、通过静态类型表达 JavaScript 的常用函数式语义，再以静态库形式供其他仓颉项目复用。

项目地址： AtomGit/nutpi_cj/ramda

上游仓库： ramda/ramda

开发工具： 华为云码道

一、背景

1.1 为什么适配 Ramda

Ramda 是 JavaScript 生态中以函数式组合、不可变数据处理和数据变换为特色的工具库，常用于集合、对象、字符串、数值和高阶函数场景。JavaScript 版本可以接收动态值、异构数组和运行时回调，而仓颉强调静态类型、泛型和显式的空值处理。直接逐行翻译 JavaScript 源码并不能解决类型边界问题，适配的重点是为常用 Ramda 能力重新设计可编译、可复用的仓颉签名。

本项目将 Ramda 0.32.0 的常用能力拆分为多个仓颉源码文件，并保留 map、filter、reduce、pipe、groupBy、assoc 等熟悉的函数名，让熟悉 Ramda 的开发者可以沿用原有的思维方式完成迁移。

1.2 跨端三方库的适配边界

当前项目提供的是仓颉跨端库，不绑定某一个 UI 框架或操作系统。适配边界可以概括为：

边界	仓颉实现
包管理	cjpm.toml、cjpm.lock、cjpm build 和 target/release/ramda
集合数据	Array、Array<Array>、HashMap<String, V>
缺省值	Option 和显式 fallback 参数
回调	带参数和返回值类型的函数值
交付形态	仓颉静态库 libramda.a 和接口文件 ramda.cjo
验证方式	test/main.cj 自动化测试和 example/example.cj 终端示例

这里没有 HAP 构建、ArkTS 桥接和真机系统能力验收。只要目标平台提供兼容版本的仓颉 SDK，就可以按同一套源码和 cjpm 配置构建并消费这个库。原始 Ramda JavaScript 文件和目录继续保留在项目中，不参与仓颉包的源码扫描。

1.3 适配后的能力

当前版本已经为一组常用 Ramda API 提供了明确的仓颉入口，能力按以下类别组织：

• 集合变换：map、filter、reduce、find、take、drop、flatten、uniq、splitEvery、intersperse、dropRepeats、range、product 等；
• 对象和路径：prop、path、pathOr、assoc、assocPath、dissoc、pick、omit、keys、values、groupBy、keyBy 等；
• 函数组合和谓词：pipe、compose、identity、always、all、any、none、both、either、complement 等；
• 字符串和数值：trim、replace、toLower、toUpper、camelCase、add、subtract、multiply、sum、mean、clamp、mathMod 等；
• 兼容入口：对部分高阶函数、对象操作、排序、随机和工具函数保留可调用的静态签名，并在兼容边界中说明当前实现范围。

这些能力覆盖当前示例和测试使用的主要场景。项目没有把"导出名称存在"当成"所有 JavaScript 动态语义已经完全实现"，行为仍以具体仓颉签名、测试断言和兼容说明为准。

二、实现路线图

第 1 阶段：盘点 API       ── 对照 Ramda 0.32.0 的函数分类，确定仓颉函数和目录边界
第 2 阶段：建立 cjpm 工程 ── 固定包名、版本、源码目录和静态库输出
第 3 阶段：类型映射       ── 用 Array、HashMap、Option 和泛型替换动态值
第 4 阶段：分模块实现     ── 完成核心、扩展和兼容 API 三层源码
第 5 阶段：测试与核对     ── 编译测试入口，执行代表性行为断言和导出声明检查
第 6 阶段：终端演示       ── 构建 example，直接输出真实函数调用结果

每个阶段都有可检查的产物：工程阶段得到 cjpm.toml 和 cjpm.lock，实现阶段得到 target/release/ramda，验证阶段得到 ALL RAMDA CANGJIE TESTS PASS，最终示例则输出一组可以直接观察的 Ramda 仓颉运行结果。

三、逐步实现过程

第 1 阶段：盘点原库 API 和仓颉工程边界

1.1 识别动态 API

Ramda 的 JavaScript API 经常通过动态值、任意参数数量和运行时函数组合来工作。例如 path 可以读取动态对象路径，curry 可以根据运行时参数逐步收集参数。仓颉没有与 JavaScript Any 完全等价的无类型容器，因此本适配先筛选能够由静态类型稳定表达的能力，再为这些能力提供明确签名；无法一比一表达的入口放入兼容层，并保留可编译的边界行为。

1.2 固定仓颉项目结构

以下目录树按照当前 ramda 项目的仓颉适配文件整理，只展示仓颉相关的文件；原始 Ramda JavaScript 源码、测试和构建目录保持原位置，不在此处重复列出：

ramda/
├── cjpm.toml
├── cjpm.lock
├── README.Cangjie.md
├── README.Cangjie_CN.md
├── src/
│   ├── ramda.cj
│   ├── ramda_compat.cj
│   ├── ramda_compat_surface.cj
│   ├── ramda_extra.cj
│   └── ramda_surface.cj
├── test/
│   └── main.cj
└── example/
    ├── cjpm.toml
    ├── cjpm.lock
    └── example.cj

源码按职责拆分：ramda.cj 放置集合、对象、字符串和数值的主体实现；ramda_extra.cj 放置随机、采样、类型判断、对象辅助和更多集合工具；ramda_surface.cj 放置 Ramda 特有的函数式入口；ramda_compat.cj 和 ramda_compat_surface.cj 保留需要兼容的函数名和静态签名。测试入口位于 test/main.cj，示例工程位于 example/，两者都独立于库源码。根目录的两个 README 只描述仓颉接入方式，不改变原始 JavaScript 文件和目录。

第 2 阶段：创建 cjpm 工程

根目录 cjpm.toml 使用静态库输出类型，并将源码目录、包名和版本固定下来：

[dependencies]

[package]
  cjc-version = "1.1.3"
  name = "ramda"
  version = "0.32.0"
  output-type = "static"
  src-dir = "src"
  target-dir = "target"

适配包沿用 Ramda 的 0.32.0 版本标识，包名保持 ramda。构建成功后，主要产物是：

target/release/ramda/libramda.a
target/release/ramda/ramda.cjo

其中 .a 用于链接，.cjo 提供编译器需要的接口信息。当前仓颉编译器会对部分兼容入口报告 unused variable 警告，原因是这些入口为了保留参数形状而暂时没有使用全部参数；只要 cjpm build 成功，静态库就已经生成。

示例工程的 example/cjpm.toml 通过 Git 依赖引用 ramda 的 master 分支，example/cjpm.lock 固定实际依赖提交，便于在独立仓颉工程中复现相同的 API。

第 3 阶段：把 JavaScript 动态值映射为仓颉类型

3.1 数组和对象

集合 API 使用泛型 Array，嵌套集合使用 Array<Array>。例如 map、filter 和 reduce 都把元素类型和回调返回值写进签名：

let even = filter([1, 2, 3, 4], { value, _ => value % 2 == 0 })
let doubled = map(even, { value, _ => value * 2 })
let total = reduce(doubled, 0, { acc, value, _ => acc + value })

对象 API 使用 HashMap<String, V>。这样 prop、path、assoc、keys 和 groupBy 在编译期就能确定值类型：

let user = HashMap<String, Int64>([("age", 21), ("score", 96)])
let updated = assoc("level", 3, user)
let age = get(user, "age", 0)

3.2 用 Option<T> 表示可能不存在的值

JavaScript 的 undefined 在仓颉中用 Option 表示。head、last、find、prop 和 path 在找不到值时返回 None，找到值时返回 Some(value)：

let score: Option<Int64> = prop("score", user)
let safeScore = score ?? 0

这样空数组、越界下标和不存在的对象键等边界行为在类型层面可见，而不是等到运行时触发空值错误。

3.3 回调函数保持参数类型

集合回调统一显式携带元素和下标；Ramda 风格的一元函数则使用明确的 (T) -> R 类型：

let names = map([1, 2, 3], { value, _ => value.toString() })
let isEven = { value: Int64 => value % 2 == 0 }
let allEven = all(isEven, [2, 4, 6])

泛型约束用于需要相等、哈希或比较的场景，例如 uniq 要求元素满足 Hashable 和 Equatable，排序辅助函数要求键满足 Comparable。这让回调的输入、输出和集合元素在编译时保持一致。

第 4 阶段：分层实现源码

4.1 核心文件 src/ramda.cj

核心文件提供最常用的集合操作、对象操作、字符串处理和数值聚合。map、filter、reduce 通过泛型保留元素类型，groupBy 返回 HashMap<String, Array>，sum 和 mean 针对明确的数值数组提供聚合结果：

let numbers = [1, 2, 3, 4, 5, 6]
let even = filter(numbers, { value, _ => value % 2 == 0 })
let total = reduce(numbers, 0, { acc, value, _ => acc + value })
let groups = groupBy(numbers, { value => if (value % 2 == 0) { "even" } else { "odd" } })

4.2 扩展文件 src/ramda_extra.cj

扩展文件实现随机、采样、排序索引、对象辅助、字符串辅助、类型判断和更多集合工具，例如 sample、sampleSize、shuffle、entries、fromPairs、startsWith、endsWith 和 zipWith。随机 API 使用可移植的伪随机实现；shuffle 返回新的数组，调用方可以检查长度和元素集合，避免修改原数组。

4.3 兼容文件 src/ramda_compat.cj

兼容文件补充 curry、curryN、rearg、overArgs、sort、sortWith、memoizeWith、lens、traverse 等需要动态参数或更复杂运行时语义的入口。ramda_compat_surface.cj 放置另一组 Ramda 名称和静态兼容签名。兼容入口尽量保持 Ramda 的命名和调用方向，但不伪造仓颉无法表达的动态参数；具体限制在第七节列出。

第 5 阶段：建立自动化测试

test/main.cj 是一个直接链接仓颉静态库的可执行程序，当前包含 17 个代表性断言，覆盖以下行为：

测试组	示例
集合变换	map、filter、reduce、uniq、splitEvery、intersperse、dropRepeats
空值和路径	head、path、prop 的 Option 结果
对象	assoc 和 HashMap<String, Int64> 的更新
数值	sum、range、mathMod
函数组合	pipe 的连续变换
组合数据	product 的笛卡尔积

断言失败会抛出异常并以非零状态退出；全部通过时输出固定标记，便于脚本或 CI 判断：

ALL RAMDA CANGJIE TESTS PASS

这些是代表性行为测试，不等于对所有 Ramda JavaScript API 和所有动态输入组合做穷举验证。

第 6 阶段：核对 Ramda 导出名称

除了行为测试，还会扫描 src/ 中的 public 声明，按集合、对象、字符串、数值、函数组合和兼容入口核对名称是否有对应的仓颉入口。这个检查用于发现拼写遗漏和重复声明，不把声明数量当成行为完成度指标。

当前结果以实际源码和测试为准：常用 API 已有可运行实现，部分动态高阶函数保留兼容入口；没有声称所有 Ramda 导出名称都已达到 JavaScript 的一比一语义。

四、完整验证步骤

以下命令均以仓库根目录 ramda/ 为当前目录。先确认已经安装的仓颉 SDK：

source ~/.zshrc
echo "$CANGJIE_HOME"
cjc --version
cjpm --version

然后构建静态库：

cjpm build

编译并运行自动化测试：

cjc test/main.cj \
  --import-path target/release/ramda \
  -L target/release/ramda \
  -lramda \
  -o /tmp/ramda-test

DYLD_LIBRARY_PATH="$CANGJIE_HOME/runtime/lib/darwin_aarch64_cjnative" \
  /tmp/ramda-test

最后编译并运行独立的终端示例。直接使用 cjc 可以清楚地看到示例链接的是刚刚构建出的本地静态库：

cjc example/example.cj \
  --import-path target/release/ramda \
  -L target/release/ramda \
  -lramda \
  -o /tmp/ramda-example

DYLD_LIBRARY_PATH="$CANGJIE_HOME/runtime/lib/darwin_aarch64_cjnative" \
  /tmp/ramda-example

example/cjpm.toml 也提供了独立的 cjpm 工程配置；如果目标机器的 SDK 链接器能够直接解析该依赖，可以在 example/ 中使用 cjpm build 和 cjpm run。当本机 cjpm 依赖构建遇到链接器环境差异时，使用上面的直接 cjc 命令仍能复现同一个示例程序。

五、运行效果

下面的输出来自 example/example.cj 的真实仓颉程序运行，调用了 Ramda 适配层中的集合、对象、Option、管道、字符串和数值函数：

Ramda from Cangjie example
even      => [2, 4, 6]
doubled   => [4, 8, 12]
sum       => 21
groupBy   => even=[2, 4, 6]
object    => age=21, level=3
option    => score=96
pipe      => 10
camelCase => helloCangjieRamda
sum/mean  => 21 / 3.500000

这些文本由 example/example.cj 中的函数调用和 println 直接生成，不是预先写死的验收文本。示例没有调用随机 API，因此每次运行的结果保持一致，适合终端截图和文档验收。

六、关键决策说明

6.1 为什么不用无类型 Any

仓颉适配的价值在于让调用方在编译期知道数据形状。若所有参数都退化成无类型值，虽然表面上接近 JavaScript，却会失去数组元素类型、对象值类型和回调返回值检查。因此项目优先使用泛型、HashMap<String, V> 和专用重载，让常见调用保持可读、可检查和可预测。

6.2 为什么保留 Ramda 函数名

保留 map、filter、pipe、assoc、path、groupBy 等名称可以降低迁移成本。熟悉 Ramda 的开发者只需要适应仓颉的参数标签、泛型约束和 Option 返回值，不必重新记忆一套完全不同的工具 API。对无法完整表达的动态能力，兼容文件提供同名的静态签名，并在文档中明确边界。

6.3 为什么把测试和示例分开

测试程序负责断言，适合自动化执行；示例工程负责展示，适合在终端中观察真实结果和截图。两者都使用同一个 Ramda 仓颉包，因此运行效果来自库的实际调用，而不是模拟输出。

七、兼容边界和遗留问题

JavaScript Ramda 与仓颉的运行时模型不同，以下限制需要在接入时提前了解：

1. JavaScript 的任意动态值、异构数组、原型派发和动态 this 没有直接的仓颉静态等价物；对象操作以 HashMap<String, V> 为边界。
2. curry、curryN、curryRight、rearg、overArgs 等高阶函数只提供仓颉能够表达的函数形状，不能接受任意数量、任意类型的 JavaScript 参数。
3. sort 和 sortWith 当前返回输入数组的副本，暂未使用传入的比较器排序；需要排序时可以使用已经实现的 sortBy，或由业务侧先完成明确类型的排序。
4. memoizeWith、部分 lens 和 transducer 相关入口保留可调用签名，但没有复刻完整的 JavaScript 缓存、镜头组合或运行时协议。
5. debounce、throttle、delay 等时间相关兼容入口是同步实现，不替代 JavaScript 事件循环和定时器队列；需要异步调度时应由宿主应用提供调度器。
6. isObject、isObjectLike、isPlainObject 等依赖 JavaScript 运行时对象标签的判断，在仓颉中采用静态类型签名和保守结果，不能承诺与 JavaScript 原型系统完全一致。
7. 随机函数使用可移植伪随机实现，适合工具库和示例，不应作为密码学随机源。

这些是当前适配的语义边界，不是构建错误。构建时出现的 unused variable 信息属于编译警告；只要 cjpm build 成功、测试程序输出通过标记，就说明当前版本已经完成本地编译和代表性行为验收。

八、接入方式

在另一个仓颉项目中，可以将本仓库作为 Git 依赖、本地依赖或发布包使用。最直接的本地验证方式是先在本仓库根目录生成 target/release/ramda，再把相同的 --import-path 和 -L 参数传给调用方的 cjc 命令。调用代码只需要导入：

import ramda.*
import std.collection.*

main(): Int64 {
    let values = filter([1, 2, 3, 4], { value, _ => value % 2 == 0 })
    let total = reduce(values, 0, { acc, value, _ => acc + value })
    println(join(values, separator: ", ") + " / " + total.toString())
    return 0
}

如果使用 cjpm 管理依赖，则将仓颉包加入项目依赖配置，再由业务工程统一构建。跨端项目可以复用相同的 API 和测试思路，具体的线程、定时器、文件系统或 UI 能力由宿主平台负责。

九、总结

本次适配完成了 Ramda 0.32.0 到仓颉静态类型模型的迁移：源码按核心、扩展、Ramda 特有 surface 和兼容层组织，数组使用 Array，对象使用 HashMap<String, V>，可能缺失的结果使用 Option，回调通过带明确参数类型的函数值表达。

验证链路包括 cjpm build、代表性自动化测试和独立终端示例。最终运行效果来自真实的仓颉可执行程序，能够直观看到三方库在集合、对象、字符串、数值、Option 和函数管道场景中的输出。对于无法一比一映射 JavaScript 动态语义的部分，项目通过静态签名和文档边界保持行为可解释，方便后续继续扩展。

适配过程 FAQ

以下问题来自仓颉工程创建、cjpm 依赖、与 HarmonyOS 设备联调的实际流程。

Q1：cjpm 依赖解析失败或拉取超时？

• 检查 cjpm.toml 中的依赖坐标与版本号；
• 配置可用的仓颉包仓库镜像或代理；
• 删除 target、cjpm.lock 后重新执行 cjpm update / cjpm build。

Q2：编译报找不到仓颉 SDK 或 cjc 版本不匹配？

• 设置 CANGJIE_HOME 指向仓颉 SDK 根目录；
• 确认 cjc --version、cjpm --version 与工程要求的版本一致；
• 清理构建缓存后重新生成。

Q3：与 HarmonyOS 设备联调时安装失败？

• 用 hdc list targets 确认设备在线；
• 确认 HAP 已签名，bundleName 与签名 profile 一致；
• 设备需加入调试 profile 的 deviceIds。

Q4：动态库或 FFI 符号找不到？

• 检查导出符号名称、ABI 与打包路径；
• 确认 .so 已随 HAP 一起打包到 libs/<abi>/；
• 用 llvm-readelf -d 检查依赖库是否齐全。

Q5：测试用例在设备上失败，但本机通过？

• 对比设备与主机的架构、SDK 版本和环境变量；
• 用 hdc hilog 抓取运行日志；
• 优先复现最小用例，确认是否为平台差异或时序问题。

十、参考资料

• AtomGit 项目仓库：Ramda 仓颉适配
• Ramda 官方文档
• 仓颉语言官方文档
• 仓颉项目管理工具 cjpm