utilCode（通用工具）招募

一、 项目概述

为系统性地构建鸿蒙生态下仓颉语言的开发者基础设施，我们正式启动一项公益性开源项目，旨在创建一款在架构设计、代码质量、测试覆盖率和文档完备性上均达到生产级标准的通用工具库。本项目旨在为仓颉语言开发者提供一套可靠、高效的基础工具集，降低日常开发复杂度。

本项目完全以社区驱动的方式运作，聚焦于技术贡献与代码质量，不涉及任何商业报酬。我们诚邀追求卓越、熟悉仓颉语言的开发者加入，共同打造一个未来可被广泛信赖和使用的开源资产。

二、 项目目标与详细范围

本项目的核心交付物是一个模块化、可扩展的仓颉语言工具库。其初步范围规划如下，贡献者可选择其中一个或多个模块进行实现：

表1：工具库核心模块清单

三、 质量认证与专业技术要求

本项目对代码质量设有极高要求，所有贡献代码需通过以下多维度的质量认证。

1. 代码规范与架构设计

• 编码规范：​ 代码必须严格遵守仓颉语言官方代码风格指南。

  • 命名规范：​ 类名采用大驼峰，方法/变量采用小驼峰，常量采用全大写+下划线。

  • 代码格式：​ 缩进、空格、换行需统一。

• 架构设计原则：

  • 单一职责原则：​ 每个类/函数应只负责一个明确的功能点。

  • 依赖注入：​ 鼓励使用接口抽象和依赖注入来降低模块耦合度，以提高代码的可测试性。

代码示例：良好的接口设计与实现分离java

// 1. 定义加密工具接口，便于后续测试和扩展
public interface HashUtils {
    // 使用文档注释清晰说明功能、参数和返回值
    /**
     * 计算字符串的 SHA-256 哈希值，并以十六进制字符串形式返回。
     *
     * @param input 待计算的原始字符串
     * @return 长度为64的十六进制哈希字符串，输入为空时返回空字符串。
     */
    hashSha256(input: string): string;
}

// 2. 提供该接口的标准实现
public class StandardHashUtils implements HashUtils {
    public hashSha256(input: string): string {
        // 具体的算法实现...
    }
}

// 3. 通过依赖注入使用，而非硬编码实例化
public class MyService {
    private hashUtils: HashUtils;

    // 通过构造器注入依赖
    public init(hashUtils: HashUtils): void {
        this.hashUtils = hashUtils;
    }

    public processData(data: string): void {
        let hash = this.hashUtils.hashSha256(data);
        // ... 其他逻辑
    }
}

2. 测试覆盖率与健壮性

• 单元测试：​ 每个公开API必须有对应的单元测试。我们要求合并入主分支的代码需满足以下硬性指标：

  表2：单元测试覆盖率要求

  测试覆盖率类型	最低要求	目标要求
  行覆盖率	90%	95%+
  分支覆盖率	85%	90%+

• 测试用例设计：​ 测试应覆盖正常流程、边界条件（如空值、极值）和异常场景。

代码示例：对应的单元测试

// 对 HashUtils.hashSha256 方法的单元测试
// 使用 @Test 注解等仓颉语言测试框架特性
@Test
public testHashSha256(): void {
    // 1. 准备 (Arrange)
    let hashUtils: HashUtils = new StandardHashUtils();
    let testInput = "Hello, Cangjie!";
    let expectedHash = "8f7d..."; // 此处应为预先计算好的正确哈希值

    // 2. 执行 (Act)
    let actualHash = hashUtils.hashSha256(testInput);

    // 3. 断言 (Assert)
    Assert.equals(expectedHash, actualHash);
}

@Test
public testHashSha256WithEmptyInput(): void {
    // 测试边界条件：空字符串
    let hashUtils: HashUtils = new StandardHashUtils();
    let result = hashUtils.hashSha256("");
    Assert.equals("", result); // 根据验收要求，空输入返回空字符串
}

3. 工程化与文档完备性

• 构建与依赖：​ 项目必须提供清晰的构建脚本（如 build.sh），能够一键完成编译、测试、打包。依赖管理应简洁明确。

• API 文档：​ 所有公开的类、方法、参数必须使用仓颉语言的文档注释标准。项目需能自动化生成API文档站点。

• README.md：​ 必须提供详尽的说明文档，至少包含：

  • 项目简介和特性列表

  • 快速入门指南

  • 详细的API使用示例

  • 贡献指南（指向本招募公告）

四、 贡献流程与评审标准

1. 意向沟通：​ 贡献者请在本帖或项目仓库的Issue中声明意向，并说明计划贡献的模块。

2. Fork & PR：​ 遵循标准的GitHub/GitCode工作流：Fork仓库 -> 创建功能分支 -> 开发 -> 提交Pull Request。

3. 自动化流水线：​ 每个PR将自动触发CI/CD流水线，执行编译、静态代码分析和单元测试覆盖率检查。未能通过自动化检查的PR将不会被人工评审。

4. 人工评审：​ 项目维护者将进行深度代码评审，评审维度如下：

   评审维度	权重	关注点
   架构与设计​	30%	代码结构、模块划分、扩展性、是否符合设计原则。
   代码质量与规范​	25%	可读性、命名、注释、是否遵循编码规范。
   测试覆盖率与质量​	25%	测试用例的完备性、设计的合理性。
   文档完整性​	20%	API文档、README、代码内注释是否清晰准确。

5. 合并与认证：​ 通过全部评审的代码将被合并。优秀的贡献者将被邀请成为项目的长期维护者。

交付件

验收标准

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

过程质量要求