# springcloud-gateway-route-push

**Repository Path**: ismartyx/springcloud-gateway-route-push

## Basic Information

- **Project Name**: springcloud-gateway-route-push
- **Description**: 基于 **MySQL + Hazelcast 或 redis ** 实现网关路由的持久化存储与分布式实时推送，支持多网关节点秒级同步
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: replace-hazelcast
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Cloud Gateway 分布式路由推送系统 (springcloud-gateway-route-push)

基于 **MySQL + Hazelcast** 实现网关路由的持久化存储与分布式实时推送，支持多网关节点秒级同步。无需 Redis，完全依赖 Hazelcast
去中心化集群完成路由共享与变更广播。

## 技术栈

| 组件                   | 版本       | 说明                          |
|----------------------|----------|-----------------------------|
| Java                 | 17       |                             |
| Spring Boot          | 3.2.5    |                             |
| Spring Cloud         | 2023.0.1 |                             |
| Spring Cloud Gateway | —        | 基于 WebFlux 的响应式网关           |
| Hazelcast            | 5.3.6    | 分布式 IMap 存储路由 + ITopic 广播变更 |
| MySQL                | 8.0.33   | 路由持久化                       |
| MyBatis              | 3.0.3    | ORM                         |
| Hutool               | 5.8.26   | JSON 工具                     |

## 架构图

```
┌──────────────────────────────────────────────────────────────────────┐
│                          gateway-admin (port:9000)                    │
│                                                                       │
│  REST API ──► GatewayRouteService                                     │
│                    │                                                  │
│                    ├─── 1. 写入 MySQL (gateway_route)                 │
│                    ├─── 2. 写入 Hazelcast IMap (gateway:routes)       │
│                    └─── 3. Publish → Hazelcast ITopic (gateway:route:change) │
└──────────────────────────────────────────────────────────────────────┘
                                       │
                     Hazelcast Cluster  │  (TCP/IP 去中心化集群)
                                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│                          gateway-core (port:8080)                     │
│                                                                       │
│  HazelcastRouteChangeListener (ITopic) ──► DynamicRouteService        │
│                                                  │                    │
│                                                  ├─ 更新内存 ConcurrentHashMap │
│                                                  └─ 发布 RefreshRoutesEvent   │
│                                                            │          │
│                                                Spring Cloud Gateway   │
│                                                重新加载路由定义        │
└──────────────────────────────────────────────────────────────────────┘
```

## 模块说明

| 模块               | 端口   | 职责                                                                    |
|------------------|------|-----------------------------------------------------------------------|
| `gateway-common` | —    | 公共实体（`GatewayRoute`）、常量（`GatewayConstants`）、DTO（`RouteChangeMessage`） |
| `gateway-admin`  | 9000 | 路由 CRUD 管理、同步 Hazelcast IMap、发布 Topic 消息                              |
| `gateway-core`   | 8080 | Spring Cloud Gateway 网关、动态路由加载、监听 Topic 热更新                           |

## 界面预览

### 路由列表

![路由列表](doc/img/query-route.png)

### 新增/编辑路由

![新增路由](doc/img/add-route.png)

## 快速启动

### 1. 初始化数据库

```sql
mysql -u root -p < doc/sql/init.sql
```

### 2. 修改配置

编辑两个模块的 `application.yml`，配置 MySQL 连接信息和 Hazelcast 集群成员：

- `gateway-admin/src/main/resources/application.yml`
- `gateway-core/src/main/resources/application.yml`

关键配置项：

```yaml
# Hazelcast 去中心化集群配置（两个模块均需配置，集群名称必须一致）
hazelcast:
  cluster:
    name: gateway-cluster
  network:
    members: localhost:5700,localhost:5701  # 所有节点的 Hazelcast 端口
```

> **说明**：`gateway-admin` 默认监听 Hazelcast 端口 `5700`，`gateway-core` 从 `5700` 开始自动递增（多实例时依次为 `5701`、
`5702`……）。

### 3. 编译打包

```bash
mvn clean package -DskipTests
```

### 4. 启动顺序

```bash
# 先启动管理后台
java -jar gateway-admin/target/gateway-admin-1.0.0.jar

# 再启动网关（会自动从 Hazelcast/MySQL 加载路由）
java -jar gateway-core/target/gateway-core-1.0.0.jar
```

## 动态路由 API

### 新增路由

```http
POST http://localhost:9000/api/routes
Content-Type: application/json

{
  "routeId": "demo-route",
  "uri": "http://httpbin.org",
  "predicates": "[\"Path=/demo/**\"]",
  "filters": "[\"StripPrefix=1\"]",
  "orders": 5,
  "status": 1,
  "remark": "Demo 路由"
}
```

### 查询路由列表（分页）

```http
GET http://localhost:9000/api/routes?current=1&size=10
```

### 查询路由列表（不分页）

```http
GET http://localhost:9000/api/routes/all?status=1
```

### 查询单条路由

```http
GET http://localhost:9000/api/routes/1
```

### 更新路由

```http
PUT http://localhost:9000/api/routes
Content-Type: application/json

{ "id": 1, "routeId": "demo-route", "status": 0, ... }
```

### 切换路由状态（启用/禁用）

```http
PUT http://localhost:9000/api/routes/1/status?status=0
```

### 删除路由

```http
DELETE http://localhost:9000/api/routes/1
```

### 批量删除路由

```http
DELETE http://localhost:9000/api/routes/batch
Content-Type: application/json

[1, 2, 3]
```

### 全量同步到 Hazelcast

```http
POST http://localhost:9000/api/routes/sync
```

## 路由数据结构说明

`predicates` 和 `filters` 字段存储 JSON 字符串数组，每个元素为 Spring Cloud Gateway 的简写语法：

```json
{
  "predicates": "[\"Path=/api/user/**\", \"Method=GET,POST\"]",
  "filters":    "[\"StripPrefix=1\", \"AddRequestHeader=X-Source, gateway\"]"
}
```

> **状态说明**：`status=1` 为启用（推送到 Hazelcast），`status=0` 为禁用（从 Hazelcast 删除并通知网关移除）。

## 关键流程

1. **启动加载**：`RouteInitRunner` → `DynamicRouteService.loadRoutes()` → 优先读 Hazelcast IMap，降级读 MySQL → 写入内存
   `ConcurrentHashMap` → 触发 `RefreshRoutesEvent`
2. **运行时更新**：Admin 调用 API → 写 MySQL → 写 Hazelcast IMap → Publish 消息到 ITopic → Core 监听器收到消息 → 从
   Hazelcast IMap 拉取最新路由 → 更新内存 Map → 触发 `RefreshRoutesEvent`
3. **全量同步**：调用 `/api/routes/sync` → Admin 清空并重写 Hazelcast IMap → 发布 `SYNC_ALL` 消息 → 所有 Core 实例重新加载全量路由
4. **多实例一致性**：多个 `gateway-core` 实例加入同一 Hazelcast 集群，Topic 消息广播确保所有实例同步更新，无需重启。