Python 金额舍入实测:round、Decimal 与 float 的 8 个静默分歧
TL;DR:金额不要用 float 存,也不要用默认上下文的 Decimal 直接 quantize。八个分歧里最贵的三个是:round() 遇到正好一半时往偶数走而不是往大走;Decimal 默认 28 位精度会在小数点后静默吃位;除不尽的分摊与含税单价,舍入时机比舍入模式更决定账能不能对上。
先说结论:八处分歧,一句话一处
round()不是四舍五入:正好一半时它往偶数走,round(0.5)是 0,round(2.5)是 2。- 同一个 2.675 有三个答案:
f'{2.675:.2f}'得 2.67,Decimal(str(2.675))量化得 2.68,Decimal(2.675)量化又回到 2.67。 - Decimal 收 float,收的是一串二进制尾巴:
Decimal(0.1)有 55 位小数,与Decimal("0.1")不相等。 - 28 位精度会静默吃位:
Decimal("1e30") + 1的结果等于Decimal("1e30"),比较返回 True,没有任何提示。 quantize的舍入模式读线程上下文:round(Decimal("2.665"), 2)默认得 2.66,把上下文改成四舍五入立刻变 2.67。- Decimal 与 float 混用是一扇半开的门:加法直接抛 TypeError,比较却全部放行,排序甚至不报错。
- 除不尽的分摊必然差一分:100 除以 3,各舍到 33.33,三个加起来 99.99。
- JSON 与 sqlite3 都不收 Decimal:一个抛 TypeError,一个抛 ProgrammingError,而报错点离金额逻辑很远。
这份清单不是抄文档抄来的。下面每一条都有本机输出,读者可以复制粘贴复现。
我实际跑的环境
CPython 3.13.14,Windows 11,只用标准库 decimal、json、sqlite3,没有装任何第三方财务库。我实际跑了四组脚本,全部零依赖、零凭据、零网络。所有数字都是本机输出,不是从文档里摘的;凡是引用官方原文的地方,我会标明是原文而不是我的转述。
文中出现的 $19.99 一类价格只是算式的一部分,用于把误差量级摊开给你看。本文不含任何联盟推广链接,也不推荐任何具体软件。
分歧一:round() 不是四舍五入
先把最容易踩的钉子拔掉。round() 的官方 docstring 写得很清楚:
「The return value is an integer if ndigits is omitted or None. Otherwise the return value has the same type as the number.」
也就是说,round(x) 给你 int,round(x, 2) 给你 float 或 Decimal。这一条本身就够坑:两种调用返回不同类型,混进同一个列表里排序不会报错,但下游 isinstance(x, float) 的分支会走错。
真正的分歧在"正好一半"的时候。本机输出:
round(0.5) # 0
round(1.5) # 2
round(2.5) # 2
round(-1.5) # -2
round(-0.5, 0) # -0.0
注意最后一行:round(-0.5) 省略 ndigits 返回 int 的 0,而 round(-0.5, 0) 返回 float 的 -0.0。同一个数、同一个函数,多写一个参数就多出一个负零。负零在 JSON 里序列化成 -0.0,在报表里显示成「-0.00」,在按字符串比对的场景里跟 0.0 不相等。
这条规则有正式名字,decimal 模块给了官方定义:ROUND_HALF_EVEN 是「Round to nearest with ties going to nearest even integer.」翻译过来就是"就近取整,平局取最近的偶数"。这也解释了为什么 round(1.5) 是 2 而 round(2.5) 也是 2 —— 2 是偶数,2.5 那一次就往下走了。
业务上的后果不是"偶尔差一分",而是系统性偏向:如果每张发票的尾数都落在 .5,全站会朝偶数方向累积偏移,正负相抵之后并不归零。审计问起"为什么总额比明细少 3.5 元",你很难用"Python 就是这样"解释过去。
还有第二层原因,更隐蔽:即便你接受半偶规则,float 上的 round() 仍可能给出"按十进制看是错的"结果。这就是下一个分歧。
分歧二:同一个 2.675,三条路给出两个答案
我在同一台机器上跑了三条看上去都"正确"的写法:
f'{2.675:.2f}' # '2.67'
Decimal(str(2.675)).quantize(Decimal('0.01')) # Decimal('2.68')
Decimal(2.675).quantize(Decimal('0.01')) # Decimal('2.67')
第一行给 2.67,第二行给 2.68。两条都号称按两位小数处理同一个数,结果差一分。
原因在 float 里。format(2.675, '.20f') 的输出是 2.67499999999999982236 —— 这个 float 的真实值比 2.675 小,所以任何"就近取整"都会把它舍到 2.67,这里根本没有平局,半偶规则还没上场。而 str(2.675) 得到的是最短往返表示 '2.675',Decimal('2.675') 因此是精确的 2.675,这才真的触发平局:第三位是 7,7 是奇数,按半偶规则进到 8。
于是同一条业务规则在三个层级上给出三个不同的"正确":
- 在 float 层,
f'{x:.2f}'忠实反映了二进制真实值,判 2.67。 - 在"字符串截获"层,
Decimal(str(x))把 float 的最短表示当成真值,判 2.68。 - 在"精确转换"层,
Decimal(x)拿回 53 位精度的完整尾巴,又判回 2.67。
换一组数,分歧会换方向。1.115 用 f-string 得 1.11,用 Decimal(str(1.115)) 量化得 1.12;1.005 两种情况都是半偶赢,得 1.00,但换成 ROUND_HALF_UP 立刻变 1.01。
我的结论很朴素:别在 float 上讨论舍入规则。float 里根本不存在"2.675 这个数",存在的只是它的一个邻居。要在十进制语义上做决定,就必须让数据从源头就是十进制。
分歧三:Decimal 收 float,收的是一串二进制尾巴
这一条官方文档自己写明了。Decimal.from_float() 的 Note 原文:
「Note Decimal.from_float(0.1) is not the same as Decimal('0.1'). Since 0.1 is not exactly representable in binary floating point, the value is stored as the nearest representable value which is 0x1.999999999999ap-4. That equivalent value in decimal is 0.1000000000000000055511151231257827021181583404541015625.」
构造函数那一节也写了:float 会被「losslessly converted to its exact decimal equivalent」,而且「This conversion can often require 53 or more digits of precision.」
本机验证:
Decimal(0.1) # 0.1000000000000000055511151231257827021181583404541015625
Decimal('0.1') # 0.1
Decimal(0.1) == Decimal('0.1') # False
55 位小数,误差从第 18 位开始。这个误差本身很小,小到任何两位小数的舍入都看不见它 —— 那它为什么危险?
因为误差会在不该被看见的地方露头:分组求和后做相等判断、库存数量与单价相乘后与总账对拍、把金额塞进 set 或 dict 做去重、以及拿它当 SQL 参数去匹配一个 DECIMAL 列。Decimal(0.1) == Decimal("0.1") 返回 False,这一条会在"明明两边都是 0.1"的工单里耗掉一个下午。
对策只有一条:金额进系统时就转成字符串或整数分,别让 float 进来。CSV 读取用 csv 模块拿字符串而不是让表格库默认推断成 float;JSON 用 json.loads(..., parse_float=str);Excel 导入时把单元格读成文本再校验格式。
分歧四:28 位精度会在你看不见的地方吃位
decimal 的默认上下文,官方原文:
「The default values are Context.prec=28, Context.rounding=ROUND_HALF_EVEN, and enabled traps for Overflow, InvalidOperation, and DivisionByZero.」
28 位对普通金额当然够。问题在于"够"是有条件的,而条件不满足时它不报错:
Decimal('1e30') + Decimal('1') == Decimal('1e30') # True
加法把那个 1 吃掉了,结果仍然是一个合法的 Decimal,比较也"正确"地相等。这类缺陷在单元测试里几乎抓不到 —— 你写 assert total == expected,两边都被同一个精度规则吃掉了同一位,断言照样绿。
更狠的是把精度调小之后的连锁反应。我把上下文精度设成 6,做一个再普通不过的加法:
with localcontext() as ctx:
ctx.prec = 6
s = Decimal('123456.78') + Decimal('1.00') # 123458
s.quantize(Decimal('0.01')) # decimal.InvalidOperation
加法结果 123458,小数点后整段消失(as_tuple() 是 digits=(1,2,3,4,5,8), exponent=0),紧接着量化直接抛 InvalidOperation。前一步静默,后一步崩溃,两个症状相隔一行,而根因在两行之前。
官方在「Mitigating round-off error with increased precision」一节把这件事说得很克制:decimal 消除了十进制表示误差(0.1 能被精确表示),但「some operations can still incur round-off error when non-zero digits exceed the fixed precision」。
给你的可执行判据:精度下限 = 金额整数位 + 小数位 + 汇率或税率的最长小数位 + 1 位余量。含分金额(两位小数)乘四位小数税率,最大金额十亿级(10 位整数),需要 10 + 2 + 4 + 1 = 17 位,28 位够用;但如果你做的是复利、单位换算(比如毫克到吨、厘到元)或多段累乘,很容易越线,那时必须显式 localcontext(prec=...),不能靠默认值。
分歧五:quantize 的舍入模式跟着线程上下文走
同一个函数调用,代码字面完全一样,结果随上下文变:
round(Decimal('2.665'), 2) # 2.66
with localcontext() as ctx:
ctx.rounding = ROUND_HALF_UP
round(Decimal('2.665'), 2) # 2.67
round(Decimal('2.665'), 2) # 2.66
quantize() 不带 rounding= 参数时同理 —— 它读的是当前上下文,不是"四舍五入",也不是"跟上次一样"。
为什么 2.665 会是 2.66?因为半偶规则看的是被舍弃的那一位之后还有没有东西:2.665 精确等于一半,5 后面没有非零位,于是看前一位 6 —— 6 是偶数,不动。而 1.005 的前一位是 0,也是偶数,所以得 1.00 而不是 1.01。同一套规则,一个"看起来舍了",一个"看起来没舍",全靠前一位的奇偶。
上下文是线程隔离的,官方在「Working with threads」一节写明:「The getcontext() function accesses a different Context object for each thread. Having separate thread contexts means that threads may make changes (such as getcontext().prec=10) without interfering with other threads.」
这句话听起来是安全承诺,实际只是"别的线程不受影响"。同一个线程里的所有代码共享同一个上下文,包括第三方库、包括你三个月前写的那个把 prec 改成 10 的辅助函数。在 asyncio 里更微妙:多个协程跑在同一个线程上,一个协程改了上下文,下一个协程接手的就是被改过的精度。
所以:财务代码里不要出现裸 quantize(Decimal('0.01'))。要么显式写 quantize(Decimal('0.01'), rounding=ROUND_HALF_UP),要么整个函数用 localcontext() 包住并显式设 prec 与 rounding。显式比正确更重要 —— 因为你不知道调用方此刻的上下文是什么。
顺带纠正一个常见误解:ROUND_HALF_UP 的官方定义是「Round to nearest with ties going away from zero.」,是"远离零",不是中文"四舍五入"在负数上的直觉。Decimal('-2.5') 在 HALF_UP 下是 -3,在 HALF_DOWN 下是 -2。退款、冲正这类负金额场景要单独验一遍。
分歧六:Decimal 与 float 混用,一半报错一半静默
Decimal('0.1') + 0.1 # TypeError: unsupported operand type(s) for +: 'decimal.Decimal' and 'float'
Decimal('0.1') == 0.1 # False
Decimal('0.1') != 0.1 # True
sorted([0.3, Decimal('0.2'), 0.1]) # [0.1, Decimal('0.2'), 0.3]
加法毫不客气地抛异常,比较和排序却一路绿灯。而且这个比较不是"相等就完事":float 的 0.1 实际略大于十进制的 0.1,所以 Decimal('0.1') 与 float 的 0.1 比大小时,结论是 Decimal 那边更小 —— 放在"金额不能超过限额"的判断里,这会放过一个本该拒绝的值,或者拒绝一个本该放过的值,全看你在哪一侧。
sorted() 混排不报错这一点更值得警惕:一个 [float, Decimal, float] 的列表能安静地排好序,你在返回值里看不出任何异常。到了下游 Decimal 与 Decimal 相加时才崩,崩的位置与产生混排的位置隔了好几层。
Decimal('1.0') 与 int 的 1、float 的 1.0 相等,hash 也相同,所以它能直接命中 {1.0: ...} 这个字典键。这在缓存场景里是便利,在"用金额做键"的场景里是隐患:Decimal('1.00') 与 Decimal('1.0') 会被当成同一个键,而你原本想区分的是两种精度。
官方提供了一个把混用变成硬错误的手段 —— FloatOperation 信号:
「If the signal is not trapped (default), mixing floats and Decimals is permitted in the Decimal constructor, create_decimal() and all comparison operators. Both conversion and comparisons are exact.」
把 trap 打开之后,本机实测 Decimal(0.1)、sorted([0.3, Decimal('0.2')]) 都会抛 FloatOperation。这是我在财务模块入口最推荐的一行配置:让混用变成启动即崩的错误,而不是三个月后对不上的账。
分歧七:分摊一百块,朴素舍入少一分
total = Decimal('100.00')
raw = total / 3 # 33.33333333333333333333333333
naive = raw.quantize(Decimal('0.01')) # 33.33
naive * 3 # 99.99
三个人各 33.33,合计 99.99,少一分。这一分不会消失,它会变成一张永远对不平的对账单。
正确做法是最大余数法:先向下取整分配,再把余下的最小单位按小数部分的余数从大到小补回去。本机跑出来是 33.34 + 33.33 + 33.33 = 100.00。多出来的那一分给谁,规则要写进业务文档(通常是给余数最大的那一方,或给第一个受益人),不能靠"看情况"。
含税单价的偏差量级更大:
price = Decimal('19.99'); rate = Decimal('0.0825')
(price * (1 + rate)).quantize(Decimal('0.01')) # 21.64(单件)
(price * 100 * (1 + rate)).quantize(Decimal('0.01')) # 2163.92(先汇总)
Decimal('21.64') * 100 # 2164.00(先舍后乘)
100 件同价商品,两种顺序差 0.08 美元。听起来微不足道,但这是每 100 件 8 分的固定偏差,100 万件就是 800 美元量级的账实不符,而且方向恒定 —— 永远是先舍后乘的那一边更高。
所以舍入的时机比舍入的模式贵得多。模式错了是随机误差,时机错了是系统误差。写代码时的判据:中间结果不落库就不舍入,落库的金额必须是已经对齐过的最终值。
分歧八:序列化的最后一道门
金额在内存里算对了,出门时照样翻车。
json.dumps({'amount': Decimal('1.10')})
# TypeError: Object of type Decimal is not JSON serializable
conn.execute('insert into t values (?)', (Decimal('1.10'),))
# sqlite3.ProgrammingError: Error binding parameter 1: type 'decimal.Decimal' is not supported
两个报错都很直白,麻烦的是"顺手绕开"的那些写法。为了过 JSON,很多人写 float(amount),于是 1.10 变成了二进制邻居;为了过 sqlite3,很多人也写 float(amount),实测存进去后 typeof() 是 real,1.10 读出来是 1.1,再参与一次运算就可能变成 1.1000000000000001。
还有一层是显示与比较的分离:
Decimal('1.00') == Decimal('1.0') # True
hash(Decimal('1.00')) == hash(Decimal('1.0')) # True
str(Decimal('1.00')) # '1.00'
Decimal('1.00').as_tuple() # digits=(1, 0, 0), exponent=-2
Decimal('1.0').as_tuple() # digits=(1, 0), exponent=-1
相等、同 hash,但字符串不同、as_tuple() 不同。也就是说:比较层丢零,展示层保零。如果你依赖 str() 做展示而对相等做校验,两边校验的东西根本不是一回事。反过来说,这也是 Decimal 比 float 好用的地方 —— 它记住了"这是两位小数",金额字段的末尾零不会在往返中蒸发。
工程上的落地:数据库存整数分(BIGINT)或 NUMERIC(18,2),应用层用 Decimal 与之对应;JSON 里金额一律用字符串;序列化层写显式 encoder,不要留给"顺手 float 一下"。
Troubleshooting:六个我真实撞到的报错
下面六个报错全部来自本机复现,不是文档示例。
- TypeError: unsupported operand type(s) for +: 'decimal.Decimal' and 'float' —— 混算。修法是源头统一类型,或在模块入口打开
FloatOperationtrap 让它在启动时先崩。 - decimal.InvalidOperation —— 本机有两条来路:一是量化结果的位数超过上下文精度(
Decimal('1e30').quantize(Decimal('0.01'))在 prec=28 下必抛,改成Context(prec=40)就正常输出 1000000000000000000000000000000.00);二是 NaN 参与比较(min(Decimal('NaN'), Decimal('1'))直接抛)。它的异常文本里嵌着类名字符串,看起来像个未处理的内部错误,实际是正常信号。 - decimal.DivisionByZero —— 除零。要注意它的 MRO 是
DivisionByZero到DecimalException到ZeroDivisionError,所以except ZeroDivisionError能接住它,但日志里type(e).__name__打印的是 DivisionByZero。用except decimal.DecimalException更准,能一次覆盖 InvalidOperation、DivisionByZero、Overflow 三个默认 trap。 - decimal.Overflow —— 溢出。float 在这件事上给
inf,Decimal 默认直接抛。Decimal('1e999999') * Decimal('1e999999')本机抛 Overflow。它的 MRO 里还带着 Inexact 与 Rounded,意味着你except decimal.Inexact也会把它当成"不精确"捕获 —— 一个非常好笑的陷阱。 - FloatOperation —— 只在 trap 打开时出现。打开之后
Decimal(0.1)也抛,因为构造本身就算混用。这一条要写进项目约定,否则同事会以为是 bug。 - json 的 TypeError 与 sqlite3 的 ProgrammingError —— 上一节那两个。修法不是
float(),是字符串或整数分。
一份可以直接抄的金额处理清单
- 入口:金额一律以字符串或整数分进入系统;
json.loads(..., parse_float=str)、CSV 读成文本、Excel 读单元格文本。 - 构造:永远
Decimal(str(x)),绝不Decimal(float_x);从 ORM 拿到 float 时先str()再Decimal(),并记一次日志,因为这说明上游有 float 泄漏。 - 精度:每次进入财务计算函数时用
localcontext(prec=...)显式设定,下限按"整数位 + 小数位 + 乘数最长小数位 + 1"算。 - 舍入:所有
quantize显式写rounding=,不要依赖默认的半偶;负金额(退款、冲正)单独验一遍 HALF_UP 的"远离零"语义。 - 时机:中间结果不舍入,落库与对账的金额必须是最终对齐值;同一笔业务的所有舍入只发生一次。
- 分摊:用最大余数法补差,补差规则写进文档,并对"分摊合计等于总额"写断言。
- 混用:财务模块入口设置
getcontext().traps[decimal.FloatOperation] = True,让混用变成启动错误。 - 存储与传输:DB 用 BIGINT 分或 NUMERIC(18,2),JSON 用字符串,日志里打印
str()而不是float()。
这份清单不解决所有问题(币种、汇率日期、税务规则都在它之外),但它能挡掉本文八个分歧里的全部八个。
常见问题
Q:只做展示、不做计算的金额,能存 float 吗?
如果这个数一辈子不参与运算、不参与相等判断、不进聚合,float 是可以的。但只要它有可能被求和、被排序去重、被拿去和另一条记录比相等,就该用 Decimal。判断成本很低:问一句"这个字段会不会出现在 GROUP BY 或相等比较里"。
Q:Decimal 的 precision 设成多少才够?
按"金额整数位 + 小数位 + 最长乘数小数位 + 1"算,得到的是一个下限而不是建议值。普通电商两位小数、十亿量级、四位税率,17 位够;做单位换算或复利时按实际链条算一遍再往上取整到 10 的倍数。设大了不会有精度损失,只多占几个字节。
Q:为什么 1.005 用 ROUND_HALF_UP 是 1.01,f-string 却是 1.00?
因为 f-string 处理的是 float 1.005,它实际存的是 1.00499999999999989342,比一半小,任何规则都往下舍;而 Decimal('1.005') 是精确的一半,HALF_UP 就往远离零的方向进。这不是 Python 的 bug,是二进制与十进制两种表示的必然差异。
Q:有没有现成的库可以少踩这些坑?
标准库就够用,关键是用法。第三方财务库能帮你封装分摊与币种,但封装不掉本文的八个分歧 —— 它们都在 Decimal 与 float 的边界上,而不在业务逻辑里。先把边界管住,再谈封装。
结语
这八个分歧有一个共同形状:代码不报错,结果不对,而且错得很小。小到单元测试抓不到,小到上线三个月才被财务发现,小到修的时候不敢改。
它们也不是 Python 独有的问题 —— 任何一门用二进制浮点表示十进制金额的语言都有同一套坑,只是 Python 把两套数值类型同时摆在你面前,让你误以为"用了 Decimal 就安全了"。真正决定结果的是三件事:数据从哪进来、上下文是谁的、舍入发生在第几步。
我在这条线上还写过两篇相邻的:一篇讲 SQL NULL 的三值逻辑,那里出问题的是分母;一篇讲 Unicode 规范化,那里出问题的是"看起来一样"。加上这篇的"最后一位",三篇讲的是同一件事:值在边界上会变形,而边界不写在类型签名里。序列化那一层的坑,我在 json、orjson 与 msgspec 的默认值对照里量过一遍,可以接着看。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。