Saml通信组件

项目背景与战略目标

Saml通信组件旨在为仓颉语言生态提供完整的 SAML 2.0 协议支持，用于构建企业级身份联合（Federated Identity）和单点登录（SSO）系统。该项目将充分利用仓颉编程语言 1.0.0+ 的内存安全特性（杜绝空指针、缓冲区溢出等 CVE 类漏洞）、轻量级线程模型（实现高并发低开销的协议处理）以及强类型系统（保障 XML 结构与安全策略的类型一致性），打造一个高性能、高可靠、可审计的安全认证基础设施组件。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：单节点 QPS ≥ 5000（Assertion 验证场景），吞吐量较 Java OpenSAML 提升 30%。

• 安全要求：通过仓颉编译期内存安全检查，杜绝运行时内存错误；所有加密操作使用经过 FIPS 140-2 验证的底层库（通过 CJNative 封装）。

• 可靠性：资源自动回收（RAII 模式），异常路径全覆盖，服务无单点崩溃风险。

• 可维护性：模块解耦清晰，接口契约明确，符合仓颉官方编码规范。

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

interface SamlService {
    fn validateAssertion(encrypted: XmlString, cert: X509Cert) -> Result<ValidAssertion, SamlError>
    async fn processAuthnRequest(req: AuthnRequest, binding: BindingType) -> Result<SamlResponse, SamlError>
}

enum SamlError {
    InvalidSignature,
    ExpiredAssertion,
    CertificateNotTrusted,
    MalformedXml,
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：SAML 2.0 核心消息模型 + XML 解析/序列化 + 单元测试（覆盖率≥95%）+ 接口文档

• 第二阶段：签名/加密模块 + HTTP/SOAP 绑定适配 + 集成测试（含 Shibboleth IDP 对接）

• 第三阶段：性能调优报告 + 生产部署指南 + cjpm 发布包（支持 cjpm install saml-cj）

3.2 项目实施路线图

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

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt 格式校验，禁止手动内存管理。

• 类型安全：所有 XML 字段映射为强类型 struct，避免字符串拼接；使用代数数据类型表达协议状态。

• 错误处理：所有公开接口返回 Result<T, E>，错误类型显式声明，禁止 panic 传播至调用边界。

4.2 测试与验证标准

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

• 性能基准：建立 cjpm bench 基准集，监控 Assertion 验证、元数据解析等关键路径。

• 安全扫描：集成仓颉静态分析工具，确保无未初始化变量、悬垂指针等隐患。

4.3 文档与可维护性

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

• 架构决策记录（ADR）：记录 XML 解析策略（DOM vs Streaming）、加密库选型等关键决策。

• 贡献指南：提供 CONTRIBUTING.md，明确开发环境搭建、调试命令、PR 流程。

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, cjpm coverage

• 环境要求：开发机需安装仓颉 1.0.0+ 工具链；CI 使用 cangjie-lang/ci: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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求