Spring Cloud Gateway 全景功能地图（架构师落地版）
| 功能域 | 功能点 | 优先级 | 星级 （必做程度） | 典型使用场景 | 落地做法与配置关键 | 避坑红线 |
|---|---|---|---|---|---|---|
| 流量入口 | 动态路由 | P0 | ⭐⭐⭐⭐⭐ 5/5 | 微服务上下线自动感知；按客户端类型分流（App vs Web） | 对接 Nacos/Eureka，禁用 IP 硬编码。 配置示例： spring.cloud.gateway.routes[0].uri=lb://user-service | 严禁手动维护 IP 列表，重启网关才能改路由是架构失职 |
| 负载均衡 | P0 | ⭐⭐⭐⭐⭐ 5/5 | 后端多实例流量分配；故障实例自动剔除 | 集成 Spring Cloud LoadBalancer，开启健康检查。 重试策略：GET 可重试 1 次，POST/PUT 禁止自动重试 | 默认的轮询不一定最优，对长尾请求用 ResponseTime 加权算法 | |
| 安全防护 | 统一鉴权 | P0 | ⭐⭐⭐⭐⭐ 5/5 | 所有请求统一验 JWT，避免每个服务重复实现 | 只验签和过期时间（exp），不解密业务敏感字段。 验签失败直接 401，不往后传 | 严禁在网关层查数据库/Redis 做权限校验，这会让网关成为瓶颈 |
| HTTPS 卸载 | P1 | ⭐⭐⭐⭐ 4/5 | 统一证书管理，后端专注业务；支持 HTTP/2 | 网关层配置 SSL 证书，内部转 HTTP。 证书到期只换网关配置，不动 100 个微服务 | 注意证书链完整性，部分安卓低版本对证书链要求严格 | |
| 敏感数据脱敏 | P2 | ⭐⭐⭐ 3/5 | 日志审计要求；防止手机号/身份证泄漏 | 自定义 Filter，用正则匹配 \d{18} 等，替换为 ****。只针对 DEBUG/INFO 级别日志 | 脱敏规则别太激进，别把正常 JSON 结构破坏导致下游解析失败 | |
| 稳定性治理 | 限流熔断 | P0 | ⭐⭐⭐⭐⭐ 5/5 | 大促防刷；下游服务故障时自保 | 限流：单用户 10次/秒（本地），全局限流用 Redis Lua 脚本。 熔断：5 秒内错误率>50% 触发，30 秒后半开试探 | 熔断后要返回 503 + 友好提示，别返回 500 让前端以为业务错了 |
| 超时控制 | P0 | ⭐⭐⭐⭐⭐ 5/5 | 防止慢请求拖垮连接池；避免级联等待 | 全局设置 response-timeout: 5s，针对特定接口可单独配置（如文件上传 60s） | 严禁不设置超时，默认无限等待会导致连接池耗尽，全站宕机 | |
| 重试机制 | P1 | ⭐⭐⭐⭐ 4/5 | 网络抖动时的自动容错 | 仅对幂等的 GET/HEAD 开启，retry-on: IOException。最多重试 1 次，且避开上次失败的实例 | POST 下单接口如果重试，可能导致重复扣款，这是生产事故 | |
| 发布运维 | 灰度发布 | P1 | ⭐⭐⭐⭐ 4/5 | 新版本先给内部员工试用；金丝雀放量 | Header 匹配：X-User-Id=10086 或 X-Version=v2 走新集群。配合前端动态打标 | 灰度标识要全链路传递（通过 Header 透传），下游服务也要能识别 |
| 配置热更新 | P1 | ⭐⭐⭐⭐ 4/5 | 调整限流阈值、新增路由不用重启 | 对接 Nacos/Apollo，监听配置变更事件。 路由表存在内存 + 本地文件备份 | 热更新失败要有兜底（保留上次有效配置），别更新失败就清空路由表 | |
| 健康检查 | P1 | ⭐⭐⭐⭐ 4/5 | K8s 探针判断容器存活；自动扩缩容依据 | 暴露 /actuator/health，包含 Redis/注册中心连接状态。非 UP 状态让 K8s 自动重启 | 健康检查接口本身要做限流，别被刷爆了误判为不健康 | |
| 可观测性 | 日志追踪 | P1 | ⭐⭐⭐⭐ 4/5 | 线上故障定位；性能瓶颈分析 | 每个请求生成 TraceId，写入 MDC。 接入 SkyWalking/Pinpoint，采样率 10%（高并发下全量采集会死） | 日志别打印 Request/Response Body，量太大且易泄漏隐私 |
| 指标监控 | P1 | ⭐⭐⭐⭐ 4/5 | 实时 QPS/延迟/错误率看板；告警 | 暴露 Prometheus 端点，监控 gateway_requests_seconds 等指标。告警规则：P99 延迟>1s 或错误率>1% | 监控数据也要限流，别监控本身把网关拖慢 | |
| 协议适配 | 协议转换 | P1 | ⭐⭐⭐⭐ 4/5 | 前端 HTTP 调后端 gRPC；WebSocket 长连接 | HTTP JSON 转 gRPC 用 GrpcGatewayFilter。WebSocket 连接状态存 Redis，支持网关水平扩展 | WebSocket 要注意心跳检测，假连接过多会占满文件描述符 |
| 请求重写 | P2 | ⭐⭐⭐ 3/5 | 老接口兼容（/v1 映射到 /v2）；统一加请求头 | RewritePath Filter：/api/(?<segment>.*) → /v2/$\{segment}。统一加 X-Real-IP 透传真实 IP | 重写规则别太复杂，正则太多会影响网关吞吐性能 | |
| 进阶能力 | 边缘计算 | P2 | ⭐⭐⭐ 3/5 | IP 转城市；简单数据聚合（BFF） | 轻量级逻辑：查本地 IP 库返回地域信息。 缓存热点数据（Caffeine，TTL 30s） | 严禁在网关做事务操作（如下单、扣款），这是架构越界 |
| 多租户隔离 | P2 | ⭐⭐⭐ 3/5 | 多部门共享网关；SaaS 多客户隔离 | 按 Header X-Tenant-Id 路由到不同集群。线程池隔离：重要业务独立 EventLoop | 租户标识要做校验，防止伪造 Header 访问其他租户数据 | |
| 请求镜像 | P2 | ⭐⭐ 2/5 | 复制线上流量到测试环境，做真实压力测试 | RequestRateLimiter 旁路复制，只复制 GET 请求。镜像请求异步发送，不影响主链路延迟 | 镜像流量别调用真实支付/短信接口，否则可能重复扣费或骚扰用户 |
⭐ 星级含义速查（打印贴工位版）
| 星级 | 含义 | 不做后果 | 落地时间 |
|---|---|---|---|
| ⭐⭐⭐⭐⭐ P0 | 生死线 架构底线 | 系统随时雪崩、数据泄漏、全面宕机，属于P0 事故 | 上线前必须搞定 |
| ⭐⭐⭐⭐ P1 | 生产力 工程刚需 | 无法灰度、排查困难、运维痛苦，团队天天加班救火 | 1 个月内补齐 |
| ⭐⭐⭐ P2 | 竞争力 体验优化 | 功能可用但体验差，大促可能扛不住，或无法满足合规 | 按需迭代 |
| ⭐⭐ 选修 | 加分项 特定场景 | 锦上添花，非核心能力，不做不影响主线业务 | 有空再说 |
一句话 checklist（⭐⭐⭐⭐⭐ 必做项）
✅ 路由用服务名(lb://)，别写死 IP
✅ 只验 JWT 签名，不查库验权
✅ POST 请求不重试，GET 可试 1 次
✅ 必须设超时，必须配熔断
✅ 日志采样打，别全量写磁盘
✅ 证书放网关，后端全走 HTTP
