Python decimal.quantize 如何固定金额小数位：舍入模式与异常边界

订单结算里最容易被忽略的 bug，往往不是公式写错，而是金额在中间步骤多留了一位小数，最后才被页面格式化成两位。Python 的 decimal.Decimal 配合 quantize 可以把“保留几位”和“怎么舍入”明确写进代码，并且把超出精度、发生舍入这些状态交给程序处理。

固定金额小数位时，用字符串创建 Decimal，用 quantize(Decimal('0.01')) 固定结果尺度；如果业务规则是常见的“5 入”，显式传入 ROUND_HALF_UP，不要把默认舍入方式当成业务规则。

先把“显示两位”和“数值两位”分开

结算服务通常会同时处理商品单价、折扣和税额。页面上显示 19.90，并不代表内部值真的已经按两位小数完成舍入；如果后续又参与乘法，隐藏的第三位、第四位仍然会影响最终结果。

另一个常见入口是把 float 直接塞进 Decimal。下面的第一种写法会把二进制浮点的近似值带进十进制计算，排查账单差异时很难解释。金额文本、数据库 decimal 字段或接口字符串更适合走字符串构造。

from decimal import Decimal

bad = Decimal(2.675)
good = Decimal("2.675")
print(bad)
print(good)

用 quantize 把结果尺度固定下来

quantize 会让结果采用第二个 Decimal 的指数。把 Decimal('0.01') 作为模板，就是把结果固定到百分之一；它不是给字符串补零的展示函数，而是一次真正的十进制舍入操作。配图中的 Decimal result 表示舍入后的数值，two decimal places 表示它的指数尺度。

from decimal import Decimal

CENT = Decimal("0.01")

for raw in ("19.90", "19.905", "19.904"):
    amount = Decimal(raw)
    print(raw, "->", amount.quantize(CENT))

如果没有显式指定舍入方式，当前上下文的 rounding 会生效，默认上下文通常是 ROUND_HALF_EVEN。这在统计或科学计算里有价值，但“金额达到 5 就进位”是另一条业务规则，不能只因为输出看起来正常就省略配置。

在入账边界显式选择 ROUND_HALF_UP

下面这个函数把舍入策略收口在一个入口，调用方不用在每次计算时猜当前上下文。Decimal 仍然从字符串创建，最终返回值保留两位小数。

from decimal import Decimal, ROUND_HALF_UP

CENT = Decimal("0.01")

def money(raw: str) -> Decimal:
    value = Decimal(raw)
    return value.quantize(CENT, rounding=ROUND_HALF_UP)

print(money("19.905"))  # 19.91
print(money("19.904"))  # 19.90

这里不要把 round() 当成完全等价的替代品。Decimal 的 round(number, ndigits) 在不同参数形式下会受到上下文规则影响，而结算入口更需要一眼能看出的舍入约定。

把舍入发生与精度不足分别验收

“结果出来了”不等于“输入没有被悄悄改变”。如果订单金额必须最多两位小数，可以在校验入口打开 Inexact trap，让多余小数直接变成可捕获的异常；如果计算结果的系数长度超过上下文 precision，quantize 可能触发 InvalidOperation。

from decimal import Decimal, Inexact, InvalidOperation, localcontext

CENT = Decimal("0.01")

def require_two_places(raw: str) -> Decimal:
    with localcontext() as ctx:
        ctx.traps[Inexact] = True
        return Decimal(raw).quantize(CENT)

try:
    require_two_places("19.90")
    require_two_places("19.905")
except Inexact:
    print("金额超过两位小数，需要业务确认")

try:
    with localcontext() as ctx:
        ctx.prec = 4
        Decimal("12345.67").quantize(CENT)
except InvalidOperation:
    print("当前 precision 无法容纳结果")

Inexact 更适合表达“这次操作发生了舍入”，而 InvalidOperation 表达的是当前操作无法按上下文完成。两者不要统一吞掉后返回一个默认金额，否则账单错误会被推迟到对账环节才暴露。

上线前用同一组边界样例复查

发布前至少保留正数、负数、恰好两位、第三位为 4、第三位为 5，以及超出 precision 的样例。尤其是 2.675 这类值，字符串构造和 float 构造不能混用，否则测试通过的可能只是某个平台上的近似结果。

如果接口接收的是 JSON 数字，建议在进入金额函数前先转成字符串或直接使用原始文本字段，并对空串、科学计数法、非法字符单独给出输入错误。金额舍入完成后，再把 Decimal 交给数据库驱动或序列化层，显示格式放在最后一步。

常见问题

quantize 只是把金额显示成两位吗？

不是。它会按目标 Decimal 的指数返回舍入后的 Decimal；显示层再把这个值格式化成字符串，两者职责不同。

为什么要写 Decimal("2.675")，不能直接写 Decimal(2.675)？

float 先经过二进制浮点表示，Decimal 接收到的可能已经不是十进制文本中的精确值。金额入口应优先使用字符串或数据库读取出的十进制文本。

ROUND_HALF_UP 和默认 ROUND_HALF_EVEN 选哪个？

取决于业务规则。前者在常见的半数进位规则下更直观，后者是 decimal 上下文的常见默认值，统计计算可能更合适。不要让默认值代替需求确认。

Inexact 一定代表计算失败吗？

不一定。它说明发生了舍入；如果业务允许舍入，可以读取 flag 或正常返回，如果业务要求输入最多两位小数，则可以像示例一样启用 trap 把它变成校验错误。

把金额规则收口成可复查的边界

稳定的金额处理链通常很短：字符串进入 Decimal，在明确的业务边界调用 quantize(Decimal('0.01'))，显式指定舍入方式，再按需要检查 Inexact 和 InvalidOperation。这样页面显示、数据库保存和对账验证使用的是同一个已舍入值，出了差异也能沿着输入、舍入、异常分支逐步定位。