@ohos/amqplib

项目背景与战略目标

@ohos/amqplib 旨在为 OpenHarmony 及仓颉语言生态提供原生 AMQP 0-9-1 协议支持，用于构建高可靠、松耦合的分布式系统通信基础设施。该项目将深度利用仓颉编程语言 1.0.0+ 的核心优势：内存安全（杜绝因帧解析或缓冲区管理导致的 CVE 漏洞）、轻量级线程模型（高效支撑万级并发 Channel 与消息流）、强类型系统（精确建模 AMQP 帧结构与状态机）以及 CJNative 性能（无缝对接底层 RabbitMQ/C++ 客户端），打造一个适用于物联网边缘计算、微服务异步通信和任务队列场景的高性能后端消息库。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：单连接消息吞吐量 ≥ 15,000 msg/s（1KB 消息），较 Node.js amqplib 提升 40%。

• 安全要求：所有网络输入经仓颉编译期边界检查，彻底消除缓冲区溢出、整数溢出等风险。

• 可靠性：自动重连、通道重建、消息确认机制完备，服务中断后可自愈。

• 可维护性：协议状态机清晰分离，接口符合 AMQP 规范，代码符合仓颉编码标准。

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

interface AmqpConnection {
    async fn createChannel() -> Result<AmqpChannel, AmqpError>
    fn close(self)
}

interface AmqpChannel {
    async fn declareQueue(name: String) -> Result<QueueInfo, AmqpError>
    async fn publish(exchange: String, routingKey: String, body: Bytes) -> Result<(), AmqpError>
    async fn consume(queue: String, handler: Message -> Result<AckAction, AmqpError>) -> Result<ConsumerTag, AmqpError>
}

enum AmqpError {
    ConnectionClosed,
    ChannelError(String),
    FrameDecodingFailed,
    AuthenticationFailed,
}

enum AckAction {
    Ack,
    NackRequeue,
    Reject,
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：AMQP 0-9-1 帧编解码器 + 基础 Connection/Channel + 单元测试（覆盖率≥95%）+ 接口文档

• 第二阶段：完整消息收发（publish/consume/ack）+ TLS 支持 + 与 RabbitMQ 3.12+ 集成测试

• 第三阶段：性能调优报告 + OpenHarmony 设备适配指南 + cjpm 发布包（@cangjie/amqplib）

3.2 项目实施路线图

技术实现规范与质量认证体系

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt 格式校验，禁止 unsafe 代码。

• 类型安全：AMQP 方法帧使用代数数据类型建模；所有字段绑定为强类型（如 ShortString、LongLong）。

• 错误处理：所有公开方法返回 Result<T, AmqpError>，错误携带上下文信息，支持链式处理。

4.2 测试与验证标准

• 单元测试：协议编解码、状态机等核心模块行覆盖率 ≥95%（cjpm test --coverage 验证）。

• 性能基准：建立 cjpm bench 套件，监控 publish/consume 关键路径。

• 安全扫描：通过仓颉静态分析工具确保无未初始化内存、数据竞争等问题。

4.3 文档与可维护性

• API 文档：所有 public 接口包含 Doc Comments，支持自动生成 Web 文档。

• 架构决策记录（ADR）：记录帧解析策略（零拷贝 vs 缓冲区复制）、异步模型选型等关键决策。

• 贡献指南：提供 CONTRIBUTING.md，明确协议开发模板、RabbitMQ 测试环境搭建流程。

4.4 持续集成质量门禁

cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench

技术栈与开发环境

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

• 构建与包管理：CJPM（Cangjie Package Manager）

• 测试框架：仓颉原生测试框架（支持 async 和集成测试）

• 质量工具：cjfmt, cjpm lint, cjpm bench

• 环境要求：开发机需安装仓颉 1.0.0+ 工具链；CI 使用 cangjie-lang/ci:1.0.0 官方 Docker 镜像，并集成 RabbitMQ 测试容器

交付件

验收标准

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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求