# backend-gateway

**Repository Path**: MetaLite/backend-gateway

## Basic Information

- **Project Name**: backend-gateway
- **Description**: 【独立部署应用】元界MetaLite后端应用的业务网关，处于负载均衡组件之后，对外提供所有公网API访问入口。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-04
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# backend-gateway

## 简介

`backend-gateway` 是 MetaLite 微服务架构的**业务网关层**，位于负载均衡之后，作为所有公网API的唯一入口，需独立部署。

### 定位与职责

| 定位 | 职责 |
|------|------|
| 统一入口 | 所有公网API的唯一入口 |
| 流量控制 | 三层维度限流（节点/调用方/用户） |
| 认证鉴权 | 调用方鉴权(AppKey/签名) + 用户认证(userToken) |
| 统一加解密 | 请求解密、响应加密、明文清除 |
| 独立部署 | 作为独立服务运行 |

---

## 设计思想

### 三层维度限流

```
请求 → 节点级限流 → 调用方级限流 → 用户级限流 → 业务处理
         │              │              │
         │              │              ▼
         │              │         Redis Lua脚本
         │              │         分钟/小时/天级窗口
         │              ▼
         │         Redis Lua脚本
         │         分钟/小时/天级窗口
         ▼
    Guava RateLimiter
    内存秒级滑动窗口
    保护当前节点
```

每个层级均支持**全限流**和**单接口限流**两个维度，可灵活配置。

### 统一加解密流程

```
请求 → 解密encryptData → plaintext → 业务处理 → 加密resp.data → encryptData → 清除明文
          │                                              │                    │
          │                                              │                    ▼
          │                                              │            ApiClearRespDataHandler
          │                                              ▼
          ▼                                       ApiRespEncryptHandler
    BizParamDecryptHandler
```

支持对称加密算法：SM4-GCM、SM4-CBC、AES-GCM、AES-CBC。

### 为什么不引入 Sentinel

本框架未集成 `spring-cloud-starter-alibaba-sentinel`，设计考量如下：

**1. 网关层熔断收益有限**

| 场景 | 当前方案 | Sentinel 熔断 |
|------|---------|---------------|
| 流量突增（营销活动、爬虫） | ✅ 三层限流 | ✅ |
| 下游服务响应慢 | ✅ `RpcRequest.timeoutMillis` + `fallback` 快速失败降级 | ✅ |
| 下游服务故障 | ✅ 超时 + 降级 + 重试 | ✅ |

网关层的核心职责是**流量控制**，下游服务响应慢/故障场景已通过 `RpcRequest` 的 `timeoutMillis` 和 `fallback` 机制覆盖：

```java
RpcRequest.builder()
    .provider("user-service")
    .endpoint("/api/user/get")
    .timeoutMillis(3000)  // 超时快速失败
    .fallback((ex, resp) -> Resp.ok(null))  // 降级响应
    .build();
```

熔断的边际收益在于**自动判断故障状态**，但网关层通常明确知道哪些服务可用，且调用链路相对固定，手动配置超时降级已能满足需求。

**2. 用户维度限流需要 Token 解析**

```
请求 → 网关 → 解析Token(查Redis) → 获取userId → 用户级限流
```

Sentinel 的热点参数限流要求在规则匹配阶段就获取参数值，但此时 userId 尚未解析。若强行集成：
- 需在 Sentinel 参数解析器中查 Redis，每次请求都查询，性能损耗大
- 或在 Sentinel 过滤器前前置解析，增加复杂度

当前方案在 Token 解析后自然获取 userId，流程简洁。

**3. 当前方案已覆盖核心需求**

| 能力 | 当前方案 | Sentinel |
|------|---------|----------|
| 流量控制 | ✅ 三层维度限流 | ✅ |
| 保护网关节点 | ✅ Guava RateLimiter | ✅ |
| 调用方隔离 | ✅ Redis 分布式限流 | 需定制 |
| 用户隔离 | ✅ Redis 分布式限流 | 需定制 |
| 配置热更新 | ✅ 定时拉取 | ✅ |
| 降级 | ✅ `RpcRequest.fallback` | ✅ |
| 熔断 | ❌ 无状态机 | ✅ 自动切断/恢复 |
| 可视化控制台 | ❌ | ✅ |

90% 以上的网关场景只需**限流降级**，无需熔断。引入 Sentinel 会增加依赖复杂度，但收益有限。

**4. 如需监控能力**

若后续需要监控可视化，建议接入 **Prometheus + Grafana**，比 Sentinel Dashboard 更通用，可与整个微服务体系的监控统一。

---

## 核心能力

| 能力 | 说明 |
|------|------|
| 节点级限流 | Guava RateLimiter，内存秒级滑动窗口，保护当前节点不被压垮 |
| 调用方级限流 | Redis Lua脚本，分钟/小时/天级窗口，分布式限流，全局+单接口维度 |
| 用户级限流 | Redis Lua脚本，分钟/小时/天级窗口，分布式限流，全局+单接口维度 |
| 调用方鉴权 | 校验appId、时间戳防重放(30秒)、IP白名单、签名(SM3/SHA-256) |
| 用户认证 | userToken认证，Redis存储，可配置有效期 |
| 请求解密 | 解密encryptData字段，写入plaintext供业务使用 |
| 响应加密 | 加密resp.data字段，写入encryptData返回调用方 |
| 明文清除 | 加密响应后清除data字段明文，防止泄露 |
| HTTP状态码 | 服务端错误时设置HTTP 500，便于客户端识别 |
| 请求日志 | 全链路请求追踪日志 |
| 配置热加载 | 定时从Admin服务加载限流、调用方配置，实时生效 |

---

## 模块结构

```
backend-gateway/
├── src/main/java/com/metalite/gateway/
│   ├── GatewayApplication.java          # 启动类
│   ├── admin/api/                       # Admin服务的API接口（转发）
│   ├── security/
│   │   ├── aspect/                      # 安全切面处理器
│   │   │   ├── NodeRateLimitHandler     # 节点限流
│   │   │   ├── CallerAuthHandler        # 调用方鉴权
│   │   │   ├── UserAuthHandler          # 用户认证
│   │   │   ├── BizParamDecryptHandler   # 请求解密
│   │   │   ├── ApiRespEncryptHandler    # 响应加密
│   │   │   ├── ApiRespStatusHandler     # HTTP状态码
│   │   │   └── ApiClearRespDataHandler  # 明文清除
│   │   └── service/                     # 认证、限流服务
│   └── common/config/                   # 公共配置
└── src/main/resources/
    ├── application.yml                  # 主配置文件
    ├── application-dev.yml              # 开发环境配置
    ├── application-test.yml             # 测试环境配置（可选）
    ├── application-prod.yml             # 生产环境配置（可选）
    └── logback-spring.xml               # 日志配置
```

---

## 许可证

MIT License