ThinkPHP链路染色需在入口中间件统一生成trace_id并透传至所有下游调用：HTTP需手动注入X-Trace-ID头，Swoole下必须用Co::getContext()存储以防协程丢失，测试流量需配合X-Env等标识实现隔离。
ThinkPHP 请求上下文如何透传 trace_id
接口调用链路染色，本质是让一次请求从入口到所有下游调用（HTTP、RPC、消息）都携带同一个 trace_id。ThinkPHP 本身不内置分布式追踪能力，得靠手动注入和透传。
关键不是“生成 ID”，而是“在哪生成、在哪塞进去、在哪取出来”。推荐在应用入口统一生成并绑定到请求上下文：
- 在
app/middleware/TraceMiddleware.php中拦截请求，用uniqid('t_')或bin2hex(random_bytes(8))生成trace_id - 通过
$request->withHeader('X-Trace-ID', $trace_id)写入当前 Request 对象（仅对当前请求有效） - 更稳妥的是写进
think\Container或使用think\facade\Cache的 request scope（但注意多线程/协程下不安全） - 若用 Swoole，必须用
Co::getContext()存，否则子协程会丢失
HTTP 客户端调用时怎么自动带上 X-Trace-ID
ThinkPHP 自带的 think\Http（即 think\facade\Http）不自动继承请求头，下游服务收不到染色信息，链路就断了。
必须显式透传，且要注意：不是所有 HTTP 调用都走同一个客户端实例，每次 new 或 facade 调用都是新对象。
立即学习“PHP免费学习笔记（深入）”；
- 在发起远程调用前，从当前请求中读
$request->header('x-trace-id')，再手动加进 headers - 示例：
$traceId = $request->header('x-trace-id', uniqid('t_')); $result = Http::withHeaders(['X-Trace-ID' => $traceId])->post('https://api.example.com/user'); - 如果项目里大量用
curl或file_get_contents，得统一封装一层，否则漏掉一处，整条链就染不上 - 注意别把
X-Trace-ID错写成X-TraceId或x_trace_id—— 大小写敏感，下游框架（如 Laravel/Spring）通常只认标准命名
测试流量怎么标记并隔离（非生产污染）
测试流量标记的核心是「识别 + 路由分流」，不是加个 header 就完事。染色只是第一步，后续还得让网关或业务层能识别并做隔离处理。
- 约定测试流量带
X-Env: test或X-Test-Flag: true，和X-Trace-ID一起发 - 在中间件里检查该 header，若存在则将
trace_id改为test_开头（如test_t_5f8a1b2c），方便日志筛选 - 数据库操作若需隔离，不能只靠连接池区分，得在 SQL 前缀或 schema 层做路由 —— ThinkPHP 的
db()->name('user')->suffix('_test')是临时方案，长期建议用多库配置 + 动态切换 - 缓存 key 必须包含环境标识，否则测试写入的
cache:user:123会覆盖生产数据；推荐统一用config('app.env') . ':user:123'
Swoole 下协程间 trace_id 为什么会丢失
这是最隐蔽也最容易翻车的点。ThinkPHP 默认运行在 FPM 模式下，变量全局可见；但 Swoole 协程共享内存，static 变量或 global 不跨协程，$_SERVER 也不可靠。
- 绝对不要用
static $traceId在中间件里存 ID —— 下一个协程进来就读不到 - 必须用
Co::getContext()获取当前协程上下文，并写入trace_id字段；所有子协程内都要主动 get - 异步任务（如
go(function () { ... })）里，需手动把主协程的 context 传进去，或在 go 前先$ctx = Co::getContext();，再go(function () use ($ctx) { Co::setContext($ctx); ... }) - Redis、MySQL 等客户端若做了协程封装，要确认它们是否自动继承当前协程 context —— 很多第三方包没做这层适配，得自己 patch
链路染色真正难的不是生成 ID，而是确保它在任意执行路径（同步/异步/子协程/子进程）里都不丢、不错、不混。尤其 Swoole 场景下，少一个 Co::setContext()，整条 trace 就断在某个 Redis 查询之后。
