seedrandom

项目背景与战略目标

在后端分布式系统、大规模仿真模拟、游戏服务器逻辑同步及自动化测试场景中，随机数的“可预测性”与“可复现性”是核心需求。传统的系统随机数生成器（RNG）通常依赖全局状态或系统时间，导致在分布式节点间无法生成一致的随机序列，难以进行故障重现、确定性测试或状态同步。seedrandom 库的核心价值在于允许开发者通过指定“种子（Seed）”初始化随机数生成器，从而获得完全确定的随机序列。

本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+重构 seedrandom，打造一款线程安全、高性能、多算法支持的后端基础算法库。

• 确定性复现能力：确保相同种子在任何架构、任何时间点生成的随机序列完全一致，为分布式仿真和调试提供基石。

• 高并发线程安全：利用仓颉的所有权机制和不可变数据设计，实现无锁化的随机数生成器实例，完美适配高并发服务端场景。

• 多算法插件化：内置多种高质量伪随机算法（如 Alea, XORShift128, Tyche-I），并支持通过仓颉接口轻松扩展新算法，满足不同安全等级和性能需求。

• 熵源混合增强：支持将用户种子与系统熵源（如硬件随机数）混合，在保证可复现性的同时提升初始种子的不可预测性，适用于安全敏感场景。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：基础随机数生成延迟 < 5ns，千万级连续生成吞吐量 > 500M OPS，状态序列化延迟 < 1μs。

• 安全要求：默认算法需通过统计随机性测试（如 TestU01）；支持可选的密码学安全模式（CSPRNG）用于令牌生成。

• 可靠性：严格验证种子输入合法性，防止除零或状态溢出；确保长期运行无状态漂移。

• 可维护性：算法实现与业务逻辑解耦，新增算法无需修改核心调用代码。

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

// 定义随机数生成器接口
interface RandomGenerator {
    // 生成 [0, 1) 之间的双精度浮点数
    func nextDouble(): Double
    
    // 生成 [0, 2^32) 之间的整数
    func nextInt(): Int32
    
    // 生成指定范围内的整数 [min, max)
    func nextIntRange(min: Int32, max: Int32): Result<Int32, RangeError>
    
    // 生成指定分布的随机数 (如正态分布)
    func nextGaussian(mean: Double, stdDev: Double): Double
    
    // 保存当前状态
    func saveState(): ByteArray
    
    // 恢复状态
    func restoreState(state: ByteArray): Result<Unit, StateError>
}

// 定义生成器工厂
object SeededRandom {
    // 使用字符串种子创建生成器 (默认算法)
    static func create(seed: String): RandomGenerator
    
    // 使用整数种子创建生成器
    static func create(seed: Int64): RandomGenerator
    
    // 指定算法创建生成器
    static func createWithAlgorithm(seed: String, algo: AlgoType): RandomGenerator
    
    // 创建线程安全的生成器池
    static func createPool(seed: String, size: Int32): RandomGeneratorPool
}

// 定义算法枚举
enum AlgoType {
    case Alea       // 快速，统计特性好
    case XorShift128 // 极速，适合仿真
    case TycheI     // 加密强度较高
    case Arc4       // 兼容旧版
}

// 错误类型定义
enum RangeError {
    case InvalidRange(String)
}

enum StateError {
    case CorruptedState(String)
    case VersionMismatch
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：核心 PRNG 算法实现（Alea, XorShift）+ 种子初始化 + 基础单元测试 (覆盖率≥95%)。

• 第二阶段：分布转换模块 + 状态序列化/反序列化 + 并发池实现 + 性能基准测试。

• 第三阶段：统计随机性测试报告（TestU01）+ 高级算法扩展 + cjpm 发布包 + 最佳实践文档。

项目实施路线图

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

仓颉语言专项质量规范

• 编码规范：100% 符合仓颉语言官方编码规范，通过 cjfmt 自动格式化校验。

• 类型安全：充分利用泛型定义算法接口，利用代数数据类型（ADT）管理错误状态。

• 错误处理：所有非法输入和状态异常必须显式返回 Result 类型，严禁隐式崩溃。

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖边界种子、空种子、极长种子及状态恢复场景。

• 统计验证：必须通过 TestU01 或 Dieharder 随机性测试套件，确保生成的随机序列无显著统计偏差。

• 一致性测试：在不同架构（x86_64, ARM64）上验证相同种子生成的序列完全一致。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明各算法的统计特性和适用场景。

• 算法决策记录：记录各 PRNG 算法的选型依据及性能对比数据。

• 贡献指南：明确仓颉项目构建、调试、提交全流程规范。

持续集成质量门禁

#!/bin/bash
# PR 自动化流水线脚本

# 1. 格式检查
cjpm fmt --check

# 2. 构建检查
cjpm build
cjpm build --release

# 3. 静态 lint 检查
cjpm lint --deny-warnings

# 4. 全量测试与覆盖率
cjpm test --all-features --coverage

# 5. 统计随机性测试 (耗时较长，可选)
# cjpm test --suite statistical-randomness

# 6. 性能基准测试 (对比不同算法)
cjpm bench --threshold 5%

技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0 及以上版本（强制）。

• 构建与包管理：CJPM (Cangjie Package Manager)。

• 测试框架：仓颉原生测试框架。

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

• 环境要求：仓颉 1.0.0+ 标准工具链，CI 环境需预置随机性测试工具链（如 TestU01 bindings）。

交付件

验收标准

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

过程质量要求