1. 课程导论：为什么 gRPC 需要结构化日志、事务边界与错误处理？

1.1 微服务通信的“黑盒”困境

在单体应用时代，调试一个请求的完整路径相对简单：日志文件按时间顺序排列，错误堆栈清晰，事务边界由数据库连接管理。然而，当应用拆分为数十甚至上百个微服务，服务间通过 gRPC 进行高频、低延迟的远程调用时，传统的日志与错误处理方式迅速暴露出致命缺陷：

• 日志碎片化：每个服务独立输出日志，缺乏全局请求 ID，无法将一次跨 5 个服务的调用链串联起来。
• 错误信息丢失：gRPC 默认的 status.Code 和 status.Message 过于简略，无法传递业务上下文、堆栈跟踪或重试策略。
• 事务边界模糊：分布式事务（Saga、TCC）在 gRPC 调用链中缺乏明确的开始、提交/回滚标记，导致数据一致性难以追溯。

1.2 为什么选择 gRPC？协议层的能力与缺口

gRPC 基于 HTTP/2 和 Protobuf，天然具备高性能、强类型接口和多语言支持。但协议本身并未内置结构化日志和分布式事务边界标记。下表对比了 gRPC 原生能力与生产环境实际需求的差距：

1.3 结构化日志：从字符串到可查询的事件

结构化日志将每一行日志从纯文本转变为键值对集合。在 gRPC 场景下，一个典型的结构化日志条目应包含：

• 固定字段：时间戳、日志级别、服务名、节点 ID。
• 请求上下文：trace_id、span_id、rpc_method、peer_address。
• 业务载荷：order_id、user_id、amount（由业务层注入）。
• 性能指标：latency_ms、request_size、response_size。

这种格式使得日志可以直接被 Elasticsearch、Loki 等系统索引，支持 trace_id = "abc123" AND latency_ms > 500 这样的精确查询，而非依赖 grep 正则。

1.4 事务边界：在 gRPC 调用链中标记“开始”与“结束”

分布式事务的难点不在于“如何实现”，而在于“如何观测”。事务边界标记的核心作用包括：

1. 明确事务生命周期：在 gRPC 元数据中传递 transaction_id，并在日志中输出 tx_begin、tx_commit、tx_rollback 事件。
2. 关联跨服务操作：通过 transaction_id 将服务 A 的“扣减库存”与服务 B 的“创建订单”关联到同一个事务上下文。
3. 支持补偿审计：当事务失败时，根据边界日志快速定位需要执行补偿操作的服务和步骤。

1.5 错误处理：超越 gRPC 状态码

gRPC 定义了 16 个标准状态码（如 INVALID_ARGUMENT、UNAVAILABLE），但在复杂业务中远远不够。一个健壮的错误处理体系应包含：

通过 gRPC 的 google.rpc.Status 原型或自定义 ErrorDetails 消息，可以将上述信息打包到响应中，而客户端拦截器可以自动解析并记录结构化错误日志。

1.6 整体架构与课程目标

本课程将围绕一个核心架构展开：在 gRPC 客户端和服务端各部署一层拦截器（Interceptor），统一处理日志、事务边界和错误信息的注入、提取与记录。整体架构如下图所示：

课程将按以下路径逐步深入：

1. 基础篇：搭建 gRPC 项目，实现客户端/服务端拦截器骨架。
2. 结构化日志篇：集成 zap/structlog，在拦截器中注入 trace_id 并输出 JSON 日志。
3. 事务边界篇：在元数据中传递 transaction_id，在日志中输出事务生命周期事件。
4. 错误处理篇：自定义错误模型，实现错误码映射、堆栈捕获与重试策略。
5. 综合实战篇：构建一个包含订单、库存、支付的分布式 Saga 示例，完整演示三者的协同。