📚 课程目录第2章错误处理基础

2. 错误处理基础：错误类型、传播模式与语言范式

错误处理是构建可靠分布式系统的基石。在事务边界与调用链追踪场景中，错误的分类、传播方式以及语言层面的处理范式直接决定了可观测数据的质量与故障定位的效率。本节将系统梳理错误的核心类型、传播模式，并对比 Go 与 Python 两种主流语言在错误处理上的设计哲学。

2.1 错误类型：语法、运行时与逻辑

从软件工程角度，错误可划分为三个基本类别。理解这些类别有助于在可观测性系统中设计差异化的采集与告警策略。

错误类型	触发阶段	典型特征	可观测性处理建议
语法错误	编译/解释阶段	代码结构违反语言规范，无法生成可执行程序	CI/CD 阶段拦截，不进入运行时追踪
运行时错误	程序执行期间	除零、空指针、网络超时、资源耗尽	必须被 Span 捕获，记录异常堆栈与上下文
逻辑错误	程序执行期间	业务规则违反、数据状态不一致、边界条件遗漏	需通过断言或业务指标暴露，常表现为错误的事务结果

实践要点：在 OpenTelemetry 调用链中，运行时错误应直接映射为 Span 状态（Status.Error），而逻辑错误更适合通过自定义属性（Attributes）或业务事件（SpanEvent）传递，避免与系统级异常混淆。

2.2 错误传播模式

错误在分布式系统中的传播路径决定了故障根因分析的复杂度。以下是三种核心传播模式，它们直接影响事务边界的设计与调用链的完整性。

向上冒泡（Bubble Up）：错误沿调用栈逐层返回，每层可附加上下文信息。适用于同步调用链，Go 语言的标准模式。
隔舱隔离（Bulkhead）：错误在组件边界被捕获并转换为降级响应，防止级联故障。适用于微服务架构中的熔断与限流场景。
异步扩散（Async Propagation）：错误通过消息队列或事件总线传递，需要显式的错误通道或死信队列。适用于异步事务与事件驱动架构。

  关键认知：在事务边界处，错误的传播模式决定了是否需要回滚（Rollback）或补偿（Compensation）。向上冒泡通常触发事务回滚，而隔舱隔离则可能触发降级提交或本地补偿。

2.3 Go 语言错误处理范式

Go 采用显式错误检查的设计哲学，将错误作为函数返回值的常规部分。这种范式在分布式系统中提供了清晰的错误传播路径，非常适合与 OpenTelemetry 的 Span 状态绑定。

2.3.1 核心模式：错误即值

// Go 标准错误处理模式
func ProcessOrder(ctx context.Context, orderID string) (OrderResult, error) {
    // 创建子 Span
    _, span := tracer.Start(ctx, "ProcessOrder")
    defer span.End()

    // 步骤 1：校验订单
    if err := validateOrder(orderID); err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, "订单校验失败")
        return OrderResult{}, fmt.Errorf("validate order %s: %w", orderID, err)
    }

    // 步骤 2：扣减库存
    if err := deductInventory(orderID); err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, "库存扣减失败")
        // 事务边界：需要回滚
        return OrderResult{}, fmt.Errorf("deduct inventory for %s: %w", orderID, err)
    }

    span.SetStatus(codes.Ok, "订单处理成功")
    return OrderResult{Status: "completed"}, nil
}

Go 陷阱：不要忽略 _ 丢弃错误返回值。在事务边界处，被忽略的错误会导致 Span 状态为 Ok 而实际业务失败，造成可观测性数据与真实状态不一致。

2.3.2 错误包装与链路追踪

Go 1.13 引入的 %w 格式化动词支持错误链（Error Wrapping），配合 errors.Is 和 errors.As 可以在调用链中逐层解包。在 OpenTelemetry 中，建议将错误链的根因（Root Cause）记录到 Span 的 Status.Description 中。

// 错误包装示例
type TransactionError struct {
    Op  string
    Err error
}

func (e *TransactionError) Error() string {
    return fmt.Sprintf("%s: %v", e.Op, e.Err)
}

func (e *TransactionError) Unwrap() error {
    return e.Err
}

// 在事务边界使用
func ExecuteTransaction(ctx context.Context) error {
    err := doWork(ctx)
    if err != nil {
        return &TransactionError{Op: "ExecuteTransaction", Err: err}
    }
    return nil
}

2.4 Python 错误处理范式

Python 采用异常捕获机制，通过 try/except/finally 控制错误流。在异步与分布式场景中，异常处理与上下文管理器的结合是保证事务边界完整性的关键。

2.4.1 核心模式：异常即控制流

# Python 标准异常处理模式
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer(__name__)

def process_order(order_id: str) -> dict:
    with tracer.start_as_current_span("ProcessOrder") as span:
        try:
            # 步骤 1：校验订单
            validate_order(order_id)

            # 步骤 2：扣减库存
            deduct_inventory(order_id)

            span.set_status(Status(StatusCode.OK))
            return {"status": "completed"}

        except ValidationError as e:
            span.record_exception(e)
            span.set_status(Status(StatusCode.ERROR, "订单校验失败"))
            # 事务边界：无需回滚，直接返回
            raise

        except InventoryError as e:
            span.record_exception(e)
            span.set_status(Status(StatusCode.ERROR, "库存扣减失败"))
            # 事务边界：需要触发补偿
            compensate_order(order_id)
            raise

        except Exception as e:
            span.record_exception(e)
            span.set_status(Status(StatusCode.ERROR, "未知错误"))
            # 事务边界：全局回滚
            rollback_order(order_id)
            raise

2.4.2 上下文管理器与事务边界

Python 的 contextmanager 和 contextlib 可以优雅地封装事务边界，确保异常发生时资源正确释放，同时将错误上下文注入到 OpenTelemetry Span 中。

from contextlib import contextmanager
from opentelemetry import trace

@contextmanager
def transaction_span(name: str):
    """事务边界上下文管理器，自动处理 Span 状态与异常记录"""
    tracer = trace.get_tracer(__name__)
    with tracer.start_as_current_span(name) as span:
        try:
            yield span
            span.set_status(Status(StatusCode.OK))
        except Exception as e:
            span.record_exception(e)
            span.set_status(Status(StatusCode.ERROR, str(e)))
            # 事务边界：在此处执行回滚逻辑
            raise

# 使用示例
def transfer_funds(from_acct: str, to_acct: str, amount: float):
    with transaction_span("TransferFunds") as span:
        span.set_attribute("amount", amount)
        debit(from_acct, amount)
        credit(to_acct, amount)

2.5 Go 与 Python 错误处理范式对比

维度	Go	Python
核心机制	多返回值 + 显式错误检查	异常抛出 + try/except 捕获
错误传播	逐层返回，通过 `%w` 包装	自动沿调用栈冒泡，可被任意层捕获
事务边界控制	依赖 `defer` + 手动回滚	依赖 `finally` 或上下文管理器
OpenTelemetry 集成	`span.RecordError(err)` + `SetStatus`	`span.record_exception(e)` + `set_status`
性能开销	低（无异常栈展开）	中（异常创建有栈开销）
适用场景	高并发微服务、系统编程	快速原型、数据管道、胶水代码

2.6 错误处理与可观测性的结合点

在 OpenTelemetry 调用链中，错误处理不仅仅是代码健壮性的问题，更是可观测性数据质量的关键。以下是三个必须遵循的原则：

错误即事件：每个被捕获的错误都应记录为一个 SpanEvent，包含错误类型、堆栈、时间戳和业务上下文。
状态即契约：Span 的 Status 必须与事务的最终结果一致。部分失败（如降级）应使用 StatusCode.UNSET 并附加说明属性，而非简单标记为 ERROR。
传播即链路：错误在服务间传播时，必须通过 TraceContext 传递错误标识，确保调用链的根 Span 能够聚合所有相关错误事件。