cn-rdms/rdms-gateway

rdms-gateway

1. 模块定位

rdms-gateway 是 API 服务网关模块，基于 Spring Cloud Gateway（WebFlux）实现，负责统一入口的路由转发、鉴权透传、跨域处理、访问日志、灰度/标签负载与全局异常处理。

2. 设计思路

• 通过网关统一处理横切能力，业务服务只关注业务逻辑。
• 鉴权只做“解析 + 透传”，是否需要登录交给后端服务判定。
• 灰度/标签负载通过自定义 grayLb:// 方案实现。
• 访问日志默认打印到日志，后续可扩展为落库。

3. 功能模块

3.1 路由与文档聚合

• 路由配置集中在 application.yaml 的 spring.cloud.gateway.server.webflux.routes。
• Knife4j Gateway 负责聚合各服务的 OpenAPI 文档。

3.2 Token 鉴权透传

TokenAuthenticationFilter 负责：

• 从 Authorization 解析 Token
• 远程校验 Token 有效性
• 校验通过后将 login-user 头透传给后端
• 不阻断请求，是否需要登录由后端服务决定

3.3 跨域处理

CorsFilter 统一放行跨域请求，并处理 OPTIONS 预检请求。

3.4 访问日志

AccessLogFilter 记录：

• 请求路径、方法、参数、Body、Headers
• 响应体、响应码
• 耗时、用户信息

当前实现是打印到日志（控制台/文件），可扩展为落库。

3.5 灰度/标签负载

灰度发布（Gray/Canary）是指新旧版本并行运行，只让一小部分请求先进入新版本验证，稳定后再逐步扩大流量，最终全量切换。

在本项目中，灰度不是按“百分比随机分流”，而是按请求头定向路由：

• 请求头 version 用于匹配实例 metadata.version
• 请求头 tag 用于匹配实例 metadata.tag
• 如果匹配不到目标实例，会回退到全量实例
• 最终按 Nacos 权重随机选择实例

grayLb:// + GrayLoadBalancer 规则：

• header version 匹配实例 metadata version
• header tag 匹配实例 metadata tag
• 无匹配时回落到全量实例

注意：

• 不带 tag 的请求会优先过滤掉带 tag 的实例，避免测试/灰度实例被默认流量命中
• 灰度发布依赖请求头控制路由范围，需要由网关或内部调用方注入 version/tag，避免外部随意绕路

3.6 全局异常

GlobalExceptionHandler 将异常统一翻译为 CommonResult 返回。

3.7 Jackson 一致性

GatewayJacksonAutoConfiguration 统一 JSON 序列化策略（时间戳、Long -> Number 等）。

4. 开发人员上手

4.1 路由配置示例

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: system-admin-api
              uri: grayLb://rdms-system-server
              predicates:
                - Path=/admin-api/system/**
              filters:
                - RewritePath=/admin-api/system/v3/api-docs, /v3/api-docs

4.2 鉴权透传

前端携带：

Authorization: Bearer <token>

网关校验成功后，会透传 login-user 给后端服务。

4.3 灰度/标签路由

请求头示例：

version: 1.0.0
tag: dev

服务实例需要在注册中心 metadata 中配置对应 version/tag。

4.4 WebSocket 路由

- id: system-websocket
  uri: grayLb://rdms-system-server
  predicates:
    - Path=/system/ws/**

4.5 文档聚合示例

knife4j:
  gateway:
    enabled: true
    routes:
      - name: system-server
        service-name: rdms-system-server
        url: /admin-api/system/v3/api-docs

5. 关键类索引

• 入口：src/main/java/com/njcn/rdms/gateway/GatewayServerApplication.java
• 路由配置：src/main/resources/application.yaml
• 鉴权：src/main/java/com/njcn/rdms/gateway/filter/security/TokenAuthenticationFilter.java
• 灰度：src/main/java/com/njcn/rdms/gateway/filter/grey/GrayLoadBalancer.java
• 访问日志：src/main/java/com/njcn/rdms/gateway/filter/logging/AccessLogFilter.java
• 跨域：src/main/java/com/njcn/rdms/gateway/filter/cors/CorsFilter.java
• 全局异常：src/main/java/com/njcn/rdms/gateway/handler/GlobalExceptionHandler.java