dinero.js 中 halfAwayFromZero：远离零的四舍五入模式全解析

• 金融科技

导读

本文聚焦 dinero.js 中提供的一种关键舍入模式 ——halfAwayFromZero，用于在除法运算（精确除法余数不可忽略时）如何决定金额的舍入方向。它被设计为「就近舍入」规则：当商恰好处于两个整数正中间时，一律向远离零的方向取整，即正数向上（如 1.5 → 2）、负数向下（如 -1.5 → -2），因此也被称为「商业舍入」或「算术舍入」。读完本文，你将掌握该模式的语义定义、它如何作为第三个参数接入multiply、allocate和transformScale等核心 API，以及它在源码中的实现原理与测试验证。

一、什么是 halfAwayFromZero

在金钱计算中，除法往往会产生无法整除的余数，例如把 305 美分乘以 2.1，或者把 1055 个最小单位缩放到更小的精度（scale）。此时我们必须决定舍弃多少、进位多少。dinero.js 将这种决策抽象为一系列「除法舍入操作（divide operation）」，halfAwayFromZero是其中之一。

官方文档 half-away-from-zero.md 给出的定义是：

Divide and round towards the nearest neighbor, rounding away from zero when exactly halfway.

即：优先向最近邻取整；当数值恰好处于两个整数正中间（halfway）时，向远离零的方向取整。具体表现为：

• 正数的中间值向上取整：1.5 → 2，2.5 → 3
• 负数的中间值向下取整：-1.5 → -2，-2.5 → -3

这种规则在业界被称为commercial rounding（商业舍入）或arithmetic rounding（算术舍入），常见于发票、零售价、税费等日常商业计算场景——它保证正负金额的舍入幅度在绝对意义上一致，且所有「中间值」都被进位，避免系统性少收。

二、使用方式：作为最后一个参数传入

halfAwayFromZero不是独立执行的 API，而是以「舍入操作」的身份作为最后一个参数传给以下三个函数：

• multiply（乘法）
• allocate（按比例分配）
• transformScale（变更精度 scale）

其函数签名遵循DineroDivideOperation类型，即(amount, factor, calculator) => roundedAmount，实际由 dinero.js 内部在需要做除法舍入时调用，开发者只需传入函数引用，无需关心底层参数。

2.1 与 multiply 配合

当乘法结果需要降精度（scale）时，会产生余数，此时传入halfAwayFromZero控制舍入：

import { dinero, multiply, halfAwayFromZero } from 'dinero.js'; import { USD } from 'dinero.js/currencies'; const d = dinero({ amount: 305, currency: USD }); multiply(d, { amount: 21, scale: 1 }, halfAwayFromZero); // 返回一个 Dinero 对象，amount 为 6405，scale 为 3

本例中：305 × 2.1 = 640.5，保留 scale 3（千分位精度）即 6405/1000；若按transformScale默认的down（截断）模式，0.5 的余数会被丢弃，而halfAwayFromZero会把 640.5 舍入为 641，反映为 amount 6405。

2.2 与 transformScale 配合

transformScale用于把金额从一个精度变换到另一个精度，缩小精度时必然涉及舍入：

import { dinero, transformScale, halfAwayFromZero } from 'dinero.js'; import { USD } from 'dinero.js/currencies'; const d = dinero({ amount: 1055, currency: USD, scale: 3 }); transformScale(d, 2, halfAwayFromZero); // 返回一个 Dinero 对象，amount 为 106，scale 为 2

这里 1055/1000 → 保留两位小数：1.055，在 scale 2 下商为 1.05 与 1.06 之间，恰处于中间值（0.005），halfAwayFromZero向远离零方向舍入为 1.06，即 amount 106。

2.3 与 allocate 配合

allocate按比例拆分金额，拆分会把剩余的最小单位分给某一份。它同样接受舍入操作作为最后一个参数：

import { dinero, allocate, halfAwayFromZero } from 'dinero.js'; import { USD } from 'dinero.js/currencies'; const d = dinero({ amount: 100, currency: USD }); allocate(d, [1, 1, 1], halfAwayFromZero); // 金额 100 按 1:1:1 拆分，中间值余数按远离零规则归入相应份额

源码层面，allocate内部先调用transformScale将金额统一到更高精度（见 allocate.ts），再通过distribute分配；因此舍入操作实际影响的是分配过程中产生的余数处理。

三、源码实现原理

3.1 核心实现

halfAwayFromZero的实现位于 halfAwayFromZero.ts：

export const halfAwayFromZero: DineroDivideOperation = ( amount, factor, calculator ) => { const signFn = sign(calculator); const isHalfFn = isHalf(calculator); const absoluteFn = absolute(calculator); if (!isHalfFn(amount, factor)) { return halfUp(amount, factor, calculator); } return calculator.multiply( signFn(amount), up(absoluteFn(amount), factor, calculator) ); };

算法逻辑非常清晰：

1. 用isHalf判断余数是否恰好为 factor 的一半（即商恰在中间值）；
2. 若不是中间值，直接委托halfUp——也就是说，非中间值情况下halfAwayFromZero与halfUp行为完全一致：大于一半向上，小于一半向下；
3. 若恰好是中间值，则取金额的符号sign(amount)，对绝对值执行up（无条件向上舍入），再乘回符号——从而保证正数进位、负数进（绝对值意义上的）位，即「远离零」。

3.2 关键辅助函数

• isHalf：判断余数是否等于 factor 的一半，见 isHalf.ts。实现为：计算|amount % factor|的余数，再比较factor - remainder与remainder是否相等。注意它基于绝对值判断，因此正负对称。
• sign：返回金额的符号（-1 / 0 / 1），见 sign.ts。
• up：无条件向上舍入，见 up.ts：当余数不为 0 且金额为正时对商increment，否则返回整数商。
• halfUp：就近舍入、中间值向上（向正无穷），见 halfUp.ts，它是halfAwayFromZero在非中间值场景下的直接委托对象。

从源码结构可以看出，所有舍入模式都建立在down、up这两个最基础操作之上，通过不同组合实现七种规则（down、up、halfUp、halfDown、halfAwayFromZero、halfTowardsZero、halfEven、halfOdd），这些模式统一从 divide/index.ts 导出，并由 包入口 对外暴露。

3.3 与 halfUp / halfEven 的差异

三种「就近舍入」模式的唯一分歧点在于中间值的处理：

halfAwayFromZero与halfUp对正数完全相同（都向上），对负数才出现差异（前者向更负，后者向零靠拢）；与halfEven则在 ±2.5 这类奇数中间值时产生不同结果。

四、测试验证

仓库为halfAwayFromZero编写了完备的单元测试，见 halfAwayFromZero.test.ts，覆盖两类输入：

十进制因子（factor=10）：

• 正/负整数商不取整：20/10 → 2，-20/10 → -2
• 零商不取整：0/10 → 0
• 正中间值远离零：15/10 → 2
• 负中间值远离零：-25/10 → -3
• 大于一半向上、小于一半向下（配合 fast-check 属性测试，如fc.integer({ min: 6, max: 9 })断言结果恒为 1）

非十进制因子（factor=5、2）：

• 5/2 = 2.5 → 3、-5/2 = -2.5 → -3（中间值远离零）
• 其余场景同样验证了「整数商不变、非中间值就近」的规则

测试还特意断言了负数小于一半时结果会得到-0，说明符号运算在边界值上也能保持一致性。这些测试直接印证了文档中的语义描述：只有精确落在中间值时，halfAwayFromZero才与默认的halfUp/down分道扬镳。

五、选择该模式的实践建议

1. 何时优先选用：当业务要求「任何正中间值都必须进位」且正负对称——如商品单价计算、含税金额、折扣分摊，halfAwayFromZero是符合直觉且公平的选择。
2. 何时避免：如果涉及「向偶数舍入」的统计偏好（如金融分摊中希望系统误差更小），可改用halfEven；如果只要求简单截断，使用默认的down即可，无需显式传入。
3. 注意默认值：transformScale的默认舍入模式是down（见 transformScale.ts 中divide = down），需要本模式时必须显式传入halfAwayFromZero。
4. 理解 scale 语义：舍入结果反映在amount与scale的组合上——如 1055（scale 3）→ 106（scale 2），实际金额 1.055 → 1.06，这是金额数值不变、仅精度变化的正确体现。

六、总结

halfAwayFromZero是 dinero.js 提供的八种舍入模式之一，其核心价值在于：就近舍入 + 中间值远离零。它通过复用isHalf、sign、up、halfUp等底层工具以极简代码实现，并被multiply、allocate、transformScale三个核心 API 统一消费。理解它的源码实现（halfAwayFromZero.ts）与测试（halfAwayFromZero.test.ts），有助于你在真实业务中准确选择舍入策略，避免金额偏差。

• 金融科技