故障排除 (Troubleshooting)

本节涵盖了在使用 Spring Cloud Gateway 时可能出现的常见问题及调试方法。

1. 日志级别 (Log Levels)

当遇到路由不匹配、过滤器不执行或请求超时等问题时，将以下包的日志级别设置为 DEBUG 或 TRACE 通常可以提供非常有价值的线索：

• org.springframework.cloud.gateway：网关核心逻辑（断言匹配、过滤器链执行）。
• org.springframework.http.server.reactive：响应式服务器底层逻辑。
• org.springframework.web.reactive：WebFlux 相关逻辑。
• org.springframework.boot.autoconfigure.web：Spring Boot Web 自动配置。
• reactor.netty：底层 Netty 网络通信。
• redisratelimiter：Redis 限流器逻辑。

2. Wiretap (流量窃听)

Reactor Netty 的 HttpClient 和 HttpServer 可以开启 Wiretap 功能。 配合将 reactor.netty 的日志级别设置为 DEBUG 或 TRACE，它可以记录通过网络发送和接收的详细信息，包括 HTTP 头部 (Headers) 和 请求/响应体 (Bodies)。

要启用 Wiretap，请分别针对 HttpServer 或 HttpClient 设置以下属性：

• spring.cloud.gateway.httpserver.wiretap=true
• spring.cloud.gateway.httpclient.wiretap=true

---

补充教学 —— 网关调试“三部曲”

在开发或排查网关问题时，建议遵循以下流程，由浅入深：

第一步：检查 Actuator 端点

在看日志之前，先通过接口确认网关的“大脑”是否如你预期：

• 访问 /actuator/gateway/routes：确认路由 ID 是否重复、断言（Predicate）条件是否正确、URI 是否写错。
• 如果是动态路由，检查是否有新的配置没刷新。

第二步：配置关键日志 (Log Levels)

在 application.yml 中添加如下配置，这是排查 90% 问题的绝招：

logging:
  level:
    org.springframework.cloud.gateway: TRACE
    reactor.netty: DEBUG

为什么是这两个？

• org.springframework.cloud.gateway: TRACE 会告诉你请求匹配了哪个路由、被哪个断言拦住了、依次执行了哪些过滤器。
• reactor.netty: DEBUG 会显示连接建立的过程（DNS 解析、握手、连接池借出）。

第三步：开启 Wiretap（终极武器）

如果你怀疑请求参数在转发过程中被篡改了，或者下游返回的数据不对，但又看不到具体的 HTTP 报文，那就开启 Wiretap：

spring:
  cloud:
    gateway:
      httpclient:
        wiretap: true

⚠️ 警告：生产环境慎用！

• 性能开销：记录所有的请求体和响应体会消耗大量的 CPU 和 I/O，可能导致网关性能骤降。
• 隐私风险：密码、Token 等敏感信息会全部明文打印在日志中。
• 日志爆炸：如果是大文件上传，日志文件会瞬间撑爆硬盘。

总结：先看配置，再看路径日志，最后再抓包（Wiretap）。