贡献指南

感谢参与 ACE。本文约定开发流程与代码规范。

环境

source scripts/env.sh   # 每个 shell 必做:设 SDKROOT(MacOSX15.sdk)+ DYLD_LIBRARY_PATH(openssl@3),否则链接失败
cjpm build
cjpm test               # 全 workspace 单测,提交前必须全绿

本机构建绕过(macOS 26 / cjc 1.1.0-alpha)与 stdx 预编译接入详见 CLAUDE.md。改 stdx 相关 cjpm.toml 前先读 doc/roadmap-m12-plus.md。

架构约束

• 零运行时反射:声明式能力一律用编译期宏生成等价显式代码,保留 --debug-macro 可审计;不引入运行时反射/枚举。
• 内核 stdx-free:ace-web/ace-router/ace-bodyparser/ace-framework-runtime 不依赖 stdx;仅 ace-http、ace-security、智能体 claude 层接触 stdx。新能力优先做成 stdx-free 可单测的 module。
• 小而组合:每个能力一个可单独引入的 module(高内聚、可单测);新增成员后加入根 cjpm.toml 的 [workspace].members。
• 能力皆中间件:横切关注点优先做中间件或专用方法宏,不做通用反射式 AOP。

工作流

1. TDD:先写 *_test.cj(红)→ 实现(绿)→ 重构;纯逻辑(校验/解析/限流等)做成可单测纯函数,时间/IO 依赖以注入方式隔离(如 RateLimiter 注入 nowMs、verifyJwtAt 注入 nowSec)。
2. 宏特性:用 examples/di-demo(或新增 example)做端到端集成验证(宏消费需独立包,不便直接单测)。
3. 构建/测试全绿:cjpm test 必须 0 失败再提交。
4. 代码审查:横切/安全/宏改动建议过 code-reviewer。

编码规范

• 不可变优先:始终创建新对象,不修改入参;Bean 注入字段用 let。
• 小文件聚焦:200–400 行,函数 <50 行,嵌套 <4 层。
• 全面错误处理:Option/Result/try-catch;不泄露敏感信息(错误响应统一脱敏)。
• 无硬编码密钥(走环境变量,如 ANTHROPIC_API_KEY)。
• 命名清晰,无遗留调试输出。

仓颉/宏踩坑(本仓库已踩)

• 宏生成多条语句必须 ; 分隔(否则 token 粘连);卫生命名用双下划线前缀(__ret/__b/__dto)。
• ArrayList 用 .add、Tokens 用 .append;字符串按字节处理,字节字面量带 u8 后缀。
• 闭包捕获并重新赋值 var 不可靠 → 用引用类型累积(ArrayList)。
• std.regex 用 POSIX [0-9],不认 \d。
• member 目录名(ace-router)≠ 包名(aceboot::router)时,用整 cjpm test(或 -m)。

提交信息

约定式提交:<type>: <description>,type ∈ feat/fix/refactor/docs/test/chore/perf/ci。简洁专业,不加签名/emoji。

版本

语义化版本;0.x API 未稳定。稳定性分级见 README.md →「版本与 API 稳定性」。