@ohos/basic-ftp

项目背景与战略目标

@ohos/basic-ftp 是一个提供 FTP 和 FTPS（FTP over TLS）协议支持的客户端库，用于在 OpenHarmony 生态中实现文件上传、下载、目录管理等远程文件操作。在仓颉后端生态中，此类协议客户端是构建自动化运维工具、跨平台同步服务、边缘设备数据回传等场景的关键组件。本项目将基于仓颉语言 1.0.0+ 的核心能力——编译期内存安全（彻底消除缓冲区溢出、空指针解引用等 CVE 风险）、轻量级并发模型（通过 async/await 实现高吞吐 I/O）、强类型系统与所有权机制（保障连接状态一致性），打造一个内存安全、高可靠、可嵌入微服务架构的原生 FTP/FTPS 客户端库。该库将全面支持被动模式、MLSD 目录解析、隐式/显式 TLS 加密，并为仓颉生态提供标准化的文件传输基础设施。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：

  • 单连接吞吐 ≥ 600 MB/s（局域网 SSD 环境）

  • 目录列表解析速度 ≤ 1ms/条（MLSD 格式）

  • 内存占用 ≤ 8 MB（空闲客户端实例）

• 安全要求：

  • 所有网络输入经边界检查，杜绝整数溢出

  • 密码/证书材料生命周期受所有权严格管控

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

• 可靠性：

  • 网络中断自动重连（可配置策略）

  • 控制/数据连接状态机原子更新，避免中间态

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

• 可维护性：

  • 协议逻辑与传输层解耦

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

  • 代码 100% 通过 cjfmt 格式化

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

// FTP 协议错误类型
enum FtpError {
    ConnectionFailed(IoError),
    AuthRejected(String),
    FileNotFound,
    TlsHandshakeFailed(TlsError),
}

// 文件信息（强类型）
struct FileInfo {
    name: String,
    size: U64,
    modified: DateTime,
    isDir: Bool,
    permissions: UnixPermissions, // enum 封装 rwx 位
}

// 安全选项（FTPS）
struct TlsOptions {
    cert: Option<String>, // PEM 路径
    key: Option<String>,
    ca: [String],
    protocols: [TlsProtocol], // TLSv12/TLSv13
}

// 核心客户端接口
interface FtpClient {
    // 登录（支持 plain/implicit/explicit TLS）
    async fn login(
        host: String,
        port: U16,
        user: String,
        password: String,
        secure: SecureMode,
        tlsOpts: Option<TlsOptions>
    ) -> Result<Void, FtpError>
    
    // 获取目录列表
    async fn list(path: String) -> Result<[FileInfo], FtpError>
    
    // 上传文件（支持进度回调）
    async fn upload(
        localPath: String,
        remotePath: String,
        onProgress: FnMut(U64, U64)
    ) -> Result<Void, FtpError>
    
    // 下载文件
    async fn download(
        remotePath: String,
        localPath: String,
        onProgress: FnMut(U64, U64)
    ) -> Result<Void, FtpError>
    
    // 安全退出
    async fn quit() -> Result<Void, FtpError>
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：FTP 核心命令实现（login/list/upload/download） + 被动模式支持 + 单元测试（覆盖率≥95%） + 接口文档

• 第二阶段：FTPS 隐式/显式 TLS 集成 + 目录格式解析器 + 高并发压力测试（1K 任务） + 与 vsftpd/ProFTPD 兼容性验证

• 第三阶段：性能调优报告 + cjpm 发布包 + 生产部署指南（含弱网/断点续传示例）

3.2 项目实施路线图

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

4.1 仓颉语言专项质量规范

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

• 类型安全：

  • FTP 响应码映射为枚举（如 ResponseCode::FileActionOk）

  • 远程路径使用 RemotePath 新类型封装，防止注入攻击

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

4.2 测试与验证标准

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

• 性能基准：

  • 建立 benches/ftp_bench.cj 对比 Python ftplib/Go net/ftp

  • 监控 list() 和 upload() 的内存分配次数

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

4.3 文档与可维护性

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

• 架构决策记录：

  • ADR-01：为何仅支持被动模式（主动模式 NAT 不友好）

  • ADR-02：TLS 配置的 CJNative 绑定方案

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

过程质量要求