Kong避坑：为什么配置对了接口仍出错
Kong避坑真正难的部分，不是记住某个插件开关，而是理解请求在网关里经历了什么：先匹配路由，再处理插件，再连上游，最后把响应交回客户端。很多“配置明明没错”的事故，恰好是这条链路里两层规则互相打架造成的。
先抓住核心：Kong不是转发器，而是一条处理流水线
一条请求进入 Kong 后，会先依据 Host、Path、Method 等条件选中 Route，再关联到 Service，随后执行适用范围内的插件，最后发往上游。响应回来时，仍可能经过响应处理和日志输出。理解这个顺序，很多问题就不神秘了。
例如客户端拿到 401，不一定说明后端没启动，可能是网关认证插件先拦截了；拿到 404，也不一定是 Route 没匹配，可能是请求已转到上游、但路径被处理后不符合上游接口。排错第一问永远该是：错误由哪一层生成？
坑一：把Route匹配和上游路径拼接混为一谈
Route 负责“哪种请求进来”，Service 负责“转到哪里”，路径处理决定“上游最终收到什么”。这三件事写在一起时很容易眼花。特别是给旧服务加 /gateway、/v1 这类前缀时，一个 strip_path 或 path 配置的差异，就能让上游收到完全不同的 URL。
别用肉眼判断。为每个关键接口记录一张映射表：客户端请求 URL、匹配 Route、Service 地址、上游实际收到的 path。用 echo 类测试上游先验证，再接真实服务。这个笨办法很有效，能提前消灭大多数迁移期 404。
坑二：忽略插件作用域，导致策略叠加得出乎意料
Kong 的插件可以挂在全局、Service、Route、Consumer 等不同层级。好处是灵活，副作用是同一种能力可能被多层策略影响。你以为给某条 Route 设置了较宽松的限流，结果 Consumer 或全局策略仍在限制；你以为 CORS 开了，实际 OPTIONS 请求被认证挡住。
治理规则要有层级约定。比如全局只放基础安全头和统一日志，Route 放接口差异，Consumer 放调用方配额。每次新增插件都标注作用域和目的，并在配置评审里检查是否与已有策略重复。网关配置不是“堆积木”，重叠越多越难预测。
坑三：把超时、重试当成越大越安全
上游慢时，把 read timeout 从 30 秒改成 5 分钟，看上去减少了报错，实际上可能把 Kong 的连接和工作资源长期占住。流量一高，排队会让原本正常的请求也变慢，最后形成级联故障。
重试也有同样问题。对查询类、幂等请求，有限重试可能有帮助；对创建订单、扣款、发送通知这类非幂等动作，盲目重试可能制造重复副作用。真正的 Kong避坑原则是：超时要基于业务 SLA 设置，重试要基于幂等性设计，而不是基于“怕报错”。
坑四：只监控网关状态，却不观察请求质量
Kong 容器存活、CPU 不高，不代表用户体验正常。网关至少要能看到请求量、状态码分布、响应延迟分位数、上游错误、认证失败和限流命中。否则某个调用方突然刷爆接口时，你只能看到业务服务在报警，却不知道入口发生了什么。
日志里尤其要注意请求 ID。让请求在客户端、Kong、上游服务之间带着同一个关联标识，排一次 502 时能省掉大量时间。记录日志也要脱敏：Authorization、Cookie、API Key、身份证号这类字段不能原样扔进集中日志平台。
收尾：把Kong当成产品边界来维护
Kong避坑的终点不是写出一份永不改动的 YAML，而是建立可验证的变更习惯：配置进版本库、变更有评审、路由有回归测试、发布能回滚、异常能定位。接口网关处在最前面，一条小规则能影响整片服务，随手改最危险。
当你能清楚回答“请求匹配了谁、插件在哪层执行、上游到底收到什么、失败由谁返回”，Kong 就从玄学配置工具变成了可控的基础设施。别急着追求花哨功能，先把这四句话练熟，已经超过不少线上环境的治理水平。
常见问题
Kong配置了路由却一直404，问题在哪？
先区分 404 来自 Kong 还是上游。检查 Host、Path、Method 是否满足 Route；若已转发，再核对路径处理规则和上游实际收到的 URL。用回显服务验证路径映射最快。
Kong认证插件导致OPTIONS失败怎么办？
浏览器预检请求通常是 OPTIONS，需要确认 CORS 与认证策略的执行关系。为预检请求设计明确放行规则，并用真实浏览器请求验证，不要只用普通 GET 测试。
Kong超时应该设置多少秒？
没有统一数字。应根据接口 SLA、上游处理时间、客户端等待时间和容量计算设置连接、写入、读取超时；慢任务更适合异步化，而不是无限拉长同步请求。