集成必要性功能

rdms-gateway/README.md

@@ -0,0 +1,144 @@
+# 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 路由配置示例
+
+```yaml
+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>
+tenant-id: <tenantId>
+```
+
+网关校验成功后，会透传 `login-user` 给后端服务。
+
+### 4.3 灰度/标签路由
+
+请求头示例：
+
+```
+version: 1.0.0
+tag: dev
+```
+
+服务实例需要在注册中心 metadata 中配置对应 `version/tag`。
+
+### 4.4 WebSocket 路由
+
+```yaml
+- id: system-websocket
+  uri: grayLb://rdms-system-server
+  predicates:
+    - Path=/system/ws/**
+```
+
+### 4.5 文档聚合示例
+
+```yaml
+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`

rdms-gateway/src/main/java/com/njcn/rdms/gateway/filter/grey/GrayReactiveLoadBalancerClientFilter.java

@@ -55,7 +55,7 @@ public class GrayReactiveLoadBalancerClientFilter implements GlobalFilter, Order
     public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
         URI url = exchange.getAttribute(GATEWAY_REQUEST_URL_ATTR);
         String schemePrefix = exchange.getAttribute(GATEWAY_SCHEME_PREFIX_ATTR);
-        // 修改 by 灿能源码：将 lb 替换成 grayLb，表示灰度负载均衡
+        // 修改：将 lb 替换成 grayLb，表示灰度负载均衡
         if (url == null || (!"grayLb".equals(url.getScheme()) && !"grayLb".equals(schemePrefix))) {
             return chain.filter(exchange);
         }
@@ -121,7 +121,7 @@ public class GrayReactiveLoadBalancerClientFilter implements GlobalFilter, Order
 
     private Mono<Response<ServiceInstance>> choose(Request<RequestDataContext> lbRequest, String serviceId,
                                                    Set<LoadBalancerLifecycle> supportedLifecycleProcessors) {
-        // 修改 by 灿能源码：直接创建 GrayLoadBalancer 对象
+        // 修改：直接创建 GrayLoadBalancer 对象
         GrayLoadBalancer loadBalancer = new GrayLoadBalancer(
                 clientFactory.getLazyProvider(serviceId, ServiceInstanceListSupplier.class), serviceId);
         supportedLifecycleProcessors.forEach(lifecycle -> lifecycle.onStart(lbRequest));

rdms-gateway/src/main/resources/application.yaml

@@ -76,9 +76,6 @@ knife4j:
       - name: system-server
         service-name: rdms-system-server
         url: /admin-api/system/v3/api-docs
-      - name: infra-server
-        service-name: infra-server
-        url: /admin-api/infra/v3/api-docs
       - name: bpm-server
         service-name: bpm-server
         url: /admin-api/bpm/v3/api-docs
@@ -87,4 +84,4 @@ knife4j:
 
 rdms:
   info:
-    version: 1.0.0
+    version: 1.0.0

rdms-gateway/src/main/resources/banner.txt

@@ -1,4 +1,3 @@
-灿能源码 http://www.iocoder.cn
 Application Version: ${rdms.info.version}
 Spring Boot Version: ${spring-boot.version}