fraction-js

项目背景与战略目标

在金融交易结算、税务计算、科学工程模拟及数据统计分析等后端核心业务中，数值的精确性至关重要。传统的浮点数（Float/Double）运算遵循 IEEE 754 标准，不可避免地存在精度丢失问题（如 0.1 + 0.2 !== 0.3），这可能导致资金对账不平、科学计算误差累积等严重后果。现有的高精度库多基于大整数（BigInt）或字符串模拟，在动态语言中性能受限且内存开销大。

本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+重构 fraction.js，打造一款零精度损失、高性能、内存安全的后端数学基础库。

• 绝对精度保证：基于仓颉原生 Int64 或自定义大整数结构存储分子分母，彻底消除浮点误差，确保任意次运算后结果依然精确。

• 极致运算性能：利用仓颉的静态编译优化和内联汇编潜力，加速最大公约数（GCD）计算与分数约分过程，性能超越解释型语言实现 10 倍以上。

• 内存安全与可控：依托仓颉所有权机制，精确控制大数运算过程中的临时对象分配与释放，避免高频计算场景下的 GC 压力。

• 丰富的数学语义：提供符合数学直觉的链式调用 API，支持分数与小数、百分数的无损转换，内置完善的异常处理机制。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单次加减乘除运算平均延迟 < 50ns，百万次连续运算吞吐量 > 20M OPS，GCD 计算效率达到理论最优。

• 安全要求：严格检查分母为零的情况，抛出明确的 DivideByZeroError；防止大数运算导致的整数溢出，支持自动升级到大整数模式。

• 可靠性：所有运算满足数学结合律、交换律（在定义域内），单元测试覆盖所有边界条件（如负数、极大值、极小值）。

• 可维护性：代码结构清晰，算法实现附带数学原理注释，易于扩展新的数学函数。

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

// 定义分数结构
struct Fraction {
    numerator: Int128
    denominator: Int128
    
    // 构造函数，自动约分并处理符号
    init(numerator: Int128, denominator: Int128): Result<Fraction, MathError>
    
    // 从浮点数创建（有限精度近似）
    static func fromFloat(value: Double, precision: Int32): Result<Fraction, MathError>
    
    // 从字符串创建（支持 "1/3", "0.333...", "50%"）
    static func fromString(input: String): Result<Fraction, ParseError>
}

// 核心运算接口
interface FractionOps {
    // 四则运算
    func add(other: Fraction): Fraction
    func sub(other: Fraction): Fraction
    func mul(other: Fraction): Fraction
    func div(other: Fraction): Result<Fraction, MathError>
    
    // 高级运算
    func pow(exponent: Int64): Fraction
    func inverse(): Result<Fraction, MathError>
    func abs(): Fraction
    func negate(): Fraction
    
    // 比较
    func equals(other: Fraction): Bool
    func compareTo(other: Fraction): Int // -1, 0, 1
    
    // 转换
    func toDouble(): Double
    func toDecimal(scale: Int32): Decimal
    func toString(): String
    func toMixedString(): String // 例如 "1 1/3"
}

// 错误类型定义
enum MathError {
    case DivideByZero
    case IntegerOverflow
    case InvalidOperation(String)
}

enum ParseError {
    case InvalidFormat(String)
    case UnsupportedNotation(String)
}

// 工具类
object FractionUtils {
    // 计算最大公约数 (GCD)
    func gcd(a: Int128, b: Int128): Int128
    
    // 计算最小公倍数 (LCM)
    func lcm(a: Int128, b: Int128): Int128
    
    // 批量求和
    func sum(fractions: List<Fraction>): Fraction
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：核心 Fraction 结构 + 四则运算 + 基础转换 + 单元测试 (覆盖率≥98%)。

• 第二阶段：高级数学函数 + 字符串解析增强 + 性能基准测试 + 溢出保护机制。

• 第三阶段：批量运算优化 + 模糊测试 + 数学正确性证明文档 + cjpm 发布包。

项目实施路线图

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

仓颉语言专项质量规范

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

• 类型安全：充分利用强类型系统防止非法状态（如分母为0），利用Option/Result类型显式处理运算失败。

• 错误处理：所有数学异常必须捕获并转换为业务友好的错误码，严禁静默失败或返回 NaN。

测试与验证标准

• 单元测试：核心模块行覆盖率≥98%，重点覆盖负数运算、极大值溢出边界、除零错误及特殊分数（如 0/n, n/1）。

• 数学正确性验证：编写属性测试（Property-based Testing），随机生成大量分数运算序列，验证其是否满足数学定律（如 (a/b) * (b/a) == 1）。

• 性能基准：建立与 JavaScript/Python 版本及 BigDecimal 库的性能对比基准，确保在精度相当的前提下性能最优。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明各方法的数学定义及复杂度。

• 数学原理说明：提供《分数运算算法实现细节》，解释 GCD 选型、溢出处理策略等。

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

持续集成质量门禁

#!/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. 数学属性测试 (Property Testing)
cjpm test --suite property-math-validation

# 6. 性能基准测试 (对比基线)
cjpm bench --threshold 2%

技术栈与开发环境

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

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

• 测试框架：仓颉原生测试框架（支持属性测试插件）。

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

• 环境要求：仓颉 1.0.0+ 标准工具链，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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求