1、完整、系统、可落地的企业级 Spring Cloud Gateway 网关层设计规范文档

原创已于 2025-10-07 21:56:34 修改 · 980 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#设计规范 #java #运维 #spring boot #spring cloud #gateway

于 2025-09-27 11:56:53 首次发布

Spring Cloud Gateway 专栏收录该内容

10 篇文章

订阅专栏

【投稿赢 iPhone 17】「我的第一个开源项目」故事征集：用代码换C位出道！ 10w+人浏览 1.6k人参与

以下是一份完整、系统、可落地的企业级 Spring Cloud Gateway 网关层设计规范文档，专为你的 urbane-commerce 电商微服务项目 量身定制。
本文档明确说明：
✅ 推荐在网关层做什么
❌ 不推荐或禁止在网关层做什么
🔍 判断标准与核心原则
📌 真实生产环境最佳实践

📜《urbane-commerce 微服务网关层设计规范》

版本：1.2 | 最后更新：2025年4月 | 适用架构：Spring Cloud Gateway + Nacos + JWT + OAuth2

🧭 一、网关角色定位（Why Gateway？）

API Gateway 是整个微服务系统的“唯一入口”和“安全守门人”。

它不是业务逻辑的执行者，也不是数据的组装者，而是：

角色	说明
✅ 路由中枢	将外部请求按路径/域名分发到正确的微服务
✅ 认证入口	统一验证身份（JWT/OAuth2），拒绝非法请求
✅ 安全屏障	防止直接暴露内部服务，防御DDoS、爬虫、SQL注入等
✅ 流量控制	实现限流、熔断、降级，保障核心服务稳定
✅ 协议转换	处理跨域、压缩、Header 转换等非业务需求
❌ 非业务引擎	不处理订单计算、库存扣减、优惠券核销等

💡 一句话总结：
网关负责“能不能进”，业务服务负责“进了之后干什么”。

✅ 二、推荐在网关层做的事情（必须做）

功能	推荐实现方式	原因说明	示例
1. 请求路由（Routing）	使用 `spring.cloud.gateway.routes` YAML 配置或 Java DSL	所有微服务对外暴露的路径统一由网关管理，隐藏内部结构，支持灰度发布、蓝绿部署	`GET /order/** → lb://order-service`
2. 认证校验（Authentication）	全局过滤器 `JwtAuthenticationFilter` 校验 Token 签名、过期时间、是否在黑名单	避免每个服务重复写登录校验代码；统一策略，提升安全性	检查 `Authorization: Bearer xxx`，提取 `userId` 注入 Header
3. 用户身份透传（Identity Propagation）	将解析后的用户信息通过 HTTP Header 传递给下游服务	下游服务无需再调用认证中心，实现无状态鉴权	设置 `X-User-ID: 123`, `X-Roles: USER,ADMIN`
4. 黑名单 Token 管理（Token Revocation）	使用 Redis 缓存已注销的 JWT Token（key: `jwt:blacklist:<token>`）	实现“立即登出”能力，避免 Token 泄露后仍可被使用	登出时将 Token 写入 Redis，TTL = 5min
5. 请求日志记录（Request Logging）	使用 `GatewayFilter` 记录请求方法、路径、响应码、耗时、IP	用于审计、监控、故障排查	日志格式：`[Gateway] GET /order/123
6. 响应头标准化（Response Header Injection）	添加统一响应头如 `X-Gateway-Version`, `X-Request-ID`	便于追踪链路、识别来源、调试问题	`X-Gateway-Service: urbane-commerce-gateway`
7. 服务发现与负载均衡（Service Discovery）	集成 Nacos/Spring Cloud LoadBalancer，使用 `lb://service-name`	自动感知服务上下线，实现动态扩缩容	`uri: lb://product-service`
8. 请求限流（Rate Limiting）	使用 `RequestRateLimiterGatewayFilterFactory` + Redis 实现令牌桶算法	防止恶意刷接口、保护后端服务稳定性	限制 `/auth/login` 每分钟最多 5 次
9. 熔断与降级（Circuit Breaker）	集成 Resilience4j 或 Hystrix（已弃用），对超时/异常服务自动熔断	避免雪崩效应，保障核心链路可用	当 `payment-gateway` 连续 5 次失败，自动降级返回“支付系统维护中”
10. 跨域支持（CORS）	在网关统一配置 CORS 策略，而非每个服务单独配置	避免前端频繁遇到跨域错误，集中管理白名单	允许 `https://shop.urbane.io` 访问所有 API
11. 静态资源代理（可选）	将前端静态资源（HTML/CSS/JS）通过网关代理	简化部署，一个入口即可访问全站	`GET /static/** → file:/opt/web/dist`
12. 健康检查与监控端点暴露	开放 `/actuator/health`, `/actuator/info`	供 Kubernetes、Prometheus、Zabbix 监控网关存活状态	`management.endpoints.web.exposure.include=health,info,metrics`

❌ 三、不推荐或禁止在网关层做的事情（严禁做）

功能	为什么不推荐？	后果	正确做法
1. 统一包装正常响应体（如把所有结果包成 `{code:200, data:...}`）	网关无法理解业务语义，无法知道 `{"id":123}` 是商品还是订单；需解析 JSON 再重组，性能差、易错、难维护	前端收到 `{data: {data: {...}}}` 的嵌套结构，调试困难；破坏原有契约	✅ 在每个微服务的 Controller 层返回 `Result<T>`，网关不做任何修改
2. 执行业务逻辑（如计算价格、扣减库存、生成订单）	网关不是业务服务，职责严重越界；一旦业务变更，需重启网关，风险极高	单点故障、高耦合、难以测试、违反微服务自治原则	✅ 所有业务逻辑放在对应服务中（如 `order-service`）
3. 数据库访问或缓存操作	网关应无状态、轻量、高性能；连接数据库会拖慢响应、增加连接池压力	引发性能瓶颈、内存泄漏、连接耗尽	✅ 数据库只允许业务服务访问，网关只转发
4. 权限校验（Authorization）	“你是谁？”（认证）网关能做，“你能做什么？”（鉴权）网关不知道	网关无法判断“你能否删除这个订单”——只有 `order-service` 知道订单属于谁	✅ 网关只做认证（Authentication） ✅ 权限校验（Authorization）交给业务服务（使用 `@PreAuthorize("hasAuthority('DELETE_ORDER') and #orderId == principal.userId")`）
5. 修改请求参数或 Body 内容（如重写 userId）	安全风险极大！可能被攻击者利用伪造身份	可能导致 A 用户看到 B 用户的订单	✅ 网关只能读取并透传用户信息，绝不修改或注入伪造值
6. 拼接多个服务的响应（聚合）	如：一个请求要查商品+评价+库存→网关去调三个服务再拼接	网关变成“BFF（Backend For Frontend）”，违背其定位；性能差、复杂度爆炸	✅ 若需聚合，新建独立服务 `bff-service`，专门面向前端聚合，不要混入网关
7. 处理文件上传/下载	文件传输占用大量内存和带宽，网关不适合承担 I/O 密集型任务	易引发 OOM、超时、连接中断	✅ 上传下载走对象存储（MinIO/OSS）直连，或通过独立 `file-service` 处理
8. 依赖 Session 或 Cookie 存储用户状态	网关是无状态架构，Session 无法在集群间共享	会导致登录失效、用户漂移	✅ 使用 JWT Token，完全无状态
9. 配置复杂业务规则（如促销活动、满减逻辑）	业务规则变化频繁，网关重启成本高	每改一次规则就要部署网关，影响全平台可用性	✅ 促销规则由 `promo-service` 管理，网关仅转发请求
10. 使用 XML / SOAP 协议处理	网关主要面向 RESTful API，XML 解析开销大，不符合现代架构趋势	性能下降、维护困难	✅ 如需支持旧系统，建议用独立适配器服务（Adapter Pattern）

🔍 四、判断标准与核心设计原则

原则	说明	应用示例
✅ 单一职责原则（SRP）	一个组件只做一件事，且做好它	网关只做“路由 + 认证 + 流量控制”，不做业务
✅ 无状态性（Statelessness）	所有请求独立，不依赖本地内存或 Session	使用 JWT + Redis 黑名单，不存用户状态在网关内存
✅ 低耦合 & 高内聚	网关与业务服务解耦，业务服务可独立开发、测试、部署	业务服务升级不影响网关，网关升级不影响业务
✅ 安全纵深防御（Defense in Depth）	网关是第一道防线，但不能替代业务层的安全	网关校验 Token，业务层校验权限，双保险
✅ 性能优先（Low Latency）	网关是所有请求的必经之路，任何延迟都会放大	避免在网关做 JSON 解析、数据库查询、复杂计算
✅ 可观测性（Observability）	所有行为应可监控、可追踪、可审计	记录请求日志、响应码、耗时、TraceID，接入 Prometheus + Zipkin
✅ 渐进式演进（Gradual Evolution）	不追求一次性完美，但每一步都符合标准	初期只做路由 + JWT，后期逐步加入限流、熔断
✅ 开闭原则（OCP）	对扩展开放，对修改关闭	新增服务只需加路由，无需改网关代码；新增过滤器可插拔

🧩 五、典型场景对比：正确 vs 错误做法

场景	正确做法	错误做法
用户登录	客户端 → `auth-service`（登录）→ 返回 JWT 后续请求携带 JWT → 网关校验 → 透传 `X-User-ID` → `order-service` 鉴权	客户端 → 网关 → 网关调用 `auth-service` → 网关生成 Session → 保存在内存中
查看订单	客户端 → 网关（校验 Token）→ `order-service`（校验 `orderId` 是否属于自己）→ 返回订单	客户端 → 网关 → 网关查数据库判断“这个订单是不是你的”→ 返回结果
下单购买	客户端 → 网关 → `order-service`（创建订单）→ `inventory-service`（扣库存）→ `payment-gateway`（支付）	客户端 → 网关 → 网关调用三个服务 → 拼接响应 → 返回 `{ "status": "success" }`
获取商品详情	客户端 → 网关 → `product-service` → 返回 `{ id, name, price }`	客户端 → 网关 → 网关调用 `product-service` + `review-service` + `stock-service` → 拼成 `{ product, reviews, stock }` → 返回
用户退出登录	客户端 → 网关 → `auth-service` → 删除 Token 并写入 Redis 黑名单	客户端 → 网关 → 网关清空本地缓存（无效果，其他节点仍有效）

⚠️ 关键结论：
凡是需要“理解业务”的操作，都不该在网关做。
凡是需要“全局统一”的操作，才适合放在网关。

🛡️ 六、安全加固建议（生产环境必备）

措施	实现方式
强制 HTTPS	网关监听 443，禁用 HTTP
禁用敏感 Header	移除 `Server`, `X-Powered-By` 等泄露信息
输入过滤	过滤 SQL 注入、XSS 字符（使用 `GatewayFilter`）
WAF 集成	部署云 WAF（如阿里云 WAF、Cloudflare）前置防护
IP 白名单	对 `/actuator/*` 等管理接口设置内网访问限制
请求大小限制	限制 `maxRequestBodySize` 防止上传炸弹
防重放攻击	在 JWT 中加入 `nonce` 或 `iat` 时间戳 + 网关校验时间窗口（±5min）

📊 七、网关架构图（文字版）

[客户端]
     ↓ (HTTPS)
[API Gateway: urbane-commerce-gateway]
     ├── ✅ 路由：/user/** → lb://user-service
     ├── ✅ 认证：校验 JWT → 注入 X-User-ID
     ├── ✅ 限流：/auth/login ≤ 5次/分钟
     ├── ✅ 熔断：/payment-gateway 故障时降级
     ├── ✅ 日志：记录所有请求
     ├── ✅ CORS：允许 shop.urbane.io
     └── ✅ 健康端口：/actuator/health
     ↓ (转发，带 Header)
[业务微服务集群]
     ├── user-service → 查询用户信息
     ├── order-service → 校验权限、创建订单
     ├── product-service → 返回商品详情
     └── payment-gateway → 支付回调

🔄 注意：所有业务服务之间不得直接互相调用（除非必要），应通过网关或消息队列通信。

✅ 八、总结：网关设计黄金法则（可打印贴墙上）

✅ 网关应该做的：

路由分发
认证校验（JWT）
限流熔断
日志埋点
跨域处理
Header 透传
服务发现
异常拦截（5xx/4xx）

❌ 网关绝对不该做的：

包装响应体
执行业务逻辑
访问数据库
校验权限（Authorization）
拼接多个服务响应
管理 Session
处理文件上传
实现促销规则

🔑 判断一切的标准：

“如果这个功能，换了另一个微服务也能做，那就不该放在网关。”
“如果这个功能，需要理解业务语义，那就一定不属于网关。”

📦 九、附录：推荐依赖清单（Maven）

<!--
    Spring Cloud Gateway 基于 WebFlux 的响应式网关启动器。
    适用于构建高性能、非阻塞的 API 网关，底层基于 Project Reactor 和 Netty。
    注意：WebFlux 是响应式编程模型，不能与传统的 Servlet（如 Tomcat）混合使用。
-->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>
<!-- 使用 Sentinel 进行网关层限流 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-alibaba-sentinel-gateway</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
<!-- 如果使用配置中心，想要 bootstrap.yaml 中配置生效，则需要该依赖 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>
        
<!-- 使用 Nacos 作为注册中心和配置中心 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

<!--
    Spring Boot 响应式 Redis 启动器。
    提供基于 Reactor 的响应式 Redis 支持（ReactiveRedisTemplate），
    支持非阻塞的 Redis 操作，适用于 WebFlux 等响应式应用架构。
    与 spring-boot-starter-data-redis 功能对应，但编程模型为响应式。
    用于 Token 黑名单、限流（Redis + RateLimiter）
-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis-reactive</artifactId>
</dependency>

<!--
    Spring Boot Actuator 启动器。
    提供生产就绪的监控和管理端点（endpoints），如 /actuator/health（健康检查）、
    /actuator/metrics（指标）、/actuator/info（应用信息）、/actuator/loggers（日志级别调整）等。
    用于监控应用运行状态、性能指标、配置信息等，是构建可观测性（Observability）的基础组件。
-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

<!-- 日志增强 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

<!--
    Lombok 工具库。
    通过注解（如 @Data、@Getter、@Setter 等）自动生成 Java 类的样板代码（getter/setter/toString 等），
    减少冗余代码，提升开发效率。
    需要 IDE 安装 Lombok 插件才能正确识别生成的代码。
    标记为 optional=true 表示仅在编译期使用，运行时不需要，且不会被依赖项目传递引入。
-->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

<!--
    Java JWT（JSON Web Token）官方实现库（JJWT）。
    JJWT 是一个功能完整、安全且易于使用的 Java 库，用于创建和验证 JWT（RFC 7519）。
    核心功能包括：
      - 生成签名的 JWT（支持 HS256、HS384、HS512、RS256 等算法）
      - 解析和验证 JWT 的签名、过期时间（exp）、签发时间（iat）、受众（aud）等声明（claims）
      - 支持 JWT、JWS（签名）、JWE（加密）标准（本版本主要侧重 JWS）
      - 提供 Builder/Parser 链式 API
    常用于实现基于 Token 的无状态认证（如 OAuth2、Spring Security 集成），
    适用于微服务、前后端分离架构中的用户
    注意：
      - 自 0.10.0 起，JJWT 拆分为多个模块（如 jjwt-api、jjwt-impl、jjwt-jackson），
        但 0.13.0 版本仍提供单体 jar（包含所有依赖），使用方便；
      - 在生产环境中，建议使用强密钥（如 256 位以上）并设置合理的过期时间；
      - 若项目使用 Spring Boot 3+，需确保兼容 Jakarta EE（JJWT 0.12+ 已支持）。
-->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt</artifactId>
    <version>0.13.0</version>
</dependency>