3. 状态嵌入定义：将埋点状态标记注入请求与响应

3.1 原理概述

状态嵌入（State Embedding）是埋点体系的核心桥梁。它的职责是在网络请求离开应用之前，将调用链标识、会话标识、业务上下文等状态标记以 HTTP 头或请求体的形式注入到请求中；同样地，在响应返回时，从响应头中提取服务端下发的状态标记，恢复到线程上下文或缓存中。只有这样，整个分布式系统才能通过同一个 traceId 串联起前后端日志，通过 sessionId 追踪用户完整行为路径，通过业务标识区分不同流量来源。

状态嵌入必须具备三个特性：无侵入——业务代码无需手动传递状态参数；全链路传递——标记在请求生命周期内不丢失；可回溯——通过响应头或日志能还原调用链。

3.2 实现流程

1. 定义标记集合：明确需要注入的埋点状态标记（traceId、spanId、sessionId、appVersion、channel）。
2. 创建 RequestInterceptor：在 intercept() 方法中读取当前线程绑定的状态标记，通过 request.Builder().addHeader() 注入请求头。
3. 创建 ResponseInterceptor：从 response.header() 中读取服务端返回的标记（如服务端生成的 traceId），写回线程级缓存或全局上下文。
4. 注册到 OkHttpClient：将两个拦截器按顺序添加至 OkHttpClient.Builder。
5. 运行时验证：使用抓包工具或日志输出确认请求头中携带了目标状态标记。

3.3 代码实现

3.3.1 基础状态标记定义

public class TraceContext {
    private static final ThreadLocal<String> traceIdHolder = new ThreadLocal<>();
    private static final ThreadLocal<String> sessionIdHolder = new ThreadLocal<>();
    private static final ThreadLocal<String> bizTagHolder = new ThreadLocal<>();

    public static void setTraceId(String traceId) {
        traceIdHolder.set(traceId);
    }
    public static String getTraceId() {
        return traceIdHolder.get();
    }
    public static void setSessionId(String sessionId) {
        sessionIdHolder.set(sessionId);
    }
    public static String getSessionId() {
        return sessionIdHolder.get();
    }
    public static void setBizTag(String bizTag) {
        bizTagHolder.set(bizTag);
    }
    public static String getBizTag() {
        return bizTagHolder.get();
    }
    public static void clear() {
        traceIdHolder.remove();
        sessionIdHolder.remove();
        bizTagHolder.remove();
    }
}

3.3.2 请求拦截器——注入埋点状态

public class TraceRequestInterceptor implements Interceptor {
    private static final String HEADER_TRACE_ID = "X-Trace-Id";
    private static final String HEADER_SESSION_ID = "X-Session-Id";
    private static final String HEADER_BIZ_TAG = "X-Biz-Tag";

    @NonNull
    @Override
    public Response intercept(@NonNull Chain chain) throws IOException {
        Request originalRequest = chain.request();
        Request.Builder builder = originalRequest.newBuilder();

        // 注入 traceId
        String traceId = TraceContext.getTraceId();
        if (traceId != null && !traceId.isEmpty()) {
            builder.addHeader(HEADER_TRACE_ID, traceId);
        }

        // 注入 sessionId
        String sessionId = TraceContext.getSessionId();
        if (sessionId != null && !sessionId.isEmpty()) {
            builder.addHeader(HEADER_SESSION_ID, sessionId);
        }

        // 注入业务标识
        String bizTag = TraceContext.getBizTag();
        if (bizTag != null && !bizTag.isEmpty()) {
            builder.addHeader(HEADER_BIZ_TAG, bizTag);
        }

        Request newRequest = builder.build();
        return chain.proceed(newRequest);
    }
}

3.3.3 响应拦截器——提取并恢复状态

public class TraceResponseInterceptor implements Interceptor {
    private static final String HEADER_TRACE_ID = "X-Trace-Id";
    private static final String HEADER_SESSION_ID = "X-Session-Id";

    @NonNull
    @Override
    public Response intercept(@NonNull Chain chain) throws IOException {
        Response response = chain.proceed(chain.request());

        // 从响应头提取服务端下发的 traceId
        String serverTraceId = response.header(HEADER_TRACE_ID);
        if (serverTraceId != null && !serverTraceId.isEmpty()) {
            TraceContext.setTraceId(serverTraceId);
        }

        // 从响应头提取 sessionId（服务端可能延长 session 有效期并重新下发）
        String serverSessionId = response.header(HEADER_SESSION_ID);
        if (serverSessionId != null && !serverSessionId.isEmpty()) {
            TraceContext.setSessionId(serverSessionId);
        }

        return response;
    }
}

3.3.4 注册拦截器到 OkHttpClient

OkHttpClient client = new OkHttpClient.Builder()
        .addInterceptor(new TraceRequestInterceptor())   // 请求出发层
        .addInterceptor(new TraceResponseInterceptor())  // 响应到达层
        .build();

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("https://api.example.com/")
        .client(client)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

3.4 状态嵌入维度对比

3.5 调试验证

验证状态嵌入是否正确，推荐使用以下组合方式：

• 日志验证：在拦截器中添加日志输出，打印注入前后的 Header 列表。
• 抓包验证：使用 Charles / Wireshark 检查实际发出的 HTTP 请求头是否包含 X-Trace-Id 等标记。
• 响应头验证：在 RetrofitCallback.onResponse() 中通过 response.raw().header("X-Trace-Id") 确认服务端返回的 traceId 已被正确提取。

// 日志输出示例（需预先配置 OkHttp 日志拦截器）
D/OkHttp: --> GET /api/v1/user HTTP/1.1
D/OkHttp: X-Trace-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
D/OkHttp: X-Session-Id: session-20240315-abc123
D/OkHttp: X-Biz-Tag: user-profile
D/OkHttp: --> END GET

D/OkHttp: <-- 200 OK
D/OkHttp: X-Trace-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
D/OkHttp: X-Session-Id: session-20240315-abc123
D/OkHttp: <-- END HTTP

3.6 部署注意事项

3.7 常见错误与解决方案

3.8 性能与稳定性优化

• 状态缓存池化：用 ThreadLocal 替代 HashMap 全局缓存，减少单次请求的查找开销。
• 懒加载机制：仅在首次调用 intercept() 时初始化 TraceContext，避免启动阶段获取无用标记。
• 熔断保护：如果在 ResponseInterceptor 中连续 3 次提取响应头失败，自动降级，不再尝试恢复状态，防止连锁异常。
• 指标监控：统计每次状态注入/提取的耗时，若超过 2ms 则上报性能告警。