📚 课程目录第1章分布式上下文传播概述

1. 分布式上下文传播：从概念到落地

1.1 什么是上下文？一个再简单不过的道理

上下文（Context），说白了就是“额外带过去的信息”。你发一个 HTTP 请求，除了参数和路径，还需要带上用户身份、请求来源、链路追踪 ID、安全令牌……这些零碎信息绑在一起，就是一次请求的上下文。

我刚开始写分布式系统时，总觉得“数据都传了，还差这点玩意儿？”后来线上出了个 bug：一个订单创建失败，日志东一块西一块，完全串不起来。折腾了两天才发现是某个下游服务没拿到 Trace ID。嗯，从那以后，我对上下文传播再也不敢掉以轻心了。

核心要点：上下文就是请求在多个服务间穿越时，"额外携带"的元数据集合。它不属于业务 payload，但决定了业务能正确执行、能被追踪、能被回滚。

1.2 为什么需要传播？三个典型困境

上下文传播之所以单独拿出来讲，是因为分布式环境天然存在三个麻烦：

信息截断 – 服务 A 调用 B，B 再调 C，A 传过去的 Trace ID 可能在 B 的线程模型里丢失了。
异步撕裂 – 消息队列、定时任务、回调函数……这些异步执行路径上，上下文经常“断片”。
回滚定位难 – 一旦失败，需要回溯“到底经过了哪些服务”“谁改了数据”，没上下文等于盲人摸象。

我曾经见过一个支付系统，因为 MQ 消费线程没继承父线程的上下文，导致补偿任务重复触发退款——用户都被退了两遍钱。这种坑，踩过一次你就忘不了。

1.3 上下文里一般都装什么？一个实例表格

字段	说明	典型值
`trace_id`	全局唯一追踪 ID	`a1b2c3d4-xxxx`
`span_id`	当前服务/步骤 ID	`span-0001`
`user_id`	发起用户	`u-10086`
`auth_`	鉴权凭据	`Bearer eyJxxx`
`app_version`	客户端版本	`2.3.1`
`source`	请求来源标识	`web\|app\|cron`

你想想看，如果这些字段在某次调用链路上中断，后面的服务将无法知道用户是谁、请求从哪来、该关联哪条日志。这就是传播失效的后果。

1.4 传播的三种主流方式

我习惯把上下文传播分为三个层次，每个层面对应的实现方式差别很大：

同步 RPC（HTTP/gRPC）
通过 Header / Metadata 传递，最简单。我通常用中间件统一注入，避免业务代码到处塞参数。
异步消息（Kafka / RabbitMQ / Redis Stream）
生产者需要主动把上下文写入消息头或消息体。消费者侧再解析出来重新放回执行环境。
异步线程（线程池 / 协程 / 回调）
这个最隐蔽。父线程的 ThreadLocal 或在 Go 里的 context.Context 不会自动传递到子线程。必须手动拷贝或使用框架提供的 Runnable 包装器。

⚠️ 我曾踩过的坑： 有一次线上告警，发现某个定时任务不停重试，原因竟然是线程池中的闲线程没有清理前一个请求的上下文，导致新的任务继承了错误的 Trace ID 和认证信息。后来我定了一条硬性规则：所有线程池任务必须在执行前重置并注入新上下文。

1.5 一个简单的代码示例（Go 风格）

假设我们有一个 HTTP 中间件，负责从请求里提取 Trace ID，并通过 Go 的 context.Context 向下传递：

func TraceMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        traceID := r.Header.Get("X-Trace-ID")
        if traceID == "" {
            traceID = uuid.New().String()
        }
        ctx := context.WithValue(r.Context(), "trace_id", traceID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

之后下游服务只要从 ctx.Value("trace_id") 取出。你可能会问，为什么不直接全局变量？原因很简单：一个进程同时处理多个请求时，全局变量会互相污染——我见过生产环境因为这个导致用户 A 的请求携带了用户 B 的。

1.6 应用场景：哪些地方离不开上下文传播？

我一共总结了 4 个最吃紧的领域，几乎每个分布式系统都绕不过：

场景	为什么依赖上下文传播
分布式链路追踪	没有 Trace ID 和 Span ID，日志就是散沙
用户认证与鉴权	/ Session 必须在服务间一直传递，直到存储层
一致性补偿 & 回滚	Saga / TCC 需要知道事务边界、步骤顺序和失败来源
灰度发布 & A/B 测试	通过上下文携带用户标签，路由到正确的版本

我记得一个做电商的朋友，他们的压测流量没带上灰度标签，结果灰度服务接入了大量正常用户的请求——差点把订单表搞乱。自那以后，他们把所有流量的上下文传播列进了架构评审的红线。

💡 我的一个小建议： 无论你用哪种语言，建议在项目初期就定义一个统一的上下文结构（比如 Protobuf 或 JSON Schema），然后编写中间层组件自动注入和自动提取。这样后期加字段、改字段都只动这一个地方，整个调用链自动生效。

1.7 知识图谱：上下文传播的全貌

下图把概念、传播方式、应用场景串了起来，方便脑中形成整体印象：

1.8 一个小总结（不废话）

分布式上下文传播，不是一个可以“以后再说”的特性。它是监控、排错、治理和韧性设计的基础设施。我个人习惯把上下文传播组件和 RPC 框架、消息 SDK 深度绑定，让业务代码零感知。这样一旦出现问题，只需要排查中间件层，而不是每个服务都改一遍。

为什么会有人忽视它？因为单机和单体时代根本不需要显式传播——全局变量或进程内 ThreadLocal 就够了。但一旦服务拆分，请求跨越进程、线程、队列，上下文就会变成“断了的线”。你不主动拉回来，它就永远断在那里。而你，就是那个追责的人。