# 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>
```

网关校验成功后，会透传 `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`