外观
同一份文件为何乱码或金额算错:文本、二进制与数据转换
摘要
文件在一台机器正常、另一台乱码,金额累加又出现意外小数,常见根因是数据边界没有写清。本文面向 Python 初学者,解释 str、bytes、编码、JSON 与浮点数,给出可运行的转换对照。
1. 场景:读取成功,不代表读懂了数据
这是一个教学场景:日志工具把包含中文的 JSON 文件交给另一台机器,读取时抛 UnicodeDecodeError;有人把错误处理改成忽略,程序能运行了,却丢掉了字段内容。另一个汇总任务把 0.1 与 0.2 相加后比较 0.3,结果竟然是假。这两件事看似不相关,实际上都要求区分:外部表示是什么,程序内部对象是什么,转换按照什么规则发生。
给每次转换标出输入、规则和输出:能转换只证明满足该转换器的条件,正确解释还必须满足业务语义。 文件系统保存字节,JSON 给出文本结构,应用决定编码与字段含义。金额字符串能被 float 接收,也不说明得到的二进制数适合该账务规则。
先预测:同一 UTF-8 字节改用 Latin-1 解码,是报错还是产生另一串文本?后者同样可能成立,所以“没有异常”不是验收终点。再固定两笔 0.005,只改变逐项舍入还是合计后舍入,账面结果就会分叉。沿表示、解释、计算、输出逐层核对,比全局换一种类型更能定位错误。
2. str 与 bytes 表示不同层次
str 是 Unicode 文本序列。Unicode 是字符及相关规则体系,code point(码点)是其中用整数标识字符的单位。bytes 是不可变字节序列,每个元素取值零到二百五十五。字节可能表示 UTF-8 文本,也可能表示压缩数据、图片、协议头或密文;仅看到 bytes 不能知道内容是什么。
encoding(编码)把文本变成字节,decoding(解码)把字节按指定编码解释成文本。Python 中 text.encode("utf-8") 从 str 得到 bytes,payload.decode("utf-8") 从 bytes 得到 str。方向不能颠倒,也不能把已有文本再随意“解码一次”。str(payload) 通常得到字节对象的可读表示,可能包含 b'...' 和转义形式;这不是按 UTF-8 解码的替代方法。相关类型定义见 数据模型。
UTF-8 是 Unicode 的一种字节编码,字符并不都占一个字节。len("订单") 计算 Python 字符串中的码点数量,len("订单".encode("utf-8")) 计算编码后的字节数。用户感知的一枚字符还可能由多个码点组成,例如组合附加符或某些 emoji,因此两种长度都不必等于界面上可见字符数量。接口限制要写明按字节、码点还是业务显示单位计数。
Python 的字符串内部表示也不是“总以 UTF-8 字节存储”。CPython 有自己的 Unicode 对象表示,具体选择与内容及实现有关;外部协议编码与内部存储不能混为一谈。本篇不通过 sys.getsizeof 的单次输出推导每个字符固定占几个字节,也不凭切片结果说明用户感知字符的边界。对文本处理保持这两层区分,就能避免很多跨系统误读。
3. 文件模式决定 Python 帮你做哪些转换
open(path, "r", encoding="utf-8") 以文本模式读取,返回文本,负责解码及相应换行处理;open(path, "rb") 以二进制模式读取,返回字节,不传 encoding。文本模式默认的换行处理可能把不同平台换行转换为 \n,写入时也可能按平台转换。图片、压缩文件和精确协议字节应使用二进制模式,避免不必要转换。规则见 官方输入输出教程。
在 Python 3.14,未指定编码的文本 open 默认行为受平台和 UTF-8 模式等环境影响,不应写成“所有系统默认 UTF-8”。明确已知文件是 UTF-8 时,显式传 encoding="utf-8",让读写协议不依赖部署环境。历史文件若确实是另一种编码,应使用来源约定,不要因为另一编码“不会报错”就认定内容正确。某些编码可以为任意字节生成字符,静默错误比显式异常更难定位。
errors="ignore" 会跳过无法处理的数据,errors="replace" 会替换它们;这可能适合对损坏日志做尽力展示,但不适合悄悄处理订单、签名或主键。默认严格错误更容易暴露边界不一致。需要容错时,记录损坏计数、原始来源和处理规则,并保留必要的可追踪信息。不要把“程序不报错”当成数据完整性证据。
路径同样有边界。pathlib.Path 用对象表示文件路径,可以组合目录和文件名、读取文本或字节。相对路径基于进程当前工作目录,不自动基于源文件所在目录。脚本从编辑器运行成功,服务启动后找不到文件,往往是工作目录不同;需要配置根目录或明确资源定位。路径处理不等于权限校验,也不会自动保证文件存在,实际读取仍可能失败。
4. JSON:结构互通,类型语义还要约定
serialization(序列化)把内存数据转换为适合存储或传输的表示;deserialization(反序列化)恢复相应对象。标准库 json.dumps 返回 JSON 文本字符串,json.loads 从文本解析;dump 与 load 接收文件对象。名字中的 s 可以记为字符串形式,不要把 dumps 的返回值当成已编码的网络字节。 可进一步阅读序列化协议选型:跨服务序列化解释表示协议与兼容边界。
ensure_ascii=False 控制非 ASCII 字符是否以直接字符形式输出,不负责文件编码。json.dumps(..., ensure_ascii=False) 得到含中文的 str,随后仍需要用 UTF-8 写成字节。默认转义产生 ASCII 形式也不表示它用了另一个中文编码,两种 JSON 文本可以表达同一数据。官方教程给出 JSON 的 UTF-8 文件读写建议,见 JSON 数据保存。
JSON 不保存所有 Python 类型的语义。元组通常恢复为列表,键通常需要字符串表达,Decimal 也不会默认自动序列化为你需要的金额格式。跨系统传金额,可以约定字符串小数、最小货币单位整数,或经过明确协议支持的数值形式。"0.30" 作为字符串保留了协议表达,使用时再按校验规则转 Decimal;这不是宣称金额永远必须字符串,而是本篇最小实验的明确约定。
处理非可信输入还需要规模和结构限制。JSON 解析成功不等于包含必需字段,也不保证嵌套深度、字段长度和总字节量合理。不要用 eval 把文本当 Python 表达式执行,也不要用 pickle 接收来源不可信的数据;后者可能执行任意代码,官方教程明确提醒安全边界。输入校验与类型注解的区别将在第十三篇展开。
5. 浮点数:误差来自表示,不是加法坏了
binary floating point(二进制浮点数)用有限位数表示二进制有效数字和指数。有限十进制小数不一定有有限二进制表示,0.1 与 0.2 会取附近可表示的值。它们相加得到的值再与 0.3 对应的近似值比较,可以不相等。官方解释见 浮点数教程。
显示时看起来短,并不证明内部精确。Python 的浮点表示通常选择能往返恢复该浮点数的简洁文本;格式化保留两位小数只改变显示,不把原对象变成精确十进制。对测量值比较,使用符合业务误差范围的 math.isclose 等方法;绝对误差与相对误差应按单位和数值范围选择,不能随手复制一个阈值到所有系统。
decimal.Decimal 支持十进制数和可配置精度、舍入规则。Decimal("0.1") 从精确十进制文本创建;Decimal(0.1) 接收已经近似的浮点值,会保留该浮点值对应的十进制表达,而不是神奇恢复原输入意图。正确的源头转换比后面增加小数位重要。精度上下文、除法与舍入仍可能产生近似,Decimal 也不是所有运算都无限精确。
金额最终规则通常还需要币种和舍入位置:逐项舍入再相加,与先相加再舍入可能不同;税额、退款和分摊要依据业务规范。使用 quantize 时明确目标精度与舍入方式。本文只验证三份固定小数的表示差异,不替任何支付系统选择默认舍入策略。具体机制见 decimal 文档。
图表将在阅读到此处时加载…
每根箭头都有规则;把其中两步混在一起,异常就难以定位到正确边界。
6. 最小实验:编码错误与浮点输入污染
先把实验分成两条轨迹。文本从“订单”编码为 UTF-8 字节,再按约定解码,应回到原文;换 ASCII 会报错,换 Latin-1 则未必报错但不等于原文。金额从十进制文本进入 Decimal 后,再按明确上下文计算;两笔各舍入到分得到 0.02,先相加再舍入得到 0.01。两条轨迹都要求比较恢复的语义,不能只看转换调用完成。
完整程序在 06_data_boundaries.py,文件只写入临时目录:
python
"""所有数据在临时目录内;展示编码与金额转换边界。"""
from decimal import Decimal, localcontext, ROUND_HALF_UP
import json
from pathlib import Path
from tempfile import TemporaryDirectory
def main():
message = "订单"
payload = message.encode("utf-8")
assert payload.decode("utf-8") == message
try:
payload.decode("ascii")
except UnicodeDecodeError:
print("wrong encoding rejected")
mojibake = payload.decode("latin-1") # 每个字节均可解码,仍然不是原文。
assert mojibake != message
assert mojibake.encode("latin-1").decode("utf-8") == message
print("silent wrong decoding:", mojibake != message)
assert 0.1 + 0.2 != 0.3
good = Decimal("0.1") + Decimal("0.2")
assert good == Decimal("0.3")
assert Decimal(0.1) != Decimal("0.1")
with localcontext() as context:
context.prec = 12
context.rounding = ROUND_HALF_UP
amounts = [Decimal("0.005"), Decimal("0.005")]
item_total = sum(value.quantize(Decimal("0.01")) for value in amounts)
aggregate_total = sum(amounts).quantize(Decimal("0.01"))
assert (item_total, aggregate_total) == (Decimal("0.02"), Decimal("0.01"))
print("round items/aggregate:", item_total, aggregate_total)
with TemporaryDirectory() as directory:
path = Path(directory) / "events.json"
data = {"message": message, "amount": "0.30"}
path.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
restored = json.loads(path.read_text(encoding="utf-8"))
assert restored == data
print("json:", restored)
print("money:", good)
if __name__ == "__main__":
main()执行 python docs/python/examples/06_data_boundaries.py。预期第一行是 wrong encoding rejected,JSON 恢复为含 订单 与金额文本 0.30 的字典,最后为 money: 0.3。终端显示中文还受终端编码和字体影响;文件往返断言检查的是程序数据,不以截图外观替代验证。TemporaryDirectory 自动清理实验文件,资源管理将在下一篇继续解释。
错误编码被显式捕获,并没有丢弃字节后假装正确。正例在写入和读取两侧指定 UTF-8,同时把金额保持为字符串,避免先转换成浮点。断言可以证明固定数据往返一致,不能证明所有外部 JSON 都符合业务要求,也没有测量实际吞吐性能。
7. 排障与容易踩的坑
乱码排查从原始字节开始:确认文件来源、协议编码、读取参数和终端展示四个层次。保留一小段脱敏字节及其十六进制表示,能判断问题是否已经在上游产生;不要把已经错误解码的文本再次转来转去,靠外观试错。若数据经过多个服务,还需找出首次发生不一致的转换点。
金额排查则保留原始文本、构造方式、精度上下文与舍入位置。看到 Decimal 类型不意味着输入未经过浮点;看到两位小数输出不意味着计算值只有两位。把每次转换写成明确步骤,才能判断误差是表示、运算还是显示引入。分布式系统还要核对其他语言和数据库的金额类型,不能只修 Python 一端。
还有一个坑是把 bytes 与 str 直接拼接。它们表达不同层,Python 通常拒绝这类操作而不是猜测编码。修复应在协议边界选择转换,而不是为消除 TypeError 到处调用 str()。类似地,二进制文件不要用文本读写再“补回”编码,换行或解码已经可能改变数据。
8. 输入协议要约束类型,还要约束内容
给金额约定字符串形式后,还需要明确是否允许科学计数法、负数、空白、超长数字以及非有限值。仅仅 Decimal(text) 成功不代表这是一笔合法金额;十进制数也支持 NaN 和 Infinity 等特殊值。业务应检查有限性、范围、币种与小数位,避免把底层支持范围误认为接口允许范围。错误处理应返回明确失败,而不是用零替代所有无法接受的输入。
时间字段也需要类似约定。"12" 可能表示毫秒、秒或微秒,整数转换不提供单位信息;把各服务的耗时直接相加会造成看似合理但实际错误的报表。名称包含单位、协议文档明确单位,并在边界转换到统一口径,能减少隐式假设。对时间戳还应区分带时区时间与无时区时间,不通过一个字符串格式就推断绝对时刻。
文本规范化也是业务选择。某些视觉相同文本可能使用不同码点序列,精确字符串比较会认为不同。unicodedata.normalize 可以按选定形式规范化,但不能对所有标识字段不加分析就自动调用。用户名搜索、签名校验、原始日志保全与显示文本可能有不同要求。规范化后还可能改变长度,因此长度限制和规范化顺序也要定义。
对 JSON 中的重复字段,解析器默认处理方式可能使前面的值被后面的值替代;若协议不允许重复,需要使用适当钩子或入口校验识别,而不是解析成字典之后才期待找回已经丢失的区别。不同系统对重复键的处理可能不同,所以签名或权限字段不能依赖未约定的重复语义。涉及这类协议时应单独查阅双方实现和格式约束。
Python 标准库 json 默认还兼容 NaN、Infinity 等不属于标准 JSON 的数值形式;严格输出可设置 allow_nan=False,输入拒绝这些形式则需 parse_constant 等额外规则,不能把输出选项当成解析校验。具体边界见 json 的标准兼容说明。
文件读取也不能忽略规模。read_text 会把整个文本读入内存,适合本篇小型固定 JSON;巨大日志应逐行或分块处理。分块解码多字节编码时,一块末尾可能只有某个字符的部分字节,不能每块独立严格解码后假定边界正确。文本文件对象和增量解码器可以保留相应状态,后续流式处理篇会解释如何避免全量加载与边界截断。
二进制协议里还需要考虑字节序。把数值写成多个字节时,大小端规则决定高位和低位的排列;这与 UTF-8 文本编码是另一类问题。标准库 struct 等工具可以按明确格式转换,但两端必须共享格式定义。不能仅把整数转成字符串,再认为它已符合对方的二进制协议。
建立一个简单的检查清单,通常能减少上线后猜测:文件来源与编码、字段名称与类型、单位与范围、容错规则、最大规模、输出协议。每个边界都保留足够而不泄露敏感信息的错误上下文。明确规则后的最小实验应包含合法输入、错编码、错类型和边界值;不需要把所有 Unicode 和数值算法都塞进第一份脚本,但不能省掉自己接口实际依赖的前提。
9. 面试与延伸
Unicode 和 UTF-8 有何区别? 前者定义字符与码点等体系,后者是一种把这些码点表示成字节的编码。Python str 是文本,bytes 才是外部字节表示。
ensure_ascii=False 是否意味着文件按 UTF-8 写入? 不意味着,它控制 JSON 文本的转义形式,文件编码由读写过程决定。
为什么 Decimal(0.1) 不等于 Decimal("0.1")? 前者接受已经近似的二进制浮点值,后者接受十进制文本;转换源头不同,后续对象类型相同也无法抹平来源差异。
把转换模型迁移到协议校验与账务保存
把文件改成 HTTP 或数据库输入,字节到文本、文本到结构、结构到领域值的边界仍要逐层说明。新增的是谁提供协议和谁持久化结果。第十三篇用入口校验确认领域条件,第十六篇用事务保存已确定的账务结果;事务能保证操作边界,却不会替你纠正错误解码或错误舍入口径。
Latin-1 能把每个字节映射为字符,因此把 UTF-8 的订单字节按它解码不会报错,却得到另一串文本。实验用“不等于原文”确认损坏,再在字节确实未被改写的前提下逆向编码和正确解码恢复。现实中若曾使用 errors="replace" 替换或被其他系统二次转换,原字节可能已经丢失,不能承诺同样可逆。正确契约应从生产者定义编码开始,而不是挨个 codec 尝试直到不报异常。
Decimal 的 context(运算上下文)决定精度与舍入规则;localcontext 将教学设置限在局部范围,避免影响其他金额计算。quantize(Decimal("0.01")) 将指数对齐到两位小数;它仍受上下文精度与舍入约束,并不等价于格式化显示。实验明确选择 ROUND_HALF_UP,两笔 0.005 各舍入后相加得到 0.02,先相加再舍入得到 0.01。二者各自按规则正确,但对应不同账务契约,不能随意交换步骤,见Decimal 文档。
独立练习:由字符串读取三笔金额,显式拒绝非有限值并要求每笔不小于零;分别实现逐项舍入与总额舍入,记录原始输入、模式、结果。验收包括 0.005 边界及不合法输入;禁止经 float 中转。换上下文精度时应解释失败,而不是吞异常。基础汇总篇负责分类与坏行账目,数据库篇负责持久化一致性;数值规则必须先确定,再交给事务保存。
一句话总结:数据可靠性来自每个表示边界的明确转换,不能靠显示正常或类型名称保证。
- 文本与字节分开处理,已知编码显式传入,损坏数据不能静默吞掉。
- JSON 转义、文本编码和业务类型是不同层次,解析后还要校验结构。
- 精确金额从精确输入创建,并明确精度与舍入位置;格式化不修复计算误差。
参考:文件和 JSON、浮点数、decimal。独立示例已在 Windows x64 的 CPython 3.14.0 和 3.13.7 验证通过;编码默认行为按 Python 3.14 的具体模式理解。
上一篇:函数参数作用域与闭包。下一篇:异常链与资源清理。延伸:类型注解输入校验与测试。