Python decimal.Context 如何固定金额计算边界：局部精度、舍入模式与线程上下文

订单服务里，金额错一分往往不是加法写错，而是精度和舍入规则藏在了调用方的全局上下文里。Python 的 decimal.Context 可以把 precision、rounding 和异常陷阱收拢到一次明确的计算边界中：先复制一份上下文，再在局部完成金额运算，最后用固定的小数位验收结果。

先把“精度”和“金额小数位”分开

Context.prec 控制的是有效数字总数，不是小数点后保留几位。例如，订单税额需要保留两位，不能只把 precision 设成 2；这样会连整数部分也算进去。金额落库前通常要再调用 quantize(Decimal("0.01"))，把指数明确到分。

from decimal import Decimal, Context, ROUND_HALF_UP

money_ctx = Context(prec=28, rounding=ROUND_HALF_UP)
cent = Decimal("0.01")

def to_cent(value: str) -> Decimal:
    amount = money_ctx.create_decimal(value)
    return amount.quantize(cent, context=money_ctx)

print(to_cent("12.345"))  # 12.35

这里的两个动作职责不同：create_decimal() 在进入计算上下文时限制有效数字，quantize() 在输出边界上固定两位小数。把它们混成一个“保留两位”的开关，后续排查时很容易误判。

升级旧写法：用局部上下文包住一笔计算

旧代码常见的写法是直接修改 getcontext().rounding，算完后再手动改回去。中间一旦抛异常，恢复动作就可能漏掉。更稳妥的迁移方式是保留一个基础 Context，在函数内部通过 localcontext() 建立临时副本。

from decimal import Decimal, Context, ROUND_HALF_UP, localcontext

BASE = Context(prec=28, rounding=ROUND_HALF_UP)

def invoice_total(items: list[tuple[str, str]]) -> Decimal:
    with localcontext(BASE) as ctx:
        total = sum(ctx.create_decimal(price) * ctx.create_decimal(qty)
                    for price, qty in items)
        return total.quantize(Decimal("0.01"), context=ctx)

assert invoice_total([("19.995", "2"), ("3.20", "1")]) == Decimal("43.19")

验证点不只是最终数字。测试还应确认离开 with 后，调用方的 rounding 没有变化；否则这段迁移只是把隐式全局状态换了一个位置。

让意外舍入在测试环境中尽早暴露

金额计算如果不允许悄悄丢弃有效数字，可以在验收用 Context 中开启 Inexact 与 Rounded 陷阱。生产代码是否长期打开，要看业务协议；但测试阶段打开很有价值，因为输入从字符串进入 Context 时就会暴露精度不足。

from decimal import Decimal, Context, Inexact, Rounded, ROUND_HALF_UP

strict = Context(prec=6, rounding=ROUND_HALF_UP)
strict.traps[Inexact] = True
strict.traps[Rounded] = True

try:
    strict.create_decimal("1234.5678")
except Inexact:
    print("input precision rejected")

如果业务允许中间结果多几位、只在发票金额处舍入，就不要把陷阱放在所有层级。可以给“输入解析”“税额计算”“落库金额”分别定义 Context，并为每个边界写一个预期结果。

线程和协程里的上下文边界

Python 文档说明当前 decimal Context 与执行环境关联；线程之间不会直接共享同一个当前 Context。但这不等于可以把一个可变 Context 到处修改。线程池任务最好接收一个只在任务内使用的 Context 副本，或者把金额函数设计成显式接收策略，避免测试依赖调用顺序。

def calculate_fee(base: Decimal, rate: Decimal, ctx: Context) -> Decimal:
    with localcontext(ctx) as active:
        fee = base * rate
        return fee.quantize(Decimal("0.01"), context=active)

这段接口的好处是边界清楚：调用者提供规则，函数只在局部使用；不同线程的任务可以使用不同 precision 和 rounding，而不会靠一个隐形的“当前设置”猜测结果。

迁移时最容易漏掉的四个检查

• 不要用二进制浮点数直接构造 Decimal；金额输入优先来自字符串。
• 不要把 prec=2 当作“保留两位小数”；输出位数由 quantize 的模板决定。
• 不要在库函数内部永久调用 setcontext()；局部策略应在 localcontext 中结束。
• 要覆盖 0、负数、刚好半分、超过 precision 和异常恢复后的下一次调用。

相关问答

Context 的 precision 是小数位数吗？

不是。它是有效数字总数；需要固定金额小数位时，应使用 quantize 和明确的指数模板。

为什么不直接修改 getcontext()？

直接修改会让调用顺序影响结果，异常路径也可能留下脏状态。局部上下文更容易恢复和测试。

ROUND_HALF_UP 适合所有财务场景吗？

不一定。它只是一个舍入策略，最终应以业务或会计规则为准，并把策略写进 Context 和测试样例。

把计算规则变成可回归的迁移清单

迁移完成的标志，不是代码里出现了 Context，而是每个金额边界都能回答三件事：输入允许多少有效数字，什么时候固定到分，发生意外舍入时是报错还是按规则处理。把这三项写进函数参数、Context 配置和断言，金额逻辑才不会被某个请求留下的全局状态牵着走。