一、方案设计：两层机制解决两个问题
在 Spring Cloud 微服务项目中落地标记透传，需要同时解决跨线程和跨服务两个问题，对应两套机制：跨线程：引入数据上下文（AppContext）对象，底层使用 TransmittableThreadLocal，确保压测标记在线程池复用场景下不丢失，并支持在任意位置随取随用。跨服务：利用 Sleuth 原生的 Span Baggage 机制，在网关 Filter 中将压测标记写入 Baggage，下游服务通过 Baggage 读取，无需修改业务代码。两者组合的完整流程：请求到达网关 → Filter 提取 Header 中的压测标记 → 写入 Span Baggage + 存入 AppContext → 下游服务通过 Baggage 或 AppContext 读取标记 → 区分压测流量与正常流量。—## 二、网关 Filter：标记注入的入口网关是整条链路的流量入口，所有压测标记的注入都在这里完成。实现GlobalFilter接口，在filter()方法中提取请求 Header 中的压测标记，写入 Span Baggage：java@Componentpublic class globalTagFilter implements GlobalFilter { @Autowired private Tracer tracer; @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { String dunshan = exchange.getRequest().getHeaders().getFirst("dunshan"); if (dunshan != null) { tracer.currentSpan().tag("dunshan", dunshan); // 写入 Span Baggage ServerHttpRequest request = exchange.getRequest().mutate() .header("dunshan", dunshan).build(); exchange = exchange.mutate().request(request).build(); } return chain.filter(exchange); }}````tracer.currentSpan().tag("dunshan", dunshan)` 将标记写入当前 Span 的 Tag，Sleuth 会自动将其随 Trace 传递到所有下游服务。同时通过 `mutate().header()` 保留 Header，确保下游服务也能通过 `HttpServletRequest` 直接读取。---## 三、Sleuth 配置：开启 Baggage 透传仅有 Filter 代码还不够，Sleuth 需要显式配置哪些 key 允许透传，否则自定义字段会被过滤掉：yamlspring: sleuth: sampler: probability: 1.0 rate: 10000 propagation: tag: whitelisted-keys: - dunshan # 允许该 key 作为 Tag 透传 enabled: true propagation-keys: - dunshan # 允许该 key 在服务间传播 zipkin: base-url: http://127.0.0.1:9411````propagation-keys是关键配置，声明了哪些自定义字段需要随 Trace 在服务间传播。whitelisted-keys控制哪些字段会作为 Tag 显示在 Zipkin UI 中。**所有服务的配置文件都需要加上这两项**，否则中间某个服务会截断标记传递。---## 四、下游服务：两种方式读取标记下游服务（如订单服务）可以用两种方式读取压测标记，可根据场景灵活选择：```java// 方式一：通过 Sleuth Baggage 读取BaggageField dunshan = BaggageField.getByName("dunshan");String tagInfo = dunshan.getValue();// 方式二：通过 HttpServletRequest Header 读取String dunshan = request.getHeader("dunshan");```Baggage 方式不依赖 HTTP 协议，适合 RPC 调用场景；Header 方式更直接，适合纯 HTTP 链路。实际项目中两种方式可以并存，互为兜底。---## 五、数据上下文（AppContext）：跨线程透传的核心Sleuth Baggage 解决了跨服务传递，但在服务内部的异步场景（线程池、MQ 消费者）中，Baggage 无法自动传递。这时需要引入 AppContext——一个基于 TTL 的数据上下文对象：```javapublic class AppContext implements Serializable { private static final TransmittableThreadLocal<AppContext> contextdunshan = new TransmittableThreadLocal<>(); private String flag; public static AppContext getContext() { return contextdunshan.get(); } public static void setContext(AppContext context) { contextdunshan.set(context); } public static void removeContext() { contextdunshan.remove(); } public String getFlag() { return flag; } public void setFlag(String flag) { this.flag = flag; }}```在 Filter 或 Controller 中获取到 Baggage 标记后，立即存入 AppContext：```javaAppContext ctx = new AppContext();ctx.setFlag(tagInfo);AppContext.setContext(ctx);```之后在任意位置（包括线程池中的异步任务）都可以通过AppContext.getContext().getFlag()读取标记，TTL 保证了线程池复用场景下的正确传递。---## 六、验证：Zipkin 中确认标记透传改造完成后，通过 JMeter 在 HTTP Header Manager 中添加压测标记（如dunshan: 7DGroup），执行请求后打开 Zipkin（http://127.0.0.1:9411/zipkin）查看链路详情。验证点有两个：一是每个服务的 Span 详情中都应显示自定义 Tagdunshan=7DGroup，说明标记随 Trace 完整传递；二是链路图中服务调用关系完整（网关 → 会员 → 购物车 → 订单），无断链。如果某个服务的 Span 中缺少 Tag，通常是该服务的propagation-keys配置缺失，补充配置后重启即可。---## 七、真实系统改造的最小改动原则在 demo 验证通过后，对真实 mall 项目的改造遵循最小改动原则：网关服务（mall-gateway）需要修改代码：在已有的AuthGlobalFilter中添加 Tag 注入逻辑，并更新application.yml配置。其他业务服务（mall-member、mall-auth 等）**只需修改配置文件**，添加propagation-keys和whitelisted-keys两项配置，无需改动业务代码。这是 Sleuth Baggage 方案相比 Header 方案的核心优势——标记传递对业务代码完全透明。需要使用 AppContext 读取标记的服务（如需要区分压测流量写入影子库的服务），在 Filter 或拦截器中完成 Baggage → AppContext 的转存，业务层统一通过AppContext.getContext().getFlag()` 读取，与具体传输机制解耦。
