Python UTF-8 分块解码：字符跨过读取边界时，怎样保留未完成字节
读取日志流时，英文测试完全正常，换成中文就偶发 UnicodeDecodeError，常见原因是把每次收到的字节块直接解码。读取边界由缓冲区决定，未必落在字符边界上。某一块末尾只含一个字符的前半段，并不能直接说明原数据已经损坏，后续块可能正好补全它。
AI生成概念示意图，非真实界面
观察一个字符被分到两块的过程
UTF-8 使用变长字节序列。示例文字 A中🙂B 共九个字节，我们主动切成四块，让中文和 emoji 都跨越边界。独立调用 bytes.decode 时，每块都被当成一份完整输入，第一块留下半个“中”就会报错。增加读取块大小只能降低遇到边界的机会，无法消除问题。
增量解码器为同一条流保存未完成字节，下一次输入继续补齐。中途返回空字符串也正常：本轮可能只收到 emoji 的中间部分，还不足以产生完整字符。不要把空解码结果当成文件结束，更不要因为没有输出就丢弃当前解码器，否则已保存的前缀也会丢失。
验证四块输入与全部两段切法
把代码保存为 utf8-stream-demo.py，用 Python 3 执行。实验不读取外部数据，直接从固定字符串产生字节，先展示逐块独立解码的失败，再使用同一个解码器恢复全文。随后遍历十个切点，检查任何一种两段切法都能得到相同文字。
import codecs
text = 'A中🙂B'
raw = text.encode('utf-8')
chunks = [raw[:2], raw[2:5], raw[5:7], raw[7:]]
try:
''.join(chunk.decode('utf-8') for chunk in chunks)
except UnicodeDecodeError:
print('independent decode: UnicodeDecodeError')
else:
raise AssertionError('the first chunk should be incomplete')
decoder = codecs.getincrementaldecoder('utf-8')(errors='strict')
pieces = [decoder.decode(chunk, final=False) for chunk in chunks]
pieces.append(decoder.decode(b'', final=True))
result = ''.join(pieces)
assert result == text
print('pieces:', repr(pieces))
print('result:', result)
for cut in range(len(raw) + 1):
decoder = codecs.getincrementaldecoder('utf-8')(errors='strict')
result = decoder.decode(raw[:cut], final=False)
result += decoder.decode(raw[cut:], final=True)
assert result == text
print('all split positions:', len(raw) + 1)
decoder = codecs.getincrementaldecoder('utf-8')(errors='strict')
decoder.decode(raw[:-2], final=False)
try:
decoder.decode(b'', final=True)
except UnicodeDecodeError:
print('truncated end: UnicodeDecodeError')
else:
raise AssertionError('truncated sequence must fail')
decoder = codecs.getincrementaldecoder('utf-8')(errors='strict')
try:
decoder.decode(b'\xff', final=False)
except UnicodeDecodeError:
print('invalid byte: UnicodeDecodeError')
else:
raise AssertionError('invalid byte must fail')流结束时必须完成最后一次检查
pieces 应显示五项：A、中、空字符串、🙂B、空字符串；result 应完整显示 A中🙂B。最后一项来自结束刷新。all split positions 应为 10，包含开头和末尾的空块，因此同时覆盖没有任何前段数据、以及后段为空的情况，不能只测几个方便的字符边界。
Python codecs 文档要求，最后一次 decode 使用 final=True，以便处理尚未完成的输入。代码故意去掉最后两个字节，使 emoji 缺少结尾；中途调用可以暂存它，最终刷新必须抛出 UnicodeDecodeError。若漏掉这一步，程序可能把被截断的日志尾部误判成成功读完。
“还没收齐”与“已经非法”要分别观察。最后一个实验输入单字节 FF，它不构成合法 UTF-8 起始字节，即使 final=False 也立即失败。增量处理提供的是跨块状态，不会把任意损坏的数据变成合法文字。错误发生后应按应用策略终止或隔离该输入，保留必要的原始证据。
让解码状态只服务于一条数据流
每个独立文件、连接或响应应有自己的解码器。若把上一份输入遗留的半个字符带到下一份文件，错误就会跨对象传播。相反，同一份连续输入中若每块都新建解码器，也会回到最初的问题。可以把解码器的创建、读取循环和最终刷新写在同一处，明确其生命周期。
用于数据导入时，优先保留 strict 错误策略；ignore 会删除无法解码的内容，replace 会引入替代字符，后续匹配和审计可能因此失真。若业务允许容错展示，应明确提示内容受损，并另存原始字节。选择编码仍依赖协议或文件约定，增量解码本身不会识别未知编码。
手动验收可把每块缩成一个字节，再加入更多中文和 emoji，结果应完全一致。还要分别截断末尾一、二、三个字节，核对哪些切法留下未完成序列。文本恢复后若要按行、CSV 字段或 JSON 记录处理，还需独立的结构解析阶段；一个完整字符不代表一条业务记录也已经到齐。
