Vibe Coding 请求路径追踪：从入口一路核对到响应与副作用

“这个接口在哪实现”通常能得到一个路由文件，却回答不了更重要的问题：请求在到达它之前是否经过代理重写和认证，参数在哪一层被规范化，事务之外是否还发布事件，错误最后被谁转换，响应返回后有没有异步副作用。AI 若只看到 handler，很容易在错误层修复症状，或增加一条绕过原有策略的新路径。

用 AI 快速熟悉陌生代码库把调用链追踪作为 onboarding 手段；这里进一步把单条请求做成可审计的“路径表”，要求每个节点有静态或运行时证据，并把分支、重试和异步边明确画出。

给路径一个可复现入口

先固定请求形态：协议、方法、主机、规范化后的路径、关键请求头类别、身份状态和输入夹具。不要把真实 cookie、token 或个人数据放入上下文。OpenAPI 可以帮助确认公开契约，但规范存在不代表运行实现完全一致；它只是入口证据之一。

scenario: update-own-profile
request: PATCH /api/profile
identity: authenticated-user fixture
body: {displayName: "New Name"}
expectedTerminal:
  status: 200
  durableEffect: profile row changed once
negativeTwin:
  identity: expired-session
  status: 401

同时准备一个负向双胞胎，如未登录、资源不属于当前用户或 schema 无效。正向请求往往只走顺畅分支，负向样例更容易暴露鉴权和错误映射到底位于哪层。

从外到内建立路径表

按实际执行顺序寻找边，而不是按目录顺序读文件：外部代理或平台规则、框架 rewrite、中间件、路由匹配、handler、输入解码、身份与授权、业务服务、repository 或外部客户端、事务提交、缓存和事件、响应序列化。每一行记录“控制权从谁交给谁、数据发生什么变换、证据在哪里”。

01 proxy rule -> /api/profile       config, static
02 auth middleware -> request.user  middleware.ts, static + test
03 route handler -> updateProfile   route.ts, static
04 service -> database transaction  profile-service.ts, static
05 commit -> audit event             runtime trace required
06 error mapper -> HTTP response     error-handler.ts, static + test

不要把函数名相似当调用关系。直接调用可由符号引用证明，依赖注入要追注册表，事件消费要追 topic 与订阅，字符串加载要追配置。动态边只能标为“可能”时，不要用肯定语气填图。仓库依赖图驱动的改动规划适合进一步计算跨模块影响闭包。

控制流与数据流分开画

控制流说明下一步执行谁，数据流说明关键字段怎样变化。请求 ID、用户身份、租户、权限结论、幂等键和事务句柄经常不是同一参数显式传递，而是放进 context、header 或全局容器。只画调用箭头会漏掉串租、丢取消和重复写入风险。

为关键字段记录来源、校验点、规范化步骤和最终 sink。例如 userId 是从已验证 session 提取，还是直接相信 body；returnTo 在代理、handler 还是前端规范化；数据库写入与审计事件是否共享提交边界。任何未找到来源的高信任字段都应阻止 AI 直接修改业务逻辑。

用运行时 Trace 验证动态边

静态搜索能找到可能路径，不能证明某个请求实际走过。W3C Trace Context 定义了跨进程传播追踪上下文的标准头；OpenTelemetry Trace 规范描述 span、父子关系和 link 等模型。若项目已有 tracing，使用脱敏测试请求采集一条 trace，对照静态路径表；不要为了本次阅读擅自把敏感 payload 加入 span。

运行时证据还要注意缺口。没有 span 可能是未执行，也可能是未埋点；异步队列通常通过 link 而非严格父子关系连接；采样后的单条成功 trace 不能证明所有分支。把静态可达但运行未见的边标为 not observed，把 trace 出现但源码表缺失的边标为 unmapped，继续查注册与基础设施配置。

编程 Agent 调试复现证据包可以保存失败请求的脱敏夹具、代码基线和判定器。路径追踪应复用这样的可重放现场，而不是在生产流量上随意试探。

同时记录终态与副作用

HTTP 状态不是唯一终点。列出数据库写入、缓存失效、消息发布、文件操作、第三方调用和审计日志，注明发生在响应前后、是否在事务中、失败是否重试。一个 200 可能在事件发布前就返回；一个超时也可能已经完成写入。修改重试或错误处理前，必须知道副作用的幂等边界。

路径表还应覆盖错误终态：谁捕获异常，怎样映射状态码，是否保留因果信息，连接取消是否传播到下游。观测策略可参考LLM Agent 失败的 Tail Sampling中的失败保留思想，但本任务的核心仍是代码与请求夹具对得上。

用差异问题结束追踪

追踪完成后，不要只给一张漂亮流程图。让 AI 回答：规范与实现哪里不同，静态与运行证据哪里冲突，哪些边没有观测，哪项副作用不在预期事务内，拟议改动会触达哪些节点。每个答案引用文件、符号、配置或 trace span。

当入口、主要分支、关键数据、终态和副作用都有证据，才把路径表交给改动规划。若某段仍靠“通常框架会这样做”连接，就继续调查或把它列为风险；不要让 Vibe Coding 的顺畅叙述替代真实执行路径。

延伸阅读

• 用 AI 快速熟悉陌生代码库
• 仓库依赖图驱动的改动规划
• 编程 Agent 调试复现证据包
• LLM Agent 失败的 Tail Sampling