API中转站常见问题汇总：超时、转发失败怎么排查

API中转站（API网关）常见的“超时”与“转发失败”问题，通常由网络、配置、服务状态或网关中间件本身引起。排查时建议遵循“由外到内、由网络到代码”的递进逻辑，具体排查路径如下：

一、 转发失败（如 404、502）排查

1. 路由配置不匹配（常见 404）

• 排查点：检查网关（如 Ocelot）的 UpstreamPathTemplate 与客户端实际请求路径是否完全匹配（注意大小写、前导斜杠、版本前缀是否遗漏）。
• 排查点：检查 DownstreamPathTemplate 与下游服务（微服务）的实际接口路径是否完全一致（包括前导斜杠和路由特性）。
• 排查点：检查是否存在路由冲突（如多个路由配置了相同的上游路径，仅第一个生效，后续被忽略）。

2. 下游服务不可达（常见 502）

• 排查点：检查 DownstreamHost 和 DownstreamPort 配置是否正确（注意：Docker 容器部署时，Host 应使用容器内服务名而非 localhost；IIS 托管时注意子应用路径影响）。
• 排查点：检查下游服务是否正常运行、是否监听了正确的 IP（如是否只监听了 127.0.0.1 导致外部无法访问）和端口。
• 排查点：检查网络连通性，通过 telnet host port 或 curl 直接访问下游服务，确认是否存在防火墙拦截或 DNS 解析失败。

3. 协议或证书问题（常见 502）

• 排查点：检查 DownstreamScheme 配置（HTTP/HTTPS）是否与下游服务实际协议一致。若为 HTTPS，需确认下游服务的证书信任链是否完整。

二、 超时（如 504）排查

1. 下游服务响应慢或阻塞

• 排查点：直接通过 curl 或 Postman 测试下游服务接口的响应时间，确认是否因下游服务负载过高、代码逻辑阻塞或数据库慢查询导致响应超时。
• 排查点：检查下游服务是否触发了网关的限流（RateLimit）或熔断机制，导致请求被提前拦截。

2. 网络延迟或网关配置超时

• 排查点：检查网关的超时（Timeout）或 QoS 配置是否设置过短，无法适应下游服务的实际响应时间，需根据实际网络情况调整配置。

三、 通用排查与定位方法

1. 查看网关日志

• 开启网关的详细日志（如 Ocelot 的日志输出），查看日志中记录的“原始请求路径”、“匹配的路由名称”、“构造的下游请求 URL”以及“HTTP 调用结果状态码”，这是定位转发失败原因最直接的依据。

2. 分段测试与抓包

• 分段测试：先直接访问下游服务验证其可用性，再访问网关，通过对比结果缩小问题范围。
• 抓包分析：使用 Fiddler 或 Wireshark 抓包，分析请求在网关与下游服务之间的实际流向，排查网络层异常。

3. 服务发现与负载均衡排查（适用于微服务架构）

• 若网关集成了 Consul、Eureka 等服务发现，需检查服务健康检查是否失败导致实例被剔除，或检查负载均衡策略是否将请求转发到了不可用的节点。