Python 邮件解析器怎样通过 defects 记录异常格式

处理历史邮箱、转发链或第三方网关产生的邮件时，解析成功不等于输入完全规范。Python 的 email 包通常会先构造消息对象，再把发现的格式问题记录到对应对象的 defects 列表；只有把 policy 配成严格模式，缺陷才会升级成异常。

官方文档：https://docs.python.org/3/library/email.errors.html

实用做法是显式指定 policy，默认模式先读取正文和附件，再递归汇总每个 MIME 部件的 defects；对不能容忍脏数据的入口，再使用 raise_on_defect=True 让解析直接失败。

先让解析器保留问题，而不是立即中断

MessageDefect 是解析过程中发现的格式缺陷基类，和“解析器完全无法工作”的异常不是一回事。比如邮件头缺少冒号、multipart 没有边界、Base64 填充不正确，都可能留下一个仍可访问的消息对象。

解析器的 policy 还决定消息对象和缺陷处理方式。下面显式使用 policy.default，避免依赖解析器当前的默认值：

from email import policy
from email.parser import BytesParser

# 用一段最小的原始邮件模拟一个缺少冒号的头部。
raw = (
    b"From: sender@example.com\r\n"
    b"Subject: defect demo\r\n"
    b"X-Broken-Header without colon\r\n"
    b"Content-Type: text/plain; charset=utf-8\r\n"
    b"\r\n"
    b"hello\r\n"
)

# 显式选择现代 EmailMessage 工厂，并让默认 policy 记录缺陷。
message = BytesParser(policy=policy.default).parsebytes(raw)
print(type(message).__name__)
for defect in message.defects:
    # 类型名适合进入日志，字符串便于人工定位输入问题。
    print(type(defect).__name__, str(defect))

这段代码的重点不是猜测某一种错误名称，而是先把 defects 当作结构化线索读取。不同输入可能产生不同的缺陷类，生产代码应保留类型名和原始上下文，别用字符串等值判断替代类型判断。

根消息没有缺陷时，还要检查嵌套 MIME 部件

官方文档特别强调，缺陷记录在发现问题的消息对象上。一个 multipart/alternative 邮件的文本子部件出了问题，根对象的 defects 可能仍然为空。因此，只打印根列表会漏报。

from email.errors import MessageDefect

def collect_defects(part, path="root"):
    """递归收集每个 MIME 节点上的缺陷，返回可写入日志的记录。"""
    found = []
    for defect in part.defects:
        # 路径比单独的类名更有用，可以定位哪一个 MIME 部件有问题。
        found.append({
            "path": path,
            "kind": type(defect).__name__,
            "detail": str(defect),
        })

    if part.is_multipart():
        # iter_parts 只遍历当前层，递归调用负责继续深入子部件。
        for index, child in enumerate(part.iter_parts()):
            found.extend(collect_defects(child, f"{path}.parts[{index}]"))
    return found

def parse_with_report(raw_bytes):
    """解析 bytes 并返回消息对象与缺陷报告。"""
    message = BytesParser(policy=policy.default).parsebytes(raw_bytes)
    return message, collect_defects(message)

# MessageDefect 作为类型提示和异常分支的共同基类，便于统一记录。
assert issubclass(MessageDefect, ValueError)

报告中的 root.parts[1] 只是本文自定义的定位路径，不是 Python 内置字段。它的价值在于把“有问题”变成“哪个部件有问题”，后续可以只隔离附件、人工复核，或者保留正文继续处理。

记录后继续处理，还是遇到缺陷就失败

默认的 raise_on_defect=False 会把缺陷交给对象的注册逻辑；适合归档、清洗和兼容历史邮件。支付回执、签名材料或必须严格合规的输入，则可以创建一个严格 policy：

from email import policy
from email.errors import MessageDefect
from email.parser import BytesParser

# 严格模式把任何已识别缺陷升级为 MessageDefect 子类异常。
strict_policy = policy.default.clone(raise_on_defect=True)

try:
    # 仍然显式传 policy，避免解析器默认值变化影响行为。
    message = BytesParser(policy=strict_policy).parsebytes(raw)
except MessageDefect as exc:
    # 这里记录输入来源和异常类型，再决定拒绝、隔离或人工复核。
    print("邮件未通过严格解析：", type(exc).__name__, str(exc))

两种模式不是“宽松正确、严格错误”的关系，而是不同的业务策略：宽松模式保留可用数据并积累质量信号，严格模式把质量信号变成流程门槛。无论哪种模式，都应限制日志中的原始邮件内容，避免把正文或附件直接写入普通日志。

一张表记住边界

最后可用三个问题自查：为什么只看根 defects 会漏报？因为缺陷归属于发现问题的对象。为什么要显式指定 policy？因为解析器默认 policy 未来会变化。为什么不直接捕获所有 Exception？因为宽松模式本来就会返回对象，应该先读取缺陷报告，再按业务决定是否拒绝。