# api-gateway

**Repository Path**: captain-duan/api-gateway

## Basic Information

- **Project Name**: api-gateway
- **Description**: 通用的api网关应用
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 统一 API 网关

统一 API 网关是面向数据中台的接口管理与运行平台。它把接口注册、版本发布、权限审批、路由配置、配置下发、调用监控和调用方自助服务集中到一个控制台，并通过 Spring Cloud Gateway 将已授权请求转发到真实 HTTP/HTTPS 后端。

> 当前状态：**参考部署可交付，生产不可上线**。仓库已经完成单机 Compose 联合验证，适合本地体验、开发联调和验收；尚未覆盖生产密钥托管、TLS/RBAC、备份恢复、多节点高可用、容量压测和正式发布审批。

## 应用功能

系统同时包含控制面和数据面：

- **控制面**：管理接口资产、版本、OpenAPI 导入、授权、后端服务、路由和配置版本，业务事实保存到 MySQL，运行态缓存和配置加载状态保存到 Redis。
- **数据面**：通过 `/gateway/**` 接收调用请求，执行鉴权、授权、限流、路由等治理阶段，再转发到真实 HTTP/HTTPS 服务。
- **可观测性**：调用日志异步写入 Elasticsearch，管理端可按 TraceID 检索；Prometheus 抓取应用、JVM 和 HTTP 请求指标。
- **调用方体验**：按调用方的有效授权展示在线文档、权限和配额，并支持携带 AppKey/Secret 通过真实 Gateway 链路在线调试。

典型业务链路如下：

```text
创建接口 -> 发布稳定版本 -> 登记后端服务 -> 建立路由
         -> 发布配置 -> 审批调用权限 -> 通过 Gateway 调用 -> 检索调用日志
```

## 技术组成

| 模块 | 技术或职责 | 代码位置 |
| --- | --- | --- |
| 管理控制台 | React 19、TypeScript、Vite、Ant Design | `frontend/frontend` |
| 网关后端 | JDK 25、Spring Boot 4、WebFlux、Spring Cloud Gateway | `backend` |
| 配置事实源 | MySQL 8，保存接口、版本、授权、路由、配置和审计 | `backend/src/main/resources/db/migration` |
| 运行状态 | Redis 7，保存缓存、锁、限流和配置加载状态 | `compose.yaml` |
| 调用日志 | Elasticsearch 9.2.1，保存可按环境和 TraceID 检索的调用日志 | `backend/src/main/java/com/dmp/apigateway/observability` |
| 指标监控 | Spring Boot Actuator、Micrometer、Prometheus 3.10 | `deploy/prometheus.yml` |
| 参考部署 | Nginx 前端、后端和全部依赖的单机 Compose 编排 | `compose.yaml` |

## 快速启动

推荐使用已经验收过的容器化参考部署。它会启动前端、后端、MySQL、Redis、Elasticsearch、Prometheus，以及一个用于联调的 HTTP fixture，共 7 个服务。

### 环境要求

- Docker Desktop 或兼容的 Docker Engine，支持 Docker Compose v2
- JDK 25 和 Maven 3.8+
- Node.js 18+ 与 npm
- 至少为 Docker 预留约 2 GB 可用内存；Elasticsearch 容器上限为 1 GB

### 1. 构建前后端产物

在仓库根目录执行：

```bash
mvn -f backend/pom.xml -DskipTests package
npm --prefix frontend/frontend ci
npm --prefix frontend/frontend run build
```

### 2. 启动参考栈

```bash
docker compose up -d --build
```

首次启动需要拉取镜像并初始化 MySQL、Elasticsearch，等待时间通常会比后续启动长。可查看服务状态：

```bash
docker compose ps
```

### 3. 访问应用

| 服务 | 默认地址 | 用途 |
| --- | --- | --- |
| 管理控制台 | <http://127.0.0.1:15187> | 使用全部菜单功能；Nginx 同时代理后端接口 |
| 后端健康检查 | <http://127.0.0.1:18087/actuator/health> | 确认 Spring Boot、MySQL 和 Redis 状态 |
| Prometheus | <http://127.0.0.1:19090> | 查看抓取目标和指标 |
| Elasticsearch | <http://127.0.0.1:19202> | 本地诊断调用日志索引 |

快速检查：

```bash
curl -fsS http://127.0.0.1:15187/actuator/health
curl -fsS http://127.0.0.1:19090/-/ready
```

MySQL 和 Redis 默认只在 Compose 内部网络开放，不暴露宿主机端口。全新部署的业务表可能为空，这是正常状态；可直接从控制台创建接口、版本和路由。

### 4. 停止或清理

停止服务并保留本地数据卷：

```bash
docker compose down
```

彻底清理参考栈及其 MySQL、Redis、Elasticsearch、Prometheus 数据：

```bash
docker compose down --volumes --remove-orphans
```

第二条命令会删除本项目 Compose 数据卷中的本地数据，请确认无需保留后再执行。

## 菜单功能介绍

控制台左侧共有 9 个一级菜单：

| 菜单 | 主要用途 | 可以完成的操作与当前边界 |
| --- | --- | --- |
| **工作台** | 汇总生产环境的资源、待办和最近一小时运行态势 | 查看接口数、已发布版本、待审批、活动告警、配置失败节点、调用成功率和活跃调用方；待办聚合权限审批、导入冲突、配置失败和告警，可点击“去处理”跳转到对应菜单。 |
| **接口资产** | 统一登记和查找接口定义 | 按状态或关键字筛选接口；新建 RESTful 接口草稿并真实写入 MySQL。当前列表中的“详情、版本、审计”快捷按钮用于展示操作说明，版本的真实创建和发布请进入“版本与灰度”。 |
| **版本与灰度** | 管理接口版本及其服务状态 | 选择接口、创建 `DRAFT` 版本、填写发布原因并全量发布为 `STABLE`。页面可展示灰度版本和策略引用，但创建灰度策略不属于当前最小闭环，不能用全量发布冒充灰度发布。 |
| **导入与迁移** | 从 OpenAPI 批量生成接口资产 | 上传或粘贴 OpenAPI 3 JSON，先生成解析预览；识别路径/方法重复和接口编码重复，再选择“跳过冲突项”或“存在冲突则终止”后执行导入。预览阶段不会写入接口资产。 |
| **安全与权限** | 处理调用方权限申请 | 查看并筛选真实权限申请；填写审批意见后批准或驳回。批准会生成唯一的 `ACTIVE` 授权，驳回不会生成授权，已处理申请不可重复审批。 |
| **路由与治理** | 把稳定接口版本连接到真实后端 | 新增 HTTP/HTTPS 后端服务和实例，设置权重及可选健康检查；将 `STABLE` 接口版本绑定到后端服务，选择轮询、加权或随机负载策略并建立 `ACTIVE` 路由。路由变更后还需进入“配置发布”使其生效。 |
| **配置发布** | 将控制面配置发布到 Gateway 运行时 | 按范围生成 `CREATED` 配置版本并发布，查看 MySQL 中的版本记录及 Gateway 节点 `LOADED` 状态；当前加载版本应与最新已发布版本一致。 |
| **监控审计** | 查看真实调用态势和定位请求 | 展示调用总数、成功率、失败数和调用方数；按 TraceID、接口 ID、调用方 ID、结果筛选调用日志，并查看请求路径与鉴权、授权、限流、路由等治理阶段。Compose 模式下最终日志存储为 Elasticsearch。 |
| **调用方门户** | 为已授权调用方提供自助服务 | 输入调用方应用 ID 后查看有效授权的已发布接口、权限有效期和日/月配额；填写 AppKey、Secret、方法、路径和请求体，通过真实 Gateway 链路在线调试并查看响应或 TraceID。 |

页面会区分加载中、空数据、无权限和后端错误。当前参考控制台没有生产级登录页，开发联调通过权限标识调用后端；这不等同于完整的生产身份认证和 RBAC。

## 建议的首次体验顺序

1. 在“接口资产”创建一个接口草稿。
2. 在“版本与灰度”为该接口创建版本并全量发布为 `STABLE`。
3. 在“路由与治理”登记可访问的 HTTP/HTTPS 后端服务，并绑定稳定版本创建路由。
4. 在“配置发布”生成配置版本并发布，确认节点状态为 `LOADED`。
5. 准备调用方凭证和有效授权后，在“调用方门户”执行真实请求。
6. 回到“工作台”查看运行态势，并在“监控审计”按 TraceID 检索调用记录。

如果希望直接执行完整机器验收，可运行：

```bash
./scripts/verify-container-deployment-loop.sh
```

该脚本会构建、启动、验证并清理独立参考栈，适合验证环境，不用于保留日常体验数据。

## 本地前端开发

参考栈后端运行在 `18087` 端口时，可以另起 Vite 开发服务器：

```bash
VITE_BACKEND_TARGET=http://127.0.0.1:18087 npm --prefix frontend/frontend run dev -- --host 127.0.0.1 --port 5174
```

访问 <http://127.0.0.1:5174>。Vite 会把 `/admin`、`/developer` 和 `/gateway` 请求代理到指定后端。

如默认端口冲突，可在启动 Compose 前覆盖宿主机端口，例如：

```bash
API_GATEWAY_DEPLOY_FRONTEND_PORT=15188 API_GATEWAY_DEPLOY_BACKEND_PORT=18088 docker compose up -d --build
```

## 验证命令

后端测试：

```bash
mvn -f backend/pom.xml test
```

前端检查与构建：

```bash
npm --prefix frontend/frontend run lint
npm --prefix frontend/frontend run build
```

完整参考部署验收：

```bash
./scripts/verify-container-deployment-loop.sh
```

## 项目目录

| 路径 | 内容 |
| --- | --- |
| `backend/` | 后端、Gateway 数据面、数据库迁移和测试 |
| `frontend/frontend/` | React 管理控制台 |
| `deploy/` | Nginx 代理和 Prometheus 配置 |
| `docs/` | 产品、架构、API/UI 契约、部署与测试报告 |
| `scripts/` | 各业务闭环和联合部署验收脚本 |
| `workflow/` | Workflow v4 的目标、任务、检查点和证据 |

更多资料：

- [文档导航](docs/README.md)
- [部署说明](docs/delivery/deployment.md)
- [OpenAPI 契约](docs/contracts/openapi.yaml)
- [系统测试报告](docs/delivery/system-test-report.md)
- [当前交付状态](workflow/STATE.md)

## 交付边界

当前证据覆盖单机参考栈，以及前端、后端、MySQL、Redis、Elasticsearch、Prometheus 和真实 HTTP 后端的联合链路。默认密码仅用于隔离的本地参考环境，不得复用到共享环境或生产环境。

在外部密钥托管、TLS、生产 RBAC、备份恢复、多节点高可用、滚动升级、容量与故障压测以及正式发布审批完成前，本项目不得作为生产部署上线。