angus-mail

项目背景与战略目标

邮件系统作为企业级应用和自动化服务的关键通信基础设施，其后端组件需具备高可靠性、强安全性与良好的协议兼容性。Angus Mail 提供了 Jakarta Mail 规范的完整实现，涵盖 SMTP 发信、IMAP/POP3 收信、MIME 解析、附件处理及 SSL/TLS/OAuth 2.0 安全机制。本项目旨在基于仓颉编程语言（Cangjie Language）1.0.0+ 构建一个原生、高性能、内存安全的邮件客户端库，填补仓颉生态在标准邮件协议支持上的空白。通过利用仓颉的内存安全特性（杜绝缓冲区溢出、空指针等 CVE 风险）、轻量级并发模型（高效管理多连接会话）以及强类型系统（精准建模 MIME 结构与协议状态机），打造适用于微服务、通知系统、自动化运维等场景的现代化邮件通信核心组件。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：单实例支持 ≥1K 并发邮件发送任务；SMTP 发信 P99 延迟 < 200ms（对比 JavaMail 性能持平或更优）。

• 安全要求：编译期杜绝内存安全漏洞；敏感信息（密码、token）不以明文长期驻留内存。

• 可靠性：网络中断自动重试；异常邮件格式不导致崩溃；支持超时与熔断机制。

• 可维护性：协议实现解耦，便于单独升级 SMTP 或 IMAP 模块；接口设计符合仓颉惯用法。

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

// 邮件传输服务接口
interface MailTransport {
    async fn send(mail: MimeMessage, auth: AuthInfo) -> Result<(), MailError>;
    fn close() -> Result<(), MailError>;
}

// 邮件获取服务接口
interface MailStore {
    async fn connect(auth: AuthInfo) -> Result<Self, MailError>;
    async fn fetch_messages(folder: String) -> Result<Vec<MimeMessage>, MailError>;
}

// 业务错误类型
enum MailError {
    ConnectionFailed(String),
    AuthenticationFailed,
    ProtocolViolation(String),
    TlsHandshakeError,
    InvalidMimeStructure,
}

// 示例：发送邮件
async fn send_email(
    transport: &mut SmtpTransport,
    msg: MimeMessage,
    creds: SmtpCredentials
) -> Result<(), MailError> {
    transport.authenticate(creds).await?;
    transport.send(msg).await
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：SMTP 客户端核心 + MIME 构建器 + 单元测试（覆盖率≥95%） + 接口文档

• 第二阶段：IMAP/POP3 支持 + OAuth 2.0 集成 + 集成测试（对接 Gmail/Outlook）

• 第三阶段：连接池优化 + 生产部署指南 + cjpm 包发布

3.2 项目实施路线图

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

4.1 仓颉语言专项质量规范

• 编码规范：严格遵循 cjfmt 格式，禁止手动内存管理（除非 CJNative 封装层）。

• 类型安全：MIME 结构使用嵌套 struct 与 enum 建模，避免 Any 或动态类型。

• 错误处理：所有 I/O 和解析操作返回 Result<T, MailError>，禁止 panic。

4.2 测试与验证标准

• 单元测试：协议解析、MIME 构建等核心模块行覆盖率 ≥95%。

• 集成测试：覆盖主流邮件服务商的真实交互场景（使用测试账号）。

• 安全扫描：通过仓颉静态分析工具确保无内存安全问题；敏感字段使用 Zeroize 清理。

4.3 文档与可维护性

• API 文档：所有 public 接口含 /// 注释，说明参数、错误码、线程安全级别。

• ADR：记录 TLS 库选型（BoringSSL vs native）、异步模型（async/await vs callback）等决策。

• 贡献指南：明确本地测试邮箱配置、OAuth 凭据管理流程。

4.4 持续集成质量门禁

cjpm fmt --check
cjpm build
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench
# 安全检查（可选）
cangjie-analyzer memory-safety .

技术栈与开发环境

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

• 构建与包管理：CJPM

• 网络与安全：仓颉标准异步 I/O 库 + CJNative 封装 TLS 库（如 BoringSSL）

• 测试框架：仓颉原生 test 模块，支持异步测试

• CI 环境：官方 cangjie-lang/cangjie:1.0 Docker 镜像，支持 Linux/macOS 构建

交付件

验收标准

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

过程质量要求