# APIHUB

**Repository Path**: hashan/apihub

## Basic Information

- **Project Name**: APIHUB
- **Description**: 基于 RuoYi-Vue 二次开发的 API 开放平台，用来管理接口、维护接口文档与请求响应契约、给开发者发放 AK/SK 凭证，并通过动态网关完成签名鉴权、来源 IP 白名单校验和真实上游转发。
 这个仓库适合用来学习和实践一个 API 平台从“控制台管理”到“开发者调用”的完整链路：后台负责接口元数据、契约、用户和凭证；前台提供接口目录、接口文档和在线调试；网关负责承接正式外部调用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">API 服务平台</h1>

<p align="center"><strong>基于 RuoYi-Vue 二次开发的 API 开放平台</strong></p>

<p align="center">
  接口管理 · 契约文档 · 开发者凭证 · 签名鉴权 · 动态网关
</p>

<p align="center">
  <a href="http://www.ruoyi.vip/"><img alt="RuoYi-Vue" src="https://img.shields.io/badge/RuoYi--Vue-3.9.2-2f74c0?style=flat-square"></a>
  <img alt="Java" src="https://img.shields.io/badge/Java-17-007396?style=flat-square&logo=openjdk&logoColor=white">
  <img alt="Spring Boot" src="https://img.shields.io/badge/Spring%20Boot-4.0.6-6DB33F?style=flat-square&logo=springboot&logoColor=white">
  <img alt="Spring Cloud" src="https://img.shields.io/badge/Spring%20Cloud-2025.1.2-6DB33F?style=flat-square">
  <img alt="Dubbo" src="https://img.shields.io/badge/Dubbo-3.3.5-d22128?style=flat-square">
  <img alt="Vue" src="https://img.shields.io/badge/Vue-3.5-42b883?style=flat-square&logo=vuedotjs&logoColor=white">
  <img alt="Vite" src="https://img.shields.io/badge/Vite-6-646cff?style=flat-square&logo=vite&logoColor=white">
  <img alt="Element Plus" src="https://img.shields.io/badge/Element%20Plus-2-409eff?style=flat-square">
  <img alt="MySQL" src="https://img.shields.io/badge/MySQL-8.x-4479A1?style=flat-square&logo=mysql&logoColor=white">
  <img alt="Redis" src="https://img.shields.io/badge/Redis-6.x-dc382d?style=flat-square&logo=redis&logoColor=white">
  <img alt="Gateway" src="https://img.shields.io/badge/API%20Gateway-enabled-0f766e?style=flat-square">
  <img alt="AK/SK" src="https://img.shields.io/badge/AK%2FSK-HMAC--SHA256-7c3aed?style=flat-square">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat-square">
</p>

<p align="center">
  <a href="#功能特性">功能特性</a> ·
  <a href="#项目演示">项目演示</a> ·   
  <a href="#项目结构">项目结构</a> ·
  <a href="#快速开始">快速开始</a> ·
  <a href="#核心调用链">调用链</a> ·
  <a href="#安全说明">安全说明</a>
</p>



---

> 基于 RuoYi-Vue 二次开发的 API 开放平台，用来管理接口、维护接口文档与请求响应契约、给开发者发放 AK/SK 凭证，并通过动态网关完成签名鉴权、来源 IP 白名单校验和真实上游转发。
>
> 这个仓库适合用来学习和实践一个 API 平台从“控制台管理”到“开发者调用”的完整链路：后台负责接口元数据、契约、用户和凭证；前台提供接口目录、接口文档和在线调试；网关负责承接正式外部调用。
>

## 项目亮点

| 模块 | 能力 | 说明 |
| --- | --- | --- |
| 控制台 | 接口管理 | 基于 RuoYi 权限体系管理接口、用户、菜单、角色和 API 凭证 |
| 契约 | 文档驱动 | 使用结构化 JSON Schema 描述请求、响应和默认测试数据 |
| 门户 | 文档市场 | 面向开发者展示已上线接口目录与接口详情 |
| 网关 | 动态转发 | 统一承接外部调用，完成验签后转发到接口配置的真实上游 |
| 安全 | 调用保护 | 支持 AK/SK、HMAC-SHA256、timestamp、nonce 和来源 IP 白名单 |
| 开发 | 本地运行 | 管理端、前端、网关、示例接口服务都提供清晰的本地启动方式 |

## 功能特性

- **接口管理**：维护接口名称、HTTP 方法、公开路径、真实上游地址、状态、排序等基础信息。
- **接口契约**：使用 `interface_info` + `interface_contract` 两表保存接口元数据、Markdown 文档、请求 JSON Schema、响应 JSON Schema 和默认测试数据。
- **在线测试**：管理端可按保存的契约和默认请求测试接口连通性，并展示请求、响应和校验结果。
- **接口目录**：提供已上线接口列表与详情接口，后端列表和详情支持匿名访问。
- **在线调试**：接口详情页可发起调试请求，调试由平台后端代为调用上游服务，仍保留登录校验。
- **AK/SK 凭证**：为用户生成 AccessKey / SecretKey，SecretKey 使用 AES-256-GCM 加密存储，支持查看、轮换和管理员重置。
- **签名基础**：提供规范请求串、HMAC-SHA256 签名与验签逻辑。
- **动态网关**：Spring Cloud Gateway 接收外部请求，通过 Dubbo RPC 到管理端做预校验，再转发到接口配置的 `upstreamUrl`。
- **防重放与白名单**：网关校验 timestamp、nonce、签名和 AccessKey，可启用精确 IPv4 来源白名单。
- **RuoYi 基础能力**：保留用户、角色、菜单、权限、字典、参数、日志、Druid、Swagger UI 等后台能力。

## 项目演示

![1](./iamge/1.png)

![2](./iamge/2.png)

![3](./iamge/3.png)

![4](./iamge/4.png)

![5](./iamge/5.png)

![6](./iamge/6.png)

![7](./iamge/7.png)

![8](./iamge/8.png)

![9](./iamge/9.png)

![10](./iamge/10.png)

![11](./iamge/11.png)

![12](./iamge/12.png)


## 项目结构

```text
.
├── Backend/                 # RuoYi 后端多模块工程
│   ├── ruoyi-admin/         # 管理后台启动入口，端口 8080
│   ├── ruoyi-api/           # API 平台业务：接口、契约、凭证、白名单、网关 RPC
│   ├── ruoyi-api-rpc/       # 网关与管理端之间的 RPC 契约
│   ├── ruoyi-gateway/       # 动态 API 网关，端口 8090
│   ├── ruoyi-framework/     # RuoYi 框架层
│   ├── ruoyi-system/        # RuoYi 系统模块
│   ├── ruoyi-common/        # 通用工具模块
│   └── sql/                 # 数据库初始化与 API 平台扩展脚本
├── Frontend/                # Vue 3 + Vite + Element Plus 管理前端
├── api-client-sdk/          # 早期 Java SDK 示例工程
├── shan-interface/          # 示例接口服务，端口 8123
├── API开放平台笔记/          # 学习笔记
├── 参考源码/                 # 参考项目源码，不是主工程启动必需
└── API服务平台-OpenAPI接口管理与文档系统完整方案.md
```

## 技术栈

后端：

- Java 17
- Spring Boot 4.0.6
- Spring Cloud 2025.1.2
- Spring Cloud Gateway
- Apache Dubbo 3.3.5
- MyBatis + PageHelper
- MySQL 8.x
- Redis
- Druid
- Spring Security + JWT
- springdoc-openapi
- NetworkNT JSON Schema Validator

前端：

- Vue 3.5
- Vite 6
- Element Plus 2
- Pinia
- Vue Router 4
- Axios
- AJV JSON Schema Validator

## 环境要求

- JDK 17+
- Maven 3.9+
- Node.js 20+，npm 10+ 推荐
- MySQL 8.x
- Redis 6+
- Nacos 2.x，用于 Dubbo 注册中心

本地默认端口：

| 服务 | 端口 | 说明 |
| --- | --- | --- |
| 后端管理服务 | `8080` | RuoYi 管理端和 API 平台控制台接口 |
| 前端开发服务 | `80` | Vite 开发服务，代理 `/dev-api` 到 `8080` |
| API 网关 | `8090` | 正式开发者调用入口 |
| 示例接口服务 | `8123` | `shan-interface` 示例上游服务，context-path 为 `/api` |
| Redis | `6379` | 登录状态、缓存、nonce 防重放 |
| Nacos | `8848` | Dubbo 注册中心 |
| MySQL | `3306` | 默认数据库名 `apiservice` |

## 快速开始

### 1. 准备数据库

创建数据库：

```sql
create database apiservice
  default character set utf8mb4
  collate utf8mb4_unicode_ci;
```

按顺序导入脚本：

```text
Backend/sql/ry_20260417.sql
Backend/sql/quartz.sql
Backend/sql/interface_two_table_schema.sql
Backend/sql/interface_menu.sql
Backend/sql/api_user_credential.sql
Backend/sql/api_ip_whitelist.sql
```

说明：

- `ry_20260417.sql` 是 RuoYi 系统基础表。
- `quartz.sql` 是定时任务表。
- `interface_two_table_schema.sql` 会重建 `interface_info` 和 `interface_contract`，适合新库初始化。
- `interface_menu.sql` 写入接口管理菜单权限。
- `api_user_credential.sql` 写入 API 用户凭证表。
- `api_ip_whitelist.sql` 写入来源 IP 白名单表和菜单权限。
- `intrefase.sql`、`interface_request_params.sql` 属于旧版接口表脚本，新库一般不要再导入。

### 2. 修改后端配置

后端数据源在：

```text
Backend/ruoyi-admin/src/main/resources/application-druid.yml
```

默认配置：

```yaml
spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://localhost:3306/apiservice?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
        username: root
        password: root
```

Redis、Dubbo、网关和凭证配置在：

```text
Backend/ruoyi-admin/src/main/resources/application.yml
Backend/ruoyi-gateway/src/main/resources/application.yml
```

生产环境务必覆盖以下默认值：

```powershell
$env:API_CREDENTIAL_MASTER_KEY = "Base64 编码后的 32 字节密钥"
$env:API_GATEWAY_BASE_URL = "http://127.0.0.1:8090"
$env:API_GATEWAY_SIGNATURE_WINDOW_SECONDS = "300"
$env:API_GATEWAY_IP_WHITELIST_ENABLED = "true"
$env:API_GATEWAY_MAX_BODY_BYTES = "1048576"
$env:DUBBO_REGISTRY_ADDRESS = "nacos://127.0.0.1:8848"
```

`API_CREDENTIAL_MASTER_KEY` 必须是 Base64 字符串，解码后正好 32 字节。仓库里的默认值只用于本地开发，开源部署时不要直接用于生产。

### 3. 启动基础服务

先启动：

- MySQL
- Redis
- Nacos

Nacos 默认地址为：

```text
http://127.0.0.1:8848
```

### 4. 启动后端管理服务

```powershell
cd Backend
mvn -pl ruoyi-admin -am spring-boot:run
```

启动成功后访问：

```text
http://localhost:8080
```

Swagger UI：

```text
http://localhost:8080/swagger-ui.html
```

### 5. 启动 API 网关

另开一个终端：

```powershell
cd Backend
mvn -pl ruoyi-gateway -am spring-boot:run
```

网关启动后监听：

```text
http://localhost:8090
```

网关会接收外部请求，读取 `accessKey`、`sign`、`timestamp`、`nonce` 等请求头，通过 Dubbo 调用管理端的 RPC 服务进行验签、nonce 防重放、来源 IP 白名单和接口状态校验，然后转发到接口的真实上游地址。

### 6. 启动前端

```powershell
cd Frontend
npm install
npm run dev
```

前端开发服务默认端口为 `80`，访问：

```text
http://localhost
```

Vite 代理配置在 `Frontend/vite.config.js`，默认把 `/dev-api` 转发到 `http://localhost:8080`。

如果本机端口 `80` 已被占用，或者 Windows 普通权限无法监听该端口，可以把 `Frontend/vite.config.js` 中的 `server.port` 改成 `5173` 等未占用端口。

初始化 SQL 中的默认账号：

```text
账号：admin
密码：admin123
```

### 7. 可选：启动示例接口服务

```powershell
cd shan-interface
mvn spring-boot:run
```

示例服务默认地址：

```text
http://localhost:8123/api
```

可以在接口管理中把某个接口的 `upstreamUrl` 配置为示例服务地址，用于本地调试网关转发。

## 常用命令

后端测试：

```powershell
cd Backend
mvn -pl ruoyi-admin -am test
```

后端打包：

```powershell
cd Backend
mvn -pl ruoyi-admin -am package -DskipTests
```

网关打包：

```powershell
cd Backend
mvn -pl ruoyi-gateway -am package -DskipTests
```

前端生产构建：

```powershell
cd Frontend
npm run build:prod
```

## 核心调用链

### 管理端在线调试

```text
浏览器
  -> Frontend: ApiDebugPanel
  -> Backend: POST /open-api/interfaces/{slug}/debug
  -> PublicInterfaceController
  -> InterfaceInfoServiceImpl.debugPublishedInterface
  -> InterfaceInvokeUtils
  -> upstreamUrl
```

在线调试是平台后端代请求上游服务，不经过 `ruoyi-gateway`。它适合管理员或登录用户在文档页快速验证接口。

### 正式开发者调用

```text
开发者应用
  -> ruoyi-gateway:8090
  -> DynamicApiGatewayFilter
  -> Dubbo RPC: GatewayInvokeRpcService.preInvoke
  -> API 凭证验签 / nonce 防重放 / IP 白名单 / 接口状态查询
  -> upstreamUrl
  -> GatewayInvokeRpcService.afterInvoke
```

正式调用应由服务端应用保存 SecretKey 并完成签名。不要把 SecretKey 放进浏览器、本地存储或公开仓库。

## API 签名请求头

网关当前读取以下请求头：

| Header | 说明 |
| --- | --- |
| `accessKey` | 开发者访问标识 |
| `sign` | HMAC-SHA256 签名 |
| `timestamp` | 请求时间戳，秒或毫秒均可 |
| `nonce` | 一次性随机串，用于防重放 |

签名会覆盖：

- HTTP method
- public path
- query parameters
- request body
- timestamp
- nonce
- accessKey

具体规范请求串和签名实现见：

```text
Backend/ruoyi-api/src/main/java/com/ruoyi/api/signature/
```

## 安全说明

- `API_CREDENTIAL_MASTER_KEY` 默认值仅用于本地开发，生产必须替换。
- SecretKey 只应在受控查看、轮换或管理员重置时短暂返回，普通资料接口只展示脱敏值。
- 正式调用请把签名逻辑放在服务端，不要在浏览器暴露 SecretKey。
- 来源 IP 白名单是精确 IPv4 白名单，不支持 CIDR、通配符或域名。
- 网关的白名单校验依赖客户端 IP 提取。生产部署在反向代理后时，需要结合可信代理规则处理 `X-Forwarded-For`。
- `upstreamUrl` 是真实转发目标。生产环境建议补充 SSRF 防护、内网地址限制、重定向限制和 DNS 解析校验。
- 默认数据库账号、Token 密钥、Druid 账号等都应在部署前改为安全值。

## 开发入口

后台菜单：

- 接口管理：维护接口基本信息、契约、默认测试请求和发布状态。
- IP 白名单：维护允许调用网关的精确 IPv4 来源地址。
- 用户管理：管理员可重置用户 API 凭证。
- 个人中心：用户可查看 AccessKey、受控查看 SecretKey、轮换 SecretKey。

前端路由：

- `/index`：接口目录入口。
- `/api-market`：接口目录兼容入口。
- `/api-doc/:slug`：接口文档详情。

后端公开接口：

- `GET /open-api/interfaces`：已上线接口列表，匿名可访问。
- `GET /open-api/interfaces/{slug}`：接口详情，匿名可访问。
- `POST /open-api/interfaces/{slug}/debug`：在线调试，需要登录。

## 开源前建议

- 检查并移除本地日志、`target/`、`node_modules/`、`dist/` 等生成物。
- 确认没有提交真实数据库密码、Redis 密码、Token 密钥、Nacos 地址或生产凭证。
- 根目录可以补充统一 `LICENSE`；当前 Backend 和 Frontend 目录内已有 MIT License。
- 如果希望别人一键启动，后续可以补充 Docker Compose，把 MySQL、Redis、Nacos、后端、网关和前端统一编排。

## 许可证

本项目基于 RuoYi-Vue 二次开发，Backend 和 Frontend 目录内保留 MIT License。开源发布时请同时保留原项目版权声明，并根据你的发布范围补充根目录许可证文件。