145 lines
4.1 KiB
Markdown
145 lines
4.1 KiB
Markdown
# 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`
|