本文详解如何编写一个兼容 UnicodeEncodeError 和 UnicodeDecodeError 的双模自定义错误处理器，实现字符串编码时将不可表示字符转为大写空格分隔的 UTF-8 十六进制格式（如 [E4 B8 96]），并在解码时自动还原为原始 Unicode 字符。
本文详解如何编写一个兼容 `unicodeencodeerror` 和 `unicodedecodeerror` 的双模自定义错误处理器，实现字符串编码时将不可表示字符转为大写空格分隔的 utf-8 十六进制格式（如 `[e4 b8 96]`），并在解码时自动还原为原始 unicode 字符。
在 Python 的 codecs 模块中，自定义错误处理器（error handler）可通过 codecs.register_error() 注册，并在 .encode() 或 .decode() 调用中通过 errors= 参数启用。关键在于：同一个错误处理函数可同时响应编码异常（UnicodeEncodeError）和解码异常（UnicodeDecodeError），只需在函数内部对异常类型进行分支判断并分别实现逻辑。
以下是一个完整、健壮的双模处理器 utf8_hex_replace 实现：
import codecs
import re
def utf8_hex_replace(exception):
if isinstance(exception, UnicodeEncodeError):
# 编码阶段：将无法转为 ASCII 的单个 Unicode 字符 → UTF-8 hex 表示（大写+空格分隔）
char = exception.object[exception.start]
hex_repr = char.encode('UTF-8').hex(' ').upper()
replacement = f"[{hex_repr}]"
next_pos = exception.start + 1
return replacement, next_pos
elif isinstance(exception, UnicodeDecodeError):
# 解码阶段：识别形如 [E4 B8 96] 的字节片段，还原为对应 Unicode 字符
raw_bytes = exception.object[exception.start:exception.end]
# 匹配方括号包裹的十六进制字符串（允许空格，如 b'[E4 B8 96]'）
match = re.match(rb'\[([0-9A-F ]+)\]', raw_bytes)
if match:
try:
# 提取并清理 hex 字符串（移除空格），转换为 bytes
hex_str = match.group(1).replace(b' ', b'')
decoded_bytes = bytes.fromhex(hex_str.decode('ASCII'))
# 以 UTF-8 解码为 Unicode 字符
replacement = decoded_bytes.decode('UTF-8')
next_pos = exception.start + len(match.group(0))
return replacement, next_pos
except (ValueError, UnicodeDecodeError):
raise exception # 格式非法或解码失败时，不静默吞错
else:
raise exception # 不匹配预期格式，交由默认策略处理
else:
raise exception # 其他异常类型不处理，原样抛出
# 注册为全局错误处理器
codecs.register_error('utf8hexreplace', utf8_hex_replace)
✅ 使用示例：双向验证
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
text = 'Hello, 世界'
# 编码：ASCII 不支持中文 → 替换为 hex 表示
encoded = text.encode('ASCII', errors='utf8hexreplace')
print(encoded) # b'Hello, [E4 B8 96][E7 95 8C]'
# 解码：将 hex 表示还原为原始字符
decoded = encoded.decode('ASCII', errors='utf8hexreplace')
print(decoded) # 'Hello, 世界'
# 验证往返一致性
assert decoded == text
⚠️ 重要注意事项：
- 解码逻辑依赖严格格式：该处理器仅识别 \[HEX\] 形式（如 [E4B896] 或 [E4 B8 96]），若输入含非法 hex（如 [GG]）、不匹配括号或多余字符，会触发 UnicodeDecodeError 并重新抛出，避免静默数据损坏。
- 性能考量：正则匹配与 bytes.fromhex() 在高频场景下有开销；如需极致性能，可预编译正则（re.compile(rb'\[([0-9A-F ]+)\]')）并复用。
- 编码器/解码器隔离性：此方案不修改底层编解码器，完全基于 Python 错误处理机制，安全、可移植，且不影响其他 errors 策略（如 'strict', 'ignore', 'replace'）。
- 扩展建议：若需支持多种编码（如 GBK、ISO-8859-1），可在解码分支中动态选择 decoded_bytes.decode(encoding)，但需确保 hex 原始字节确实对应目标编码——本例中因编码阶段固定用 UTF-8，故解码也必须用 UTF-8 才能正确还原。
通过这一设计，你获得了一个真正“对称”的自定义错误处理器：编码时生成人类可读的十六进制逃生序列，解码时精准逆向还原，无需额外状态管理或外部映射表，简洁、可靠、符合 Python 编解码协议规范。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
