# openapi-gateway

**Repository Path**: chuangchidong/openapi-gateway

## Basic Information

- **Project Name**: openapi-gateway
- **Description**: 将 HTTP / MQ（规划中：WebService、ESB、SAP、MQTT）等多协议按照配置接入，映射到同一套责任链管道与业务处理器；
实现一同套处理逻辑，多个接入的适配
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# openapi-gateway 对外集成服务网关

配置驱动的企业对外集成网关：以「开放接口」为路由单元，将 HTTP / MQ（规划中：WebService、ESB、SAP、MQTT）等多协议接入统一收口到同一套责任链管道与业务处理器（Handler），服务与接口全部落库、界面可管、启停即时生效。

## 核心特性

- **两级模型（v3）**：服务（`itg_service_def`）1:N 开放接口（`itg_service_endpoint`）。接口承载协议、路径、报文格式；一个服务可同时暴露 HTTP + MQ 等多个接口，接口即启停/路由/鉴权的管理单元
- **统一路由键**：对外统一走 `POST /gateway/{endpointCode}`；对接方地址写死的场景可给接口配置**自定义开放路径**（如 `/wms/stock/sync`），运行时动态注册/注销，无需重启
- **协议适配 + 责任链**：协议适配器把报文归一为 `MessageContext`，经鉴权（order=100）→ 限流（order=200）等管道节点后分发到业务 Handler；Handler 通过 `@IntegrationHandlerMapping(endpointCode = "xxx")` 一行注解挂载，业务代码不感知协议
- **响应格式渲染**：按接口配置的 `responseFormat` 输出 JSON / XML（含 SOAP、IDOC_XML），HTTP 状态码按业务码映射（限流返回 **409**，其余默认 200 + 业务码）
- **HTTP 限流（v4 阶段1）**：维度 接口 × 接入方（均支持 `*` 通配），匹配优先级 精确 > 仅接口 > 仅接入方 > 全局兜底；令牌桶/固定窗口实现，`RateLimitStore` 抽象为 Redis 集群化预留
- **配置热更新**：全量配置进内存快照，30 秒定时刷新 + 管理端变更即时刷新，启停/改配无需发版
- **调用日志**：每次调用落 `itg_invoke_log`（endpointCode、开放路径、耗时、错误码等），管理页可查
- **管理端**：Vue3 + Element Plus（本地化静态资源，无需外网），服务管理 / 开放接口 / 限流规则 / 调用日志四个页签

## 技术栈

| 项 | 版本/说明 |
|---|---|
| JDK | 17 |
| Spring Boot | 3.2.5 |
| MyBatis-Plus | 3.5.7（逻辑删除 `deleted`） |
| MySQL | 8.x（库名 `openapi`） |
| 构建 | Maven（fat jar，Spring Boot 插件打包） |

## 快速开始

### 1. 初始化数据库

按版本顺序执行 `docs/` 下的 DDL（幂等，可重复执行）：

```bash
mysql -u<user> -p openapi < docs/ddl-itg-v2.sql      # 基础表
mysql -u<user> -p openapi < docs/ddl-itg-v2.1.sql    # 自定义路径
mysql -u<user> -p openapi < docs/ddl-itg-v3.sql      # 两级模型迁移（含存量数据平移）
```

### 2. 构建与启动

```bash
mvn -q package -DskipTests
java -jar target/openapi-gateway.jar
```

数据库连接全部走环境变量（无硬编码凭据）：

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `MYSQL_HOST` | 127.0.0.1 | 数据库地址 |
| `MYSQL_PORT` | 3306 | 数据库端口 |
| `MYSQL_DB` | openapi | 库名 |
| `MYSQL_USER` | workbuddy | 用户名 |
| `MYSQL_PASSWORD` | （必填） | 密码 |
| `LOG_FILE` | /root/workbuddy/logs/openapi-gateway.log | 日志文件 |

启动后：健康检查 `GET /gateway/health`，管理端 `http://<host>:8080/admin/index.html`。

## 接入方式

**统一入口**（服务编码兜底路由到该服务的可用接口）：

```bash
curl -X POST http://<host>:8080/gateway/LES_STOCK_SYNC \
  -H "Content-Type: application/json" \
  -H "appKey: your-app" \
  -H "X-Trace-Id: optional-trace-id" \
  -d '{"stockList":[{"matCode":"MAT001","qty":10}]}'
```

**自定义开放路径**（接口配置 `servicePath` 后，对接方按写死地址直调）：

```bash
curl -X POST http://<host>:8080/wms/stock/sync ...
```

应答体统一为 `{code, message, traceId, data}`；配置 `responseFormat=XML` 时返回 XML。

## 业务处理器接入

```java
@Component
@IntegrationHandlerMapping(endpointCode = "LES_STOCK_SYNC")
public class StockSyncSampleHandler implements IntegrationHandler {
    @Override
    public Object handle(MessageContext context) {
        // context.getBody() 已归一为 Map，不感知来源协议
        return Map.of("received", true);
    }
}
```

一个服务多个接口可路由到不同 Handler，也可共用；新增 Handler 无需改任何框架代码。

## 错误码

| 码 | 含义 | HTTP |
|---|---|---|
| 0000 | 成功 | 200 |
| A0210 | 请求频率超限（限流） | **409** |
| A0301 / A0302 | 鉴权失败 / 验签失败 | 200 |
| A0400 | 请求参数错误 | 200 |
| B0101 ~ B0107 | 服务/接口不存在、停用、协议不匹配等 | 200 |
| B0001 | 系统内部异常 | 200 |

## 运维脚本（deploy/）

| 脚本 | 用途 |
|---|---|
| `upload.sh` | 本机上传（`./upload.sh jar` / `./upload.sh sql`），rsync + md5 校验 + 重试 |
| `db-update.sh` | 数据库增量更新：SQL 放 `deploy/sql/`（按日期命名），执行后自动登记历史、已执行跳过 |
| `deploy-jar.sh` | 发版：jar 校验 → 停服 → 备份（保留 5 份）→ 换包 → 启动 → 健康检查 |

发版顺序：**先 `db-update.sh` 后 `deploy-jar.sh`**（DDL 先行，新代码所需表结构就位后再换包，无窗口期；回滚只需换回备份 jar）。

## 目录结构

```
src/main/java/com/zhidong/zhang/openapi/
├── adapter/http/        # HTTP 入口（统一入口 + 动态路径注册）
├── admin/               # 管理端 REST API
├── common/              # 枚举（ResultCode/ProtocolType...）、模型、工具
├── core/
│   ├── adapter/         # MQ 消费 SPI（RabbitMQ 实现开发中）
│   ├── config/          # ServiceConfig / EndpointConfig / RateLimitConfig 等配置模型
│   ├── context/         # MessageContext 统一报文上下文
│   ├── dispatcher/      # GatewayDispatcher 统一分发（路由校验 + 管道编排）
│   ├── handler/         # IntegrationHandler SPI 与注解
│   ├── pipeline/        # 责任链管道
│   ├── ratelimit/       # 限流抽象（Store/Decision）
│   ├── registry/        # HandlerRegistry（endpointCode → Handler）
│   └── repository/      # ConfigRepository 配置快照接口
├── infra/               # 落地实现（DB 仓储、限流节点、审计落库）
└── sample/              # 示例（鉴权节点、库存同步 Handler）
```

## 设计文档

- [docs/design-itg-v3-endpoint.md](docs/design-itg-v3-endpoint.md) — 服务-开放接口两级模型
- [docs/design-v4-ratelimit-rabbitmq.md](docs/design-v4-ratelimit-rabbitmq.md) — 限流 / RabbitMQ 接入 / 幂等
- [docs/design-v4.3-idempotent.md](docs/design-v4.3-idempotent.md) — 幂等节点（messageId 去重）详设
- [docs/roadmap-2026-09.md](docs/roadmap-2026-09.md) — 路线图

## Roadmap

- [x] v3 服务/开放接口两级模型 + 动态路径 + 响应格式渲染
- [x] v4 阶段1 HTTP 限流（409 + 管理端规则页）
- [x] v4 阶段2 RabbitMQ 消费接入（动态订阅、手动 ack、重试 + 死信）——已上线验证
- [ ] v4 阶段3 幂等节点（messageId 去重，防 MQ 重投风暴）——设计完成，待编码
- [ ] 多实例：限流/幂等切 Redis + Lua、MQ 共享订阅