1 错误与异常的概念边界
1.1 错误（Error）的定义与特征
在Records语境中，“错误”指系统在处理数据、校验规则或业务约束时，得到的非正常结果。它通常具有明确的判定条件，能够被归入可预期的失败类别，例如字段缺失、格式不匹配、约束违背或规则校验失败等。错误往往与“输入不符合规范”或“结果不满足约束”紧密相关，因此更容易被标准化为可枚举的结果类型并形成错误字典。
1.2 异常（Exception）的定义与特征
“异常”指流程执行过程中出现的中断性或未被常规覆盖的情况，表现为运行路径偏离预期或出现无法正常处理的状态。与错误相比，异常未必总是由用户输入直接造成，更多是运行时环境、依赖服务、资源约束或不可达条件触发。异常常伴随更复杂的上下文，例如调用链、执行栈、依赖返回状态等，因此更依赖追踪与现场信息进行定位。
1.3 错误、异常与失败（Failure）的关系
“失败（Failure）”是更宽泛的结果概念，指一次处理未能达到预期目标。在Records系统中，错误与异常都可以是失败的原因或表现形式：
- 某些失败可直接归类为错误，例如校验失败导致记录无法落库。
- 某些失败由异常引发，例如依赖不可达导致流程中断并最终失败。
- 也可能出现“失败”但具体原因仍需进一步归因，此时错误与异常的分类与记录策略就尤为关键。
1.4 严重程度与影响范围的基本分级
为便于处置与审计，通常需要对严重程度与影响范围进行分级。常见做法是结合以下维度进行分层： 1) 对单条记录的影响还是对一批记录的影响； 2) 是否会导致数据丢失或一致性破坏； 3) 是否会引发流程级中断（例如停止消费、停止写入）； 4) 是否可恢复以及恢复成本。 据此可形成从轻度可忽略到高危需立即处理的多档策略，并在日志、指标与告警中保持一致口径。
2 记录系统中的常见错误类型
2.1 数据校验错误
数据校验错误通常发生在进入业务处理前或落库前的规则判断阶段。其核心特征是可验证、可定位，且多数情况下与输入内容直接相关。
2.1.1 字段缺失与必填约束违背
当记录缺少必填字段或字段存在但为空、不可用时，系统会判定为校验失败。这类问题常见于上游生成不完整、字段映射遗漏或版本升级未同步等场景。
2.1.2 数据类型与格式不匹配
字段类型不符合预期（如应为数字却收到字符串），或格式不符合约定（如日期格式、编码、长度限制）时，会触发类型与格式校验错误。该类错误通常便于用样本对照规则字典进行修正。
2.1.3 范围、枚举与正则校验失败
当数值超出允许区间、枚举值不在集合内，或文本未通过正则表达式校验时，会被归为范围/枚举/正则错误。它们往往反映业务规则变更未同步或输入语义偏差。
2.2 关联与一致性错误
关联与一致性错误强调“记录之间的关系”与“跨字段/跨记录的一致性”。这类错误可能不易在单条记录层面解决，需考虑依赖关系与写入顺序。
2.2.1 外键/引用不存在
当记录中的引用目标不存在（例如引用ID找不到对应实体）时，会触发引用缺失或外键约束相关错误。解决方案通常涉及补齐上游数据、调整写入顺序或引入延迟处理。
2.2.2 去重与唯一性冲突
如果系统要求特定键组合唯一，但实际写入发现重复，则会产生唯一性冲突错误。该问题可能来自重复投递、并发写入或幂等键设计不当。
2.2.3 幂等性破坏与重复写入
当同一业务操作被多次执行且系统未能正确识别“已处理状态”或未正确界定事务边界，就可能出现重复写入引发的业务层冲突。与简单的“重复数据”不同，此处强调的是幂等机制未能有效约束结果。
2.3 解析与映射错误
解析与映射错误通常发生在将输入载荷转换为内部模型的阶段。它们反映“数据表述”与“系统认知模型”之间存在差异。
2.3.1 解析失败（反序列化/语法错误）
当输入载荷不是预期格式，或语法结构无法被解析（例如JSON片段损坏、编码异常）时，会出现解析失败。此类问题往往需要关注输入侧的传输质量与版本兼容策略。
2.3.2 模型映射失败（字段对不上）
即便载荷能成功解析，也可能因为字段命名、层级结构或类型定义不一致而映射失败。常见原因包括字段改名、嵌套层级调整、模型版本漂移等。
2.3.3 单位与语义不一致
当数值表达在不同系统间存在单位差异（例如米与厘米、毫秒与秒）或语义口径不同（例如“状态”字段含义变化），系统可能无法仅靠类型校验识别问题，从而表现为业务层异常。为降低此类风险，往往需要额外的语义校验与数据字典治理。
2.4 流程与状态错误
流程与状态错误强调业务编排与状态机的正确性。即使数据本身合法，只要流程状态不符合约束，同样会被判定为错误或异常。
2.4.1 状态机不允许的跳转
状态机模型通常规定从某状态只能进入有限的下一状态。当记录在不允许的条件下发生跳转，例如从“未开始”直接进入“已完成”，就会触发状态错误。该类错误常见于并发竞态或消息乱序。
2.4.2 依赖未满足导致的时序错误
流程执行可能依赖其他前置条件，例如先完成关联资源创建，再进行后续处理。若依赖尚未就绪而流程提前推进，就可能出现时序错误。此类错误常通过等待、事件驱动或补偿机制处理。
2.4.3 并发写入引发的状态冲突
在并发场景下，多次更新同一记录可能造成状态版本冲突。若系统缺少乐观/悲观锁或未能正确处理冲突合并策略，就可能导致状态不一致、重复执行或流程分叉。
3 异常触发来源与上下文
3.1 输入侧异常
3.1.1 外部数据格式变更
上游系统在字段、结构或编码方式上变更，而下游未同步兼容策略，可能导致解析、映射与校验异常。该类异常通常呈现为突然的错误增长，并与部署或版本发布时间相关。
3.1.2 传输截断与不完整载荷
网络传输或消息队列投递过程中出现截断、丢段、超时截取等情况，会造成载荷缺失。表现可能是解析失败、字段缺失或校验异常，且往往伴随特定链路或批次特征。
3.2 处理侧异常
3.2.1 计算过程中的运行时问题
处理逻辑执行时可能遇到运行时问题，例如除零、类型转换失败、空指针访问（概念层面）或算法边界条件。此类异常通常需要堆栈与输入上下文联动分析。
3.2.2 资源不足（内存/超时/配额）
当计算节点资源紧张，或处理超出预设时限、配额限制时，会触发中断性异常。该类问题既可能来自流量突增，也可能是单条记录数据量异常导致的资源放大效应。
3.2.3 依赖服务返回异常
依赖服务超时、返回错误状态、返回结构不符合约定，或出现结果为空等情况，都可能触发异常。为了区分“可重试”与“不可重试”，需要对依赖返回的类别建立口径。
3.3 输出侧异常
3.3.1 写入失败（存储/索引）
落库或更新阶段可能因存储不可用、写入超时、索引约束失败等原因失败。写入失败既可能是瞬时抖动，也可能反映数据质量问题或索引策略变化。
3.3.2 结果生成失败（导出/序列化）
当系统需要生成导出文件或序列化输出时，可能因模板错误、编码异常、数据过大导致的序列化失败而中断。此类异常通常与特定输出路径相关。
3.3.3 后处理失败（回调/通知）
记录处理完成后若还需触发回调或发送通知，可能因回调接口不可用、认证失败、网络错误而导致后处理失败。是否影响主流程结果取决于业务要求与容错策略。
4 错误与异常的表示方式
4.1 错误码（Error Code）与枚举体系
错误码用于将失败类型映射到稳定、可机器处理的标识。良好实践是：错误码在版本演进中保持兼容、具备层级或分类规则、且与错误字典联动。异常也可使用类似机制对“异常类别”进行归档，而将堆栈留给追踪。
4.2 错误信息（Message）与本地化
错误信息面向日志阅读与用户提示。通常会区分：面向排障的详细信息与面向展示的简洁描述。若涉及多语言环境，可采用本地化策略，使同一错误码在不同语言下展示一致语义，同时避免在message中混入过多内部实现细节。
4.3 异常堆栈（Stack Trace）与追踪标识
堆栈用于呈现异常发生的调用链信息，追踪标识用于关联同一次请求在不同组件间的执行轨迹。二者共同构成排障“现场证据”，尤其在异常类型难以从错误码单独判断时更有效。
4.4 元数据（Metadata）与上下文字段设计
元数据用于描述失败发生的环境与要素，例如记录ID、批次ID、版本号、输入摘要、处理阶段、依赖标识、时间戳与耗时等。上下文字段设计应尽量结构化，以支持检索、聚合统计和审计回放。
4.5 可读性与可排查性权衡（不泄露敏感信息）
为了兼顾排查效率与安全，输出内容通常需要脱敏或最小化：
- 对敏感字段采用掩码或哈希摘要；
- message避免暴露内部路径、密钥、系统拓扑等；
- 日志保留必要上下文但控制体量与访问权限。
这样既能降低泄露风险，也能保证定位成本可控。
5 处理策略与恢复机制
5.1 分类处理：可重试、不可重试与降级
恢复策略首先要判断失败是否可能通过重试改善。一般可重试的情形包括暂时性超时、瞬时性依赖不可用；不可重试的情形多与数据质量或约束违背相关。对于可降级的场景，可采取部分功能关闭、延迟处理或使用默认值，尽量避免全局中断。
5.2 重试策略与退避（Retry & Backoff）
重试策略常配合退避算法，避免“重试风暴”。典型要素包括：最大重试次数、退避间隔（固定或指数）、抖动（jitter）以分散并发压力，以及对特定错误码的快速判定（例如直接拒绝某类不可重试错误）。
5.3 幂等保障与事务边界
幂等保障用于防止重复执行带来重复副作用。实现上常见做法是：为业务操作建立幂等键，使用去重表或状态标记；并明确事务边界，避免“部分写入后失败”造成不可恢复的中间态。
5.4 回滚、补偿与“最终一致”处理
当失败发生在多步骤流程中，可能需要回滚或补偿。回滚适用于可逆且成本可控的步骤；补偿适用于不可直接回滚的情形。对于分布式系统，允许采用最终一致策略，通过事件重试或补偿任务逐步收敛到一致状态。
5.5 死信队列/隔离区（Dead-letter/Quarantine）
对于不可恢复或多次失败的记录，可投递到死信队列或隔离区以脱离主处理链路。隔离机制通常包括：保留失败上下文、标记错误码、限制重试频率、提供人工或离线修复通道。这样既能保护主流程稳定，也保留了后续审计与回放的依据。
6 可观察性：记录、监控与审计
6.1 结构化日志的要求
结构化日志强调字段化、可检索与可聚合。日志通常包含错误码、阶段、记录标识、耗时、依赖信息与追踪标识，并保持稳定字段集合，便于后续分析与规则告警。
6.2 指标监控与告警阈值
指标常覆盖错误率、异常数、按错误码分布、重试次数、队列积压、处理延迟与失败回放成功率等。阈值告警应结合历史基线与业务波动设置，避免频繁误报，同时确保高危故障能及时触发处置。
6.3 链路追踪与相关性ID
相关性ID用于串联一次请求或一次批处理在多个服务间的执行。通过链路追踪可以快速判断失败发生在何处、耗时在哪个环节集中增长，并区分是数据问题、处理问题还是依赖问题。
6.4 审计记录与合规留痕
审计侧关注“发生了什么、何时发生、由谁/由哪个流程触发、采取了哪些处置”。在受监管或需要追溯的场景中，错误与异常记录往往需要保留足够证据以支持复核与调查，同时遵循数据最小化与访问控制。
6.5 报表与错误预算（Error Budget）概念（轻量化介绍）
错误预算是一种将可靠性目标量化并用于运行决策的概念：允许在一定期间内存在“可容忍的错误量”，超出后需要提高工程投入或暂停某些高风险变更。其核心价值在于把稳定性治理从口号变成可度量的运行指标。
7 故障排查流程
7.1 复现与最小化（Repro & Minimization）
排查通常从可复现开始：收集触发失败的输入样本、环境版本与配置，并尝试将案例最小化以降低变量数量。最小化样本有助于快速验证修复方案并减少误判。
7.2 定位环节：输入—处理—输出
将问题划分为输入、处理与输出三段，有助于缩小搜索范围：
- 若输入阶段失败，多围绕解析、校验与映射；
- 若处理阶段失败，多围绕业务逻辑、资源与依赖；
- 若输出阶段失败，多围绕写入、序列化与通知。
这种分段思路能减少“盲目追堆栈”的成本。
7.3 检查依赖：版本差异与契约变更
依赖检查重点包括：依赖服务版本、接口契约、字段定义、错误码规范与兼容性策略是否发生变化。契约变更往往是异常激增的根因之一，因此需要对比发布记录与契约文档。
7.4 核查数据样本与上下文字段
核查应同时关注数据本身与上下文字段：例如记录版本号、来源系统、批次时间窗、幂等键、阶段标记与追踪ID。通过对照成功样本与失败样本，可以更快识别差异点并校正规则。
7.5 修复验证与回归（含回放机制）
修复需要验证其对“已知失败”的纠正效果，同时进行回归测试以避免引入新问题。回放机制可基于失败样本或死信队列进行重放，确保变更后系统行为符合预期并维持稳定性。
8 规范与最佳实践（Records视角）
8.1 统一的错误分类与命名规则
应建立统一的错误分类体系，使相同语义错误在不同组件中具备一致错误码与字段结构。命名规则需要稳定且具备层级，以便跨系统统计与运维协作。
8.2 错误信息的风格与提示层级
错误信息建议分层：面向用户的提示简短明确，面向排障的细节通过结构化字段或日志提供。对于可能影响用户操作的错误，应给出可执行的建议，例如“缺少必填字段X”“请更换正确格式”等。
8.3 避免“吞错”与静默失败
静默失败会让系统表现为“看似正常但结果不对”，极难排查。最佳实践是对每次失败进行明确记录与可见性输出：即使走降级路径，也应保留错误码与原因，以免形成“不可追踪的空洞”。
8.4 测试覆盖：异常用例与边界条件
测试应覆盖常见失败路径，包括：校验边界、映射兼容、状态机非法跳转、并发冲突、超时与依赖异常，以及死信队列投递行为。对边界条件的覆盖能显著降低线上偶发故障的概率。
8.5 文档化：错误字典与示例（含“翻车梗”示例的可选条目）
错误字典应给出：错误码、含义、触发条件、建议处理方式与示例输入输出。可在文档中加入轻量的“翻车梗”以提升团队记忆点，但需确保仍遵循规范化字段与可检索要求，并避免用梗取代正式说明。
9 轻量梗文化：常见吐槽式异常（可选）
9.1 “404：看起来数据不想见你”
用于表达引用目标或资源未找到的情形，可作为面向排查或内部讨论的轻量提示语。实际系统仍应以错误码与上下文字段作为主要判定依据。
9.2 “字段缺失：少了它就不让你过”
用于描述必填字段缺失、空值导致校验失败的情形。该吐槽可与错误码绑定，便于团队快速定位是“数据不全”而非“逻辑出错”。
9.3 “格式不对：像把钉子装进螺丝刀里”
用于形容格式或类型不匹配导致解析/校验失败。此类提示适合用于日志摘要或测试用例描述，但不应替代结构化错误信息。
9.4 “幂等失败：你又来了（但系统没准备好）”
用于描述幂等键未生效或重复写入引发冲突的情形。该类提示语通常用于提醒工程团队检查幂等机制与事务边界是否正确。