# vertx-gateway-template

**Repository Path**: fan_gitee_develop/vertx-gateway-template

## Basic Information

- **Project Name**: vertx-gateway-template
- **Description**: 这不是一个框架，而是一个基于 Vert.x 的 OpenAPI 服务模板，用于快速构建微服务网关
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2025-06-11
- **Last Updated**: 2025-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vertx-gateway-template

这不是一个框架，而是一个基于 [Vert.x](https://vertx.io) 的 OpenAPI 服务模板，用于快速构建微服务网关。充分利用 Vert.x
的响应式特性，提供高性能的
OpenAPI 服务。相比于其他的 Java 的多线程微服务框架，Vert.x 的性能更高，更轻量，更灵活，更易于扩展。

**关键是服务启动时间是毫秒级的！**

## Vert.x 的性能介绍

相比于其他的 Java 框架，甚至是其他编程语言的框架，Vert.x
的性能都是遥遥领先的，请看来自 [TechEmpower](https://www.techempower.com/benchmarks/#section=data-r21&hw=cl&test=composite&l=cmh5z1)
的综合性能比较结果：

![techmpower benchmark](docs/benchmark.jpg)

这里有一篇文章详细介绍了 [《Vert.x 为什么高性能》](https://juejin.cn/post/7072568803942465549) 。

## 为什么要搞这个模板

那么为什么要搞这么一个模板项目呢？因为 Vert.x 只是一个库，并非框架，也就是说不同人使用 Vert.x
写出来的应用风格五花八门，没有统一的规范。这个模板项目就是为了解决这个问题，它提供了一些基础的功能，让你可以快速的构建一个微服务网关。

该模板主要包括：

- 根据配置加载微服务
- 自动化分布式集群配置
- 引入 jdbi 简化数据库访问（因为响应式的数据库访问方法实在很难受）
- openapi 3.0 规范的接口文档自动映射 Handler
- 封装了接口的限流能力
  ([HelloHandler.java#serviceTest](gateway/src/main/java/com/gitee/gateway/handlers/HelloHandler.java))

## 目录及文件说明

- [config] - 配置文件目录，包含了微服务的配置文件(核心服务、微服务定义、数据库、集群等配置)
- [core] - 核心模块，包含了基础服务启动、集群配置、数据库连接管理、缓存等功能
- [services] - 微服务模块，包含了多个微服务的代码
- [services/openapi] - openapi 服务模块，对外提供 OpenAPI 的 HTTP 访问入口
- [services/demo] - 一个最简单的微服务模块，用于演示如何编写微服务
- [gateway] - 业务代码，一般业务相关的代码都在这里
- [frontend/swagger] 存放了前端的 swagger-ui 代码，用于展示 OpenAPI 文档
- start.sh (start.bat) 服务启动脚本

## Requirements

1. Git
3. Java 21+
4. Maven 3.8.x
5. Vert.x 4.x
6. jdbi 3.x

## 开发说明

业务代码统一放到 [gateway] 模块中，微服务代码统一放到 [services] 模块中。[gateway] 包含一个最简单的接口示例。

### 1. 编写接口处理

首先在 [openapi.yaml](gateway/src/main/resource/openapi.yaml) 中定义接口。 这是 OpenAPI 接口定义文件，其中特别重要的部分是
operationId
的值，该值的格式形如 [category].[action]

你需要在 [Handlers.java](gateway/src/main/java/com/gitee/gateway/handlers/Handlers.java) 的 handle
方法中定义对 [catagory]
的处理类，一般为 [Catagory]Handler，然后在该类中的 mapping 方法定义 [action]
的相应处理方法，具体请参考 [HelloHandler.java](gateway/src/main/java/com/gitee/gateway/handlers/HelloHandler.java)。

### 2. 编写微服务

微服务代码统一放到 [services] 模块中，每个微服务都是一个单独的模块，模块名一般为 [service-xxx]，其中 xxx 为微服务的名称。

具体请参考 [services/demo]
模块。请特别主意源码中的 [package-info.java](services/demo/src/main/java/com/gitee/gateway/demo/package-info.java)
文件，Vert.x 根据这个文件来给微服务生成服务代理类，以便调用该服务。

### 3. 编写数据库访问方法

本模板使用 [jdbi](https://jdbi.org)
库进行数据库读写，同时模板已经内置了一些缓存的注解，具体使用请参考 [DemoDao.java](gateway/src/main/java/com/gitee/gateway/dao/DemoDao.java)。

其中涉及到数据库记录与 Bean 类的映射，请参考 [DemoBean.java](gateway/src/main/java/com/gitee/gateway/bean/DemoBean.java)。

### 4. 用户鉴权

基于 [UserAuthHandler.java](gateway/src/main/java/com/gitee/gateway/UserAuthHandler.java) 完善基于 Token 的用户鉴权机制。

## 集群部署

将 [server.yaml](config/server.yaml) 中的 `cluster/enabled` 值修改为 true 即可启用集群模式，默认使用 hazelcast
集群解决方案，详细的集群行为配置请看 [hazelcast.yaml](config/hazelcast.yaml)。

在多个节点上，每个节点的配置都用启用集群模式，你可以在 [services.yaml](config/services.yaml) 决定每个节点运行什么微服务，然后启动服务即可。
例如在本例中你可以将 openapi 服务跑在 A 机器上，把 demo 服务跑在 B 机器上。

## 服务启动

启动前请使用 Maven 编译项目：

```shell
mvn clean package
```

本模板提供了服务启动脚本 start.sh 或者 start.bat，利用 -d 参数可以使用守护模式启动服务。

```shell
./start.sh -d
```

测试接口：

- http://localhost:8080/swagger/  OpenAPI 接口文档
- http://localhost:8080/v1/hello/xxxxx  Hello xxxxx
- http://localhost:8080/v1/hello/db  数据库测试
- http://localhost:8080/v1/hello/service  微服务测试(支持访问限流)