# Spring Cloud Gateway通用网关

**Repository Path**: xjh201215/gateway

## Basic Information

- **Project Name**: Spring Cloud Gateway通用网关
- **Description**: Spring Cloud Gateway通用网关个人开发
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2025-03-07
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GatewayX - 企业级高性能API网关

<div align="center">

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Java Version](https://img.shields.io/badge/Java-11+-orange.svg)](https://adoptium.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.17-green.svg)](https://spring.io/projects/spring-boot)
[![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2021.0.8-green.svg)](https://spring.io/projects/spring-cloud)
[![Stars](https://gitee.com/itxtech/gatewayx/badge/star.svg?theme=dark)](https://gitee.com/itxtech/gatewayx)
[![Forks](https://gitee.com/itxtech/gatewayx/badge/fork.svg?theme=dark)](https://gitee.com/itxtech/gatewayx)

</div>

## 项目简介

**GatewayX** 是一个基于 Spring Cloud Gateway 构建的企业级高性能API网关，为微服务架构提供统一的入口点。它处理横切关注点，包括认证授权、流量控制、请求日志和系统监控。

### 核心特性

- **动态路由**：通过数据库配置路由，支持热更新无需重启
- **认证授权**：内置JWT Token验证，支持Token黑名单
- **限流控制**：基于Redis令牌桶算法的分布式限流
- **请求日志**：完整的API访问日志记录与分析
- **健康监控**：集成Spring Actuator，提供完善的监控端点
- **跨域支持**：内置CORS配置，开箱即用

### 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| 核心框架 | Spring Cloud Gateway | 2021.0.8 |
| 基础框架 | Spring Boot | 2.7.17 |
| 数据库 | MySQL | 8.0+ |
| 缓存 | Redis | 6.0+ |
| ORM | MyBatis Plus | 3.5.3 |
| 数据库连接池 | Druid | 1.2.20 |
| 异步框架 | WebFlux | - |

## 快速开始

### 环境要求

- JDK 11 或更高版本
- MySQL 8.0 或更高版本
- Redis 6.0 或更高版本
- Maven 3.8+ 或 Docker

### 使用Docker部署（推荐）

```bash
# 克隆项目
git clone https://gitee.com/itxtech/gatewayx.git
cd gatewayx

# 启动所有服务（GatewayX + MySQL + Redis）
docker-compose up -d

# 启动包含管理工具的服务
docker-compose --profile tools up -d

# 访问服务
# 网关: http://localhost:8080
# Redis Commander: http://localhost:8081
# phpMyAdmin: http://localhost:8082
```

### 手动部署

#### 1. 配置数据库

编辑 `src/main/resources/application-dev.yml` 或设置环境变量：

```bash
# Linux/macOS
export DB_HOST=localhost
export DB_PORT=3306
export DB_USERNAME=root
export DB_PASSWORD=your_password

# Windows PowerShell
$env:DB_HOST="localhost"
$env:DB_PORT="3306"
$env:DB_USERNAME="root"
$env:DB_PASSWORD="your_password"
```

#### 2. 构建项目

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

#### 3. 启动应用

```bash
java -jar target/gatewayx.jar
```

脚本会自动完成：
- 使用 JDBC `createDatabaseIfNotExist=true` 自动创建数据库
- Flyway 自动执行数据库迁移脚本

#### 4. 验证部署

| 服务 | 地址 |
|------|------|
| 网关首页 | http://localhost:8080 |
| API文档 | http://localhost:8080/doc.html |
| 健康检查 | http://localhost:8080/actuator/health |
| 路由列表 | http://localhost:8080/actuator/gateway/routes |

## 项目结构

```
gatewayx/
├── src/main/java/com/itx/gatewayx/
│   ├── GatewayXApplication.java      # 启动类
│   ├── common/                     # 公共模块
│   │   ├── StatusCode.java         # 状态码枚举
│   │   ├── model/
│   │   │   └── ResponseResult.java # 统一响应
│   │   ├── constants/
│   │   │   └── SystemConstants.java
│   │   └── exception/
│   │       └── ServiceException.java
│   ├── config/                     # 配置类
│   │   ├── RedisConfig.java
│   │   ├── IgnoreUrlsConfig.java
│   │   └── MyBatisConfig.java
│   ├── controller/                 # 控制器
│   │   ├── RouteController.java    # 路由管理
│   │   ├── AccessLogController.java # 日志查询
│   │   ├── MonitorController.java   # 系统监控
│   │   └── TestController.java      # 测试接口
│   ├── filter/                     # 网关过滤器
│   │   ├── GatewayAuthFilter.java  # 认证
│   │   ├── RateLimiterFilter.java  # 限流
│   │   └── RequestLogFilter.java   # 日志
│   ├── mapper/                     # 数据访问层
│   ├── service/                    # 业务服务层
│   │   └── impl/
│   ├── domain/                     # 实体类
│   ├── handler/                    # 全局异常处理
│   └── utils/                      # 工具类
├── src/main/resources/
│   ├── application*.yml            # 配置文件
│   └── db/migration/               # Flyway迁移脚本
├── docker/                         # Docker配置
├── k8s/                           # Kubernetes配置
├── docs/                          # 文档
├── Dockerfile
├── docker-compose.yml
└── pom.xml
```

## API接口

### 路由管理

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/route/list` | 获取所有路由 |
| GET | `/route/{routeId}` | 获取指定路由 |
| POST | `/route` | 添加路由 |
| PUT | `/route` | 更新路由 |
| DELETE | `/route/{routeId}` | 删除路由 |
| POST | `/route/refresh` | 刷新路由 |

### 访问日志

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/log/recent` | 最近日志 |
| GET | `/log/user/{userId}` | 按用户查询 |
| GET | `/log/path` | 按路径查询 |

### 系统监控

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/monitor/server` | 服务器信息 |
| GET | `/actuator/health` | 健康检查 |
| GET | `/actuator/gateway/routes` | 网关路由 |

详细API文档请参考 [docs/API.md](docs/API.md)

## 配置说明

### 主配置文件

```yaml
gateway:
  auth:
    enabled: true                    # 启用认证
    token-header: Authorization      # Token请求头
    token-prefix: Bearer             # Token前缀
  rate-limit:
    enabled: true                   # 启用限流
    default-limit: 100              # 默认限流次数/分钟
  security:
    ignoreUrls:                    # 白名单路径
      - /doc.html
      - /actuator/**
```

### 环境变量

| 变量 | 描述 | 默认值 |
|------|------|--------|
| `DB_HOST` | 数据库主机 | localhost |
| `DB_PORT` | 数据库端口 | 3306 |
| `DB_NAME` | 数据库名称 | gateway_db |
| `DB_USERNAME` | 数据库用户名 | root |
| `DB_PASSWORD` | 数据库密码 | - |
| `REDIS_HOST` | Redis主机 | localhost |
| `REDIS_PORT` | Redis端口 | 6379 |
| `REDIS_PASSWORD` | Redis密码 | - |

## 测试

```bash
# 运行单元测试
mvn test

# 生成测试覆盖率报告
mvn test jacoco:report
```

## Kubernetes部署

```bash
# 部署到Kubernetes
kubectl apply -f k8s/deployment.yaml

# 检查部署状态
kubectl get pods -n gatewayx

# 查看日志
kubectl logs -n gatewayx -l app=gatewayx
```

## 监控集成

### Prometheus

```yaml
management:
  metrics:
    export:
      prometheus:
        enabled: true
```

访问指标: `http://localhost:8080/actuator/prometheus`

### Grafana

导入 `docker/grafana/gatewayx-dashboard.json` 仪表盘。

## 开发指南

### 添加自定义过滤器

```java
@Component
@Slf4j
public class CustomFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 过滤器逻辑
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE + 100;
    }
}
```

### 添加自定义断言

```java
@Component
public class VersionPredicateFactory
    extends AbstractRoutePredicateFactory<VersionPredicateFactory.Config> {

    @Override
    public Predicate<ServerWebExchange> apply(Config config) {
        return exchange -> {
            String version = exchange.getRequest().getHeaders()
                .getFirst("X-API-Version");
            return config.getVersion().equals(version);
        };
    }

    public static class Config {
        private String version;
        // getters and setters
    }
}
```

## 常见问题

### 1. 路由配置不生效

- 检查数据库中 `status` 字段是否为 0
- 检查 `del_flag` 是否为 0（逻辑删除标志）
- 调用 `POST /route/refresh` 手动刷新

### 2. 限流不生效

- 检查 `gateway.rate-limit.enabled` 是否为 true
- 检查Redis是否正常连接
- 确认请求路径不在白名单中

### 3. 认证失败

- 检查Token格式是否为 `Bearer xxx`
- 检查Token是否在黑名单中
- 确认请求路径需要认证（不在白名单中）

## 文档

- [API接口文档](docs/API.md)
- [架构设计文档](docs/ARCHITECTURE.md)
- [环境配置指南](docs/ENVIRONMENT.md)

## 许可证

GatewayX 采用 Apache License 2.0 开源许可证。详见 [LICENSE](LICENSE) 文件。

## 贡献指南

欢迎提交 Pull Request！如有问题请提交 Issue。

## 联系方式

- **问题反馈**: https://gitee.com/itxtech/gatewayx/issues

## 致谢

- [Spring Cloud Gateway](https://spring.io/projects/spring-cloud-gateway)
- [Spring Boot](https://spring.io/projects/spring-boot)
- [MyBatis Plus](https://baomidou.com/)
- [Redisson](https://github.com/redisson/redisson)
- [Knife4j](https://doc.xiaoymin.cn/)

---

<div align="center">

**如果这个项目对您有帮助，请在 [Gitee](https://gitee.com/itxtech/gatewayx) 上给我们一个Star！**

</div>