ohos-beacon-library

项目背景与战略目标

super_fast_file_trans（SFFT）是一款面向大文件传输场景的三方库，提供多线程并发下载、分片上传、断点续传、自动重试等核心能力。在仓颉后端生态中，此类高性能文件传输库是构建云存储客户端、内容分发服务、边缘同步代理等系统的关键基础设施。本项目将充分利用仓颉语言 1.0.0+ 的核心优势——编译期内存安全（彻底杜绝缓冲区溢出、Use-After-Free 等 CVE 类漏洞）、轻量级并发模型（通过 async/await 实现高吞吐低开销 I/O）、强类型系统与所有权机制（保障任务状态一致性），打造一个内存安全、高可靠、可嵌入微服务架构的原生文件传输库。该库将显著提升 OpenHarmony 及仓颉后端应用在弱网、高并发、大文件场景下的传输效率与稳定性。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：

  • 多线程下载吞吐 ≥ 800 MB/s（局域网 SSD 环境）

  • 分片上传 CPU 开销 ≤ 5%（1 Gbps 网络）

  • 内存占用 ≤ 10 MB（空闲任务管理器）

• 安全要求：

  • 所有文件路径经沙箱校验，防止路径遍历

  • 证书配置通过 CJNative 调用系统安全库，密钥不驻留内存

  • 100% 通过仓颉编译器内存安全检查

• 可靠性：

  • 网络异常自动重试（可配置次数/策略）

  • 临时文件 100% RAII 清理，无残留

  • 任务状态变更原子化，避免中间态

• 可维护性：

  • 下载/上传逻辑通过泛型抽象共用核心调度器

  • 接口设计符合仓颉惯用法（如 impl Display for ProgressInfo）

  • 代码 100% 通过 cjfmt 格式化

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

// 传输错误类型
enum TransferError {
    Network(IoError),
    AuthFailed(String),
    FileNotFound,
    ChunkCorrupted(U64), // 分片校验失败
}

// 下载配置（强类型）
struct DownloadConfig {
    url: String,
    fileName: String,
    concurrency: U32, // 默认 2
    isBreakpointResume: Bool,
    securityConfig: Option<SecurityConfig>,
}

// 传输进度
struct TransferProgress {
    totalSize: U64,
    transferredSize: U64,
    speed: F64, // KB/s
}

// 核心任务接口
interface TransferTask {
    // 启动传输（异步）
    async fn start() -> Result<Void, TransferError>
    
    // 暂停并保存进度
    fn pause() -> Result<TransferProgress, TransferError>
    
    // 恢复传输
    async fn resume() -> Result<Void, TransferError>
    
    // 取消并清理资源
    fn cancel() -> Result<Void, TransferError>
    
    // 获取实时进度
    fn getProgress() -> TransferProgress
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：基础下载/上传任务框架 + 断点续传核心逻辑 + 单元测试（覆盖率≥95%） + 接口文档

• 第二阶段：多线程分片调度 + HTTPS 双向认证 + 高并发压力测试（1K 任务） + 中间件集成

• 第三阶段：性能调优报告 + cjpm 发布包 + 生产部署指南（含弱网模拟测试用例）

3.2 项目实施路线图

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

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt --check，禁止使用 unsafe 块

• 类型安全：

  • 文件路径使用 FilePath 新类型封装，防止字符串拼接漏洞

  • 并发分片状态通过 Arc<Mutex<ChunkState>> 显式管理

• 错误处理：所有 public API 返回 Result<T, TransferError>，禁止隐式 panic

4.2 测试与验证标准

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

• 性能基准：

  • 建立 benches/transfer_bench.cj 对比 Go/Java 实现

  • 监控分片调度器的上下文切换开销

• 安全扫描：集成 cj-analyzer 检测路径遍历、证书硬编码等风险

4.3 文档与可维护性

• API 文档：所有 public 接口包含 /// 注释，说明线程安全性和资源释放要求

• 架构决策记录：

  • ADR-01：为何选择分片而非流式传输

  • ADR-02：进度持久化方案选型（SQLite vs 文件）

• 贡献指南：明确 PR 需包含：弱网测试报告 + 基准测试对比

4.4 持续集成质量门禁

# 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)

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

过程质量要求