copa

项目背景与战略目标

CoAP（Constrained Application Protocol）是专为资源受限设备设计的轻量级应用层协议，广泛应用于物联网（IoT）、边缘计算和 M2M 通信场景。当前 ohos_coap 基于 C 语言 libcoap 封装，存在内存安全风险与跨平台维护成本高的问题。本项目旨在基于仓颉编程语言（Cangjie Language）1.0.0+ 从零构建一个纯仓颉实现的 CoAP 协议库，充分发挥仓颉语言在内存安全（杜绝 CVE-2024-31031 类漏洞）、轻量级线程（支撑万级设备并发连接）和强类型系统（减少协议解析错误）方面的优势，打造一个高性能、高可靠、可嵌入微服务或边缘网关的 CoAP 通信基础设施，填补仓颉生态在物联网协议栈的关键空白。

核心功能需求与技术规格

2.1 功能模块分解

表格

2.2 非功能性需求规范

• 性能指标：单请求 P99 延迟 < 10ms（局域网）；服务端吞吐量 ≥ 10,000 QPS；内存占用 ≤ 1KB/连接。

• 安全要求：彻底消除缓冲区溢出、空指针解引用等内存安全漏洞；敏感操作（如 Option 解析）经静态分析验证。

• 可靠性：所有网络 I/O 必须包裹错误处理；连接异常自动释放资源；支持重试与超时配置。

• 可维护性：协议层、传输层、应用层解耦；接口符合仓颉惯用法；100% 通过 cjpm lint。

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

cangjie

编辑

interface CoapClient {
    fn request(
        uri: String,
        method: CoapMethod,
        msgType: CoapMessageType
    ) -> Future<Result<CoapResponse, CoapError>>;
    
    fn setPayload(payload: Bytes) -> Unit;
    fn setOption(optionNum: U16, value: Bytes) -> Unit;
    fn setBlockMode(mode: BlockMode) -> Unit;
}

interface CoapServer {
    fn registerResource(path: String, handler: ResourceHandler) -> Unit;
    fn start(port: U16) throws NetworkError -> Unit;
    fn stop() -> Unit;
}

enum CoapError {
    Timeout,
    InvalidUri,
    PayloadTooLarge,
    NetworkUnreachable,
}

fn handleGetRequest(req: CoapRequest) -> CoapResponse {
    if req.path == "/sensor/temp" {
        return CoapResponse::new(CoapCode::Content, "23.5°C".toBytes());
    }
    CoapResponse::new(CoapCode::NotFound, Bytes::empty())
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：CoAP 报文解析器 + 客户端 GET/POST/PUT + 服务端基础路由 + 单元测试（覆盖率≥95%）

• 第二阶段：块传输（Block1/Block2）支持 + 并发模型优化 + 与 libcoap/californium 互操作测试

• 第三阶段：性能调优报告 + 生产部署指南 + cjpm 发布包（v1.0.0）

3.2 项目实施路线图

表格

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

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt 格式化，禁止手动调整缩进或绕过类型检查。

• 类型安全：所有 Option 编号、方法、状态码使用枚举而非原始整数；泛型用于泛化请求/响应处理。

• 错误处理：所有 public API 必须返回 Result 或声明 throws，禁止静默忽略错误。

• 资源管理：CoapClient 和 CoapServer 实现 Drop trait，确保 UDP socket 自动关闭。

4.2 测试与验证标准

• 单元测试：协议解析、状态机、错误路径覆盖率 ≥ 95%（cjpm test --coverage 验证）。

• 集成测试：与开源 CoAP 服务（Californium, libcoap）进行端到端互操作测试。

• 安全扫描：通过 cjpm analyze --security 及自定义规则检测潜在协议解析漏洞。

4.3 文档与可维护性

• API 文档：所有 public 接口包含 /// 注释，说明线程安全性、生命周期约束。

• ADR：记录为何选择纯仓颉实现而非绑定 libcoap、块传输状态机设计等关键决策。

• 贡献指南：提供 CONTRIBUTING.md，说明如何运行测试、模拟网络故障、提交 PR。

4.4 持续集成质量门禁

bash

编辑

# PR 自动化流水线
cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench --baseline=main

技术栈与开发环境

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

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

• 测试框架：仓颉原生 test 模块 + 自定义网络 mock 层

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

• CI 环境：基于 cangjie-lang/cangjie:1.0.0 官方 Docker 镜像的 GitHub Actions / GitLab CI 流水线

交付件

验收标准

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

过程质量要求