用 URL 路径段为 API 版本化

将 v1 和 v2 挂载在不同路径前缀，使 v2 的破坏性变更不影响仍在生产的 v1 客户端。

隔离故障

先测量问题。将 v1 和 v2 挂载在不同路径前缀，使 v2 的破坏性变更不影响仍在生产的 v1 客户端。最常见的错误是未确认门禁能捕获你关心的问题就先加上。在接入 CI 之前，先对当前代码库运行 app.use(‘/v1’, v1Router); app.use(‘/v2’, v2Router); 并检查输出。

app.use('/v1', v1Router); app.use('/v2', v2Router);

验证优雅降级

门禁就位后，让失败可操作。app.use(‘/v1’, v1Router); app.use(‘/v2’, v2Router); 失败时应指向具体文件和行号，而非泛泛的错误。在锁文件中固定工具版本，防止上游发布悄悄改变行为。每次拉取请求都应像审查测试结果一样审查门禁输出。

验证

在本地运行 app.use(‘/v1’, v1Router); app.use(‘/v2’, v2Router); 确认通过后推送。CI 中门禁应阻断不合规的拉取请求。若人为绕过门禁直接推送，应在下次定期扫描中被发现。

注意事项

The gate only runs on events that trigger the workflow; locally pushed commits bypass it.
Configuration drift is possible if someone edits settings outside version control.