dinero-best-practices

Dinero.js 最佳实践

使用 Dinero.js 时的核心规则。Dinero.js 是用于安全创建、计算和格式化金额的 JavaScript/TypeScript 库。本指南涵盖 4 个类别的规则，并按影响程度排序。

适用场景

在以下情况下，请参考这些指南：

• 根据用户输入、API 响应或数据库值创建 Dinero 对象
• 对金额执行算术运算（加法、拆分、乘法）
• 在 number 和 bigint 计算器之间进行选择
• 从 dinero.js、dinero.js/currencies 或 dinero.js/bigint 导入
• 处理价格、成本、税费或任何财务计算

按优先级划分的规则类别

优先级	类别	影响	前缀
1	对象创建	严重	creation-
2	算术运算	严重	arithmetic-
3	精度	高	precision-
4	导入	中	imports-

快速参考

1. 对象创建（严重）

• creation-minor-units - 始终以整数形式传入最小货币单位的金额
• creation-from-floats - 使用辅助函数将浮点输入转换为最小货币单位
• creation-zero-exponent - 指数为 0 的货币（例如 JPY）直接使用主要货币单位

2. 算术运算（严重）

• arithmetic-immutability - 所有操作都会返回新对象；请保存返回值
• arithmetic-allocate-not-divide - 拆分金额时使用 allocate，不要手动除法
• arithmetic-scaled-amounts - 切勿乘以未经处理的小数；应使用缩放后的金额
• arithmetic-percentages - 使用 allocate 或缩放后的 multiply 计算百分比

3. 精度（高）

• precision-bigint - 金额超过 Number.MAX_SAFE_INTEGER 时，使用 dinero.js/bigint
• precision-crypto - 加密货币因指数较高而需要使用 bigint
• precision-trim-scale - 链式操作后，使用 trimScale 去除末尾的零

4. 导入（中）

• imports-tree-shaking - 仅导入所需内容；独立函数支持摇树优化
• imports-bigint-currencies - 计算器类型须匹配：搭配 dinero.js/bigint 使用 dinero.js/bigint/currencies

使用方法

阅读各条规则文件，了解详细说明和代码示例：

rules/creation-minor-units.md
rules/arithmetic-allocate-not-divide.md

每个规则文件都包含：

• 简要说明规则的重要性
• 错误代码示例及其说明
• 正确代码示例及其说明
• 其他背景信息和参考资料