smbj

项目背景与战略目标

smbj 是一个用于与 SMB（Server Message Block）协议服务器交互的 Java 客户端库，支持 SMB2/SMB3 协议，广泛应用于企业级文件共享、远程存储访问等后端场景。本项目旨在基于仓颉编程语言（Cangjie Language）1.0.0+ 重构或实现一个高性能、内存安全的 SMB 客户端库。通过利用仓颉语言的内存安全特性（杜绝空指针、缓冲区溢出等 CVE 漏洞）、轻量级线程模型（高并发低开销）以及强类型系统，打造一个可嵌入微服务架构、支持大规模并发连接、具备生产级可靠性的 SMB 协议客户端，填补仓颉生态在企业级网络协议栈中的空白。

核心功能需求与技术规格

2.1 功能模块分解

表格

2.2 非功能性需求规范

• 性能指标：单连接文件读取 P99 延迟 < 50ms（局域网环境）；并发连接数 ≥ 10,000 时 CPU 占用率低于 70%；吞吐量较 Java 实现提升 ≥ 30%。

• 安全要求：依托仓颉编译期内存安全检查，彻底消除因缓冲区溢出、Use-After-Free 导致的安全漏洞；敏感信息（如密码）使用 SecureString 或零拷贝内存管理。

• 可靠性：所有网络 I/O 操作必须包裹在 try-catch 或 Result 中；连接异常自动清理资源；支持断线重连与会话恢复。

• 可维护性：模块解耦清晰，协议层、传输层、应用层分离；接口符合仓颉惯用法；代码通过 cjpm lint 无警告。

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

cangjie

编辑

interface SmbClient {
    fn connect(server: String) throws ConnectionError -> Connection;
    fn authenticate(authCtx: AuthenticationContext) throws AuthError -> Session;
}

interface DiskShare {
    fn list(path: String, pattern: String) throws SmbError -> List<FileEntry>;
    fn read(file: String) throws SmbError -> Bytes;
    fn write(file: String, data: Bytes) throws SmbError -> Unit;
    fn delete(file: String) throws SmbError -> Unit;
}

enum SmbError {
    AccessDenied,
    SharingViolation,
    Timeout,
    ProtocolVersionNotSupported,
}

fn processFileOperation(client: SmbClient, server: String) -> Result<Unit, SmbError> {
    let conn = client.connect(server)?;
    let session = conn.authenticate(AuthenticationContext { user: "admin", ... })?;
    let share = session.openShare("DATA")?;
    share.write("report.txt", "Hello SMB!".toBytes())?;
    Ok(())
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：SMB2 核心协议解析器 + 基础连接与认证 + 单元测试（覆盖率≥95%）+ 接口文档

• 第二阶段：完整文件操作 API + 并发连接池 + 与 Samba/Windows Server 集成测试 + 压测报告

• 第三阶段：SMB3 支持（含加密）+ 性能调优报告 + 生产部署指南 + 发布至 cjpm 仓库

3.2 项目实施路线图

表格

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

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt 格式化，禁止手动调整缩进。

• 类型安全：禁止使用 any 或强制类型转换；所有错误路径显式建模。

• 所有权设计：Connection、Session、DiskShare 等资源必须实现 Drop trait，确保 RAII。

• 错误处理：所有 public 函数必须声明 throws 或返回 Result，禁止静默失败。

4.2 测试与验证标准

• 单元测试：核心协议解析、状态机、认证流程覆盖率 ≥ 95%（cjpm test --coverage 验证）。

• 集成测试：使用 TestContainers 启动真实 Samba 容器进行端到端验证。

• 安全扫描：通过 cjpm analyze --security 及第三方静态分析工具（如 CodeQL 适配版）扫描。

4.3 文档与可维护性

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

• ADR：记录为何选择 SMB2 优先于 SMB1、为何不依赖 OpenSSL 等关键决策。

• 贡献指南：提供 CONTRIBUTING.md，说明如何本地构建、运行测试、提交 PR。

4.4 持续集成质量门禁

bash

编辑

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

• 测试框架：仓颉原生 test 模块 + TestContainers 适配层

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

• CI 环境：基于 cangjie-lang/cangjie:1.0.0 官方 Docker 镜像的 GitHub Actions / GitLab CI 流水线

交付件

验收标准

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

过程质量要求