net-snmp

项目背景与战略目标

net-snmp 是一个实现了简单网络管理协议（SNMP）v1、v2c 和 v3 的库，广泛用于设备监控、网络管理和运维自动化场景。在仓颉生态中，亟需一个内存安全、高并发、强类型的原生 SNMP 协议库，以替代传统 C/C++ 实现中存在的安全风险和性能瓶颈。本项目将充分利用仓颉语言 1.0.0+ 的核心优势——编译期内存安全（杜绝空指针、缓冲区溢出等 CVE 类漏洞）、轻量级线程模型（支持万级并发连接）、强类型系统与代数数据类型（提升协议解析可靠性），构建一个高性能、高可靠、可嵌入微服务架构的 SNMP 后端通信库，为 OpenHarmony 及更广泛的仓颉后端生态提供标准化网络管理能力。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：

  • P99 请求延迟 < 10ms（局域网环境）

  • 吞吐量 ≥ 50K QPS（GET 请求，对比 Net-SNMP C 库提升 ≥ 30%）

  • 内存占用 ≤ 5MB（空闲 Agent 实例）

• 安全要求：

  • 100% 通过仓颉编译器内存安全检查，无运行时 panic（除业务逻辑错误）

  • 密钥材料生命周期受所有权严格管控，禁止全局可变状态

  • 支持 FIPS 140-2 兼容加密算法（通过 CJNative 绑定）

• 可靠性：

  • 网络异常自动重连（可配置策略）

  • 资源（socket、buffer）100% RAII 自动回收

  • 完善的错误链（Error Chaining）追踪故障根源

• 可维护性：

  • 模块间通过清晰接口（interface）解耦

  • 协议解析与业务逻辑分离

  • 符合仓颉官方编码规范（cjfmt 100% 通过）

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

// SNMP 协议错误类型
enum SnmpError {
    Timeout,
    AuthFailure(String),
    ParseError(String),
    NetworkError(IoError),
}

// 核心会话接口
interface SnmpSession {
    // 异步 GET 请求，显式错误处理
    fn get(oids: [String]) -> Result<[VarBind], SnmpError>
    
    // 高并发 BULK 操作
    async fn getBulk(
        oids: [String],
        nonRepeaters: U32,
        maxRepetitions: U32
    ) -> Result<[VarBind], SnmpError>
    
    // 发送 Trap（支持 v2c/v3）
    fn trap(
        oid: String,
        varbinds: [VarBind]
    ) -> Result<Void, SnmpError>
}

// 变量绑定结构（强类型）
struct VarBind {
    oid: String,
    value: SnmpValue, // 枚举：Integer/OctetString/Counter64 等
}

// Agent 回调处理器
interface AgentHandler {
    // 处理 GET/SET 请求
    fn handle(request: SnmpRequest) -> Result<SnmpResponse, SnmpError>
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：SNMPv1/v2c 核心协议栈 + 基础 Session API + 单元测试（覆盖率≥95%） + 接口文档

• 第二阶段：SNMPv3 安全模块 + Agent/Receiver 实现 + 集成测试（兼容主流 NMS 如 Zabbix） + 性能压测报告

• 第三阶段：MIB 动态注册框架 + cjpm 发布包 + 生产部署指南（含 TLS/DTLS 扩展设计）

3.2 项目实施路线图

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

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt --check，禁止手动内存管理（禁用 unsafe）

• 类型安全：

  • 所有 OID 操作使用 OidPath 新类型封装，防止字符串拼接错误

  • SNMP 版本通过枚举 SnmpVersion { V1, V2c, V3 } 强制区分

• 错误处理：所有 public API 返回 Result<T, E>，禁止抛出未声明异常

4.2 测试与验证标准

• 单元测试：核心模块行覆盖率 ≥ 95%（cjpm test --coverage 验证）

• 性能基准：

  • 建立 benches/snmp_bench.cj 对比 Net-SNMP C 库

  • 监控关键路径（如 getBulk）的 CPU cycles/allocations

• 安全扫描：集成 cj-analyzer 进行数据流污染检测

4.3 文档与可维护性

• API 文档：所有 public 函数/结构体包含 /// 注释，说明参数、错误码、线程安全级别

• 架构决策记录：

  • ADR-01：为何选择异步 I/O 而非多线程模型

  • ADR-02：ASN.1 解析器的零拷贝设计

• 贡献指南：明确 PR 需包含：单测 + 基准测试 + 协议兼容性说明

4.4 持续集成质量门禁

# PR 自动化流水线
cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench --baseline=main
# 安全扫描（待集成）
cj-analyzer run --rules=snmp-security

技术栈与开发环境

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

• 构建工具：CJPM (Cangjie Package Manager)

• 测试框架：@std/testing 原生测试库

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

• 开发环境：

  • 本地：仓颉 1.0.0+ SDK（Linux/macOS）

  • CI：cangjie-lang/cjci:1.0.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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求