1. 课程导论：错误处理在API设计中的重要性，事务边界的概念，移植适配的挑战与目标

1.1 错误处理在API设计中的核心地位

在分布式系统与微服务架构中，API 是服务间通信的唯一契约。错误处理不再是“可选的异常捕获”，而是 API 契约的一等公民。一个设计不良的错误响应会导致调用方解析失败、链路追踪断裂、事务补偿误判，甚至引发雪崩效应。

1.2 事务边界的概念与治理困境

事务边界定义了一组操作要么全部成功，要么全部回滚的原子性范围。在单体架构中，事务边界由数据库本地事务（ACID）天然保障。但在微服务与 API 网关治理场景下，事务边界跨越了多个独立服务、不同数据源、甚至异构协议。

• 本地事务边界：单一数据库连接内，由 BEGIN/COMMIT/ROLLBACK 控制。
• 分布式事务边界：跨服务、跨数据库，依赖 Saga、TCC、两阶段提交（2PC）等模式。
• API 事务边界：从请求入口到响应出口，包含认证、限流、参数校验、业务逻辑、持久化、事件发布等阶段。

当错误发生在 API 事务边界内部时，错误处理逻辑必须知道当前处于事务的哪个阶段，才能决定是重试、补偿还是终止。这正是“移植适配”问题的根源——不同服务对事务边界的认知不一致。

1.3 移植适配的挑战与目标

“移植适配”指将一套成熟的错误处理策略（如基于错误码的补偿路由、基于重试预算的退避算法）从一种事务边界模型迁移到另一种模型时，所面临的语义对齐与行为兼容问题。

核心挑战

1. 语义鸿沟：服务 A 的“超时错误”在服务 B 的事务边界中可能被解释为“不可重试的致命错误”。
2. 状态可见性缺失：上游错误处理逻辑无法感知下游事务边界的当前阶段（已提交/已回滚/悬空）。
3. 补偿策略冲突：两个服务对同一错误类型定义了不同的补偿动作，导致补偿链断裂或死循环。
4. 协议异构：REST、gRPC、消息队列的错误模型不同，错误码、元数据、重试语义无法直接映射。

课程目标

1.4 课程知识体系与学习路径

本课程共 30 章，按“基础概念 → 模式设计 → 适配实现 → 治理验证”四阶段递进。下表展示了前 5 章的知识锚点：