jackrabbit

第一部分：项目背景与战略目标
jackrabbit 是一个面向 RabbitMQ 的 AMQP（Advanced Message Queuing Protocol）通信库，提供交换机、队列、发布/消费、RPC 等核心消息模式抽象，属于典型的后端中间件基础设施。当前实现依赖 JavaScript 生态的 amqplib，在 OpenHarmony 等受限环境中存在性能瓶颈与内存安全隐患。本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+ 的核心优势——编译期内存安全（杜绝缓冲区溢出、UAF 等 CVE）、轻量级线程模型（支持万级并发连接）、强类型系统（精准建模 AMQP 帧结构）以及 CJNative 高性能 FFI 能力，构建一个原生、高效、可嵌入微服务或边缘设备的 AMQP 客户端库。该库将为仓颉生态提供可靠的消息传递基座，支撑事件驱动架构、任务分发、服务解耦等关键后端场景。

第二部分：核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：单连接消息吞吐量 ≥ 50,000 msg/s（对比 Node.js amqplib 提升 ≥30%），P99 发布延迟 < 5ms。

• 安全要求：完全消除内存安全漏洞；敏感凭证（如密码）在安全内存中处理，禁止明文日志输出。

• 可靠性：网络闪断、服务端重启等异常下自动恢复会话状态；消息确认机制防止丢失。

• 可维护性：模块高内聚低耦合，协议层与业务抽象层分离；接口设计符合仓颉惯用法。

2.3 核心接口设计示例 (伪代码)

interface AmqpClient {
    // 创建连接
    fn connect(url: String): Result<Connection, AmqpError>

    // 获取默认直连交换机
    fn defaultExchange(conn: &Connection): Result<Exchange, AmqpError>

    // 声明队列并绑定
    fn declareQueue(
        exchange: &Exchange,
        name: String,
        options: QueueOptions
    ): Result<Queue, AmqpError>

    // 发布消息
    fn publish<T: Serializable>(
        exchange: &Exchange,
        message: T,
        routingKey: String,
        props: PublishProperties
    ): Result<Void, AmqpError>

    // 异步消费
    async fn consume<T: Deserializable>(
        queue: &Queue,
        handler: fn(T, Acknowledger) -> Void,
        options: ConsumeOptions
    ): Result<Void, AmqpError>
}

enum AmqpError {
    ConnectionRefused,
    InvalidCredentials,
    ChannelClosed,
    SerializationFailed(String),
    Timeout
}

第三部分：项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：AMQP 帧解析器、连接/信道管理、基础 Exchange/Queue 抽象 + 单元测试（覆盖率≥95%）+ 接口文档

• 第二阶段：完整消息模式支持（fanout/topic/RPC）、自动重连、背压控制 + 集成测试（与 RabbitMQ 3.10+ 互操作）+ 压测报告

• 第三阶段：性能调优报告、OpenHarmony HAP 示例、cjpm 发布包（支持标准 Linux 与 OHOS）

3.2 项目实施路线图

第四部分：技术实现规范与质量认证体系

4.1 仓颉语言专项质量规范

• 100% 通过 cjfmt 格式校验，禁止手动调整代码风格。

• 所有外部输入（如 URL、路由键）经强类型验证，禁止字符串拼接构造协议字段。

• 错误路径必须返回 Result<T, E>，禁止使用 panic 处理业务异常。

4.2 测试与验证标准

• 单元测试覆盖所有协议帧类型、连接状态转换、错误边界条件，行覆盖率 ≥95%。

• 建立 AMQP 协议模糊测试（fuzzing）套件，持续验证协议解析鲁棒性。

• 使用仓颉 sanitizer 工具链进行内存安全与并发数据竞争检测。

4.3 文档与可维护性

• 所有 public 接口需包含 Doc Comments，说明线程安全级别、生命周期约束及错误码含义。

• 记录关键架构决策（如为何选择同步 vs 异步 I/O 模型）至 ADR 文档。

• 提供 CONTRIBUTING.md 明确本地构建、RabbitMQ 测试环境搭建、PR 提交流程。

4.4 持续集成质量门禁

cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench --baseline=node-amqplib-v0.10

第五部分：技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0+（强制）

• 构建与包管理：CJPM (Cangjie Package Manager)

• 测试框架：仓颉原生测试框架（支持异步测试与 mock）

• 质量工具：cjfmt, cjpm lint, cjpm bench, cj-sanitizer

• 环境要求：Linux 开发环境（RabbitMQ 3.10+ 测试集群），CI 使用 cangjie-lang/cjci:1.0 官方 Docker 镜像

交付件

验收标准

1.功能

1. 三方库必须有明确的功能；

2. 如果参考对标库移值开发，功能与参考三方库保持一致。

2.资料

1. Readme：包含简介，软件架构，目录结构，下载安装（编译构建），接口说明，使用示例，约束限制，开源协议，参与贡献等内容；

2. Changelog，三方库版本需包含基本的修改说明。

3.标准遵从性（可选），三方库实现需满足对应协议或行业标准，举例

1. appquth：支持对OAuth 的PKCE扩展；

2. icu4j：支持unicode标准库，通用字符集ISO/IEC 10646。

4.性能目标

1. 性能敏感三方库接口运行性能持平对标三方库

5.开源协议遵从，必须包含License文件

1. 放置合适的开源License协议，建议Apache License Version 2.0；

2. 引用或参考开源三方库，需遵从开源协议。

6.网络安全要求

1. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求