在 React 项目里，价格、折扣、税费、分成比例等金额计算如果继续依赖原生 Number，很容易在页面展示时冒出 0.1 + 0.2 = 0.30000000000000004 这类结果。即便只是在控制台出现，也会让用户对系统可信度产生怀疑；一旦涉及订单提交或财务报表生成，误差会被进一步放大。迁移到 Saddle + Math 高精度数学库，本质上是把计算层从二进制浮点切换到十进制任意精度模型，同时保留前端组件原有的交互逻辑。

为什么原生 Number 在金额计算中不可靠

JavaScript 的 Number 类型遵循 IEEE 754 双精度浮点规范，它用有限位数表示实数。十进制中的 0.1 和 0.2 转换成二进制后都是无限循环小数，存储时只能截断，于是相加结果并不是精确的 0.3。日常开发里很多开发者习惯用 toFixed(2) 处理展示，但 toFixed 本身也有舍入误差，而且计算过程中已经丢失的精度无法通过格式化找回。金额、汇率、利率这类数据对精度敏感，依靠原生 Number 只能缓解症状，不能根除问题。

React 组件的状态更新会让这个问题更隐蔽。例如一个购物车组件先对单价做乘法，再把结果累加，最后通过 setState 写入总价。每个步骤都可能在二进制转换中丢失极小数值，最终渲染出的数字可能比后端计算的金额少一分或多一分。如果前后端对账不一致，排查成本远高于一开始就使用高精度库。

Saddle + Math 的核心思路是用十进制高精度对象替代原生数字参与运算。Saddle 负责数据容器和运算调度，Math 模块提供加、减、乘、除、幂、开方等常用函数。它的 API 设计尽量贴近原生 Math，因此 React 项目可以保留大部分业务代码结构，只把计算入口收口到统一服务层即可。

从直接计算到统一计算层

迁移的第一步不是全局替换所有 +、-、*、/ 运算符，那样会引入大量不可控的改动。更稳妥的做法是先创建一个 mathService 模块，把 Saddle + Math 的初始化、精度配置、舍入规则集中管理。组件不再直接调用 Number 或 Math，而是通过服务层函数完成计算。这样即使后续调整精度或替换底层实现，业务组件也不需要改动。

下面是一个基础的服务层封装。创建实例时指定 40 位精度，并使用四舍五入模式。所有入参先转成高精度数字，函数返回高精度对象，调用方根据需要再格式化。

// mathService.js
import { create, all } from 'saddle-math'
const math = create(all, {
  precision: 40,
  rounding: 'ROUND_HALF_UP'
})
export function add(a, b) {
  return math.add(math.bignumber(a), math.bignumber(b))
}
export function subtract(a, b) {
  return math.subtract(math.bignumber(a), math.bignumber(b))
}
export function multiply(a, b) {
  return math.multiply(math.bignumber(a), math.bignumber(b))
}
export function divide(a, b) {
  return math.divide(math.bignumber(a), math.bignumber(b))
}
export function formatMoney(value) {
  return math.format(value, {
    notation: 'fixed',
    precision: 2
  })
}

组件层使用这些函数时，不再出现裸的数字运算。比如订单摘要组件需要根据单价和数量计算总金额，可以写成下面这样。高精度对象不会直接出现在 JSX 中，而是通过格式化函数转成字符串展示。

import { add, formatMoney } from './mathService'
function OrderSummary({ unitPrice, quantity }) {
  const lineTotal = multiply(unitPrice, quantity)
  const tax = multiply(lineTotal, '0.13')
  const total = add(lineTotal, tax)
  return (
    <div>
      <p>商品金额：{formatMoney(lineTotal)}</p>
      <p>税额：{formatMoney(tax)}</p>
      <p>应付总额：{formatMoney(total)}</p>
    </div>
  )
}

这种写法把高精度计算与 React 渲染解耦，任何从表单、接口、路由参数进来的值都先经过服务层，避免在组件生命周期里反复做 parseFloat 或 Number 转换。迁移时可以按页面或业务模块逐步替换，不用一次性重写整个应用。

输入输出边界必须显式处理类型

高精度库通常不会返回原生数字，而是返回一个 BigNumber 或 Decimal 对象。这类对象不能直接放进 JSON.stringify，也不能作为 React 子节点渲染。开发中最常见的错误是把高精度结果直接塞给 <input> 的 value 或拼进接口请求体，结果得到一串内部表示或抛出序列化异常。正确方式是在边界处统一转成字符串，让字符串成为组件与计算层之间唯一的传输格式。

表单输入方面，建议把金额字段的 state 定义为字符串，而不是 Number。用户在 <input> 中输入时，用正则校验只允许数字和小数点，这样从源头上避免非法数字进入计算层。下面的示例展示了价格输入框的状态管理方式。

const [price, setPrice] = React.useState('19.90')
const handlePriceChange = (event) => {
  const raw = event.target.value
  if (/^\d*\.?\d*$/.test(raw)) {
    setPrice(raw)
  }
}
const total = add(price, '0.1')

与后端通信时同样建议采用字符串传输。金额字段在接口文档中可以约定为字符串，后端数据库使用 decimal 或 numeric 类型存储。这样前端高精度结果传到后端不会经过 JSON 数字精度丢失，后端返回的金额字符串也能直接进入 Saddle + Math 参与下一次计算。如果后端仍然返回数字，前端在进入计算层之前先转成字符串，再调用 bignumber，可以避免隐式二进制转换。

测试策略与性能调节

迁移到高精度库后，原有的金额断言可能需要更新。比如之前可能用 expect(total).toBe(0.3)，现在应改为判断格式化后的字符串，或者比较两个高精度对象的 equals 方法。单元测试要覆盖边界舍入、除不尽、负数、零值、超大金额等场景，确保舍入规则与业务要求一致。下面是一个基础测试示例。

import { add } from './mathService'
test('0.1 + 0.2 should equal 0.3', () => {
  const result = add('0.1', '0.2')
  expect(result.toString()).toBe('0.3')
})

高精度运算的性能比原生 Number 慢，频繁在渲染路径中创建高精度对象会造成不必要的开销。对于金额计算，通常数据量不大，性能影响可忽略；但如果要在表格中处理数千行合计，建议将计算移到 useMemo 或数据加载阶段，避免每次 render 都重新计算。也可以通过缓存格式化结果、批量处理数据等方式减少实例创建次数。

总体来看，React 应用迁移到 Saddle + Math 高精度数学库，核心在于建立统一计算层、显式处理字符串边界、用测试锁定精度规则。这样既能解决金额计算中的浮点误差，又不会让组件结构变得难以维护。对金融、电商、薪资、库存等业务场景，这次迁移带来的对账一致性和用户信任提升，远比迁移本身的工作量更有价值。