闲暇时编写，问题较多，仅供参考。

Vert.x 快速开发模板

这是一个基于 Vert.x 库的后端快速开发模板，采用 Kotlin 语言和协程实现高性能异步编程。本项目提供了完整的开发框架，能够帮助开发者快速搭建响应式、模块化、高性能的后端服务。

技术栈

• 核心框架: Vert.x 4.5.x (响应式、事件驱动框架)
• 编程语言: Kotlin 1.9.x (协程支持)
• 依赖注入: Google Guice 7.0.0
• 数据库: PostgreSQL, (不支持MySQL)
• 缓存: Redis
• 认证: JWT
• 构建工具: Gradle with Kotlin DSL
• 代码规范: Spotless, ktlint

项目结构

项目采用模块化设计，主要分为两个模块：

vertx-fw (框架核心)

提供基础架构和通用功能:

• 依赖注入配置
• 路由管理
• 认证与授权
• 数据库操作封装
• 事务管理
• 全局异常处理
• 通用工具类

vertx-demo (应用示例)

包含示例应用代码:

• 控制器实现示例
• 服务层实现
• 数据访问层
• 实体类定义
• 配置文件

主要特性

1. 注解驱动的路由

通过简单的注解即可定义 API 路由和参数绑定:

@D("测试1:测试")
@Controller
class Demo1Controller @Inject constructor(
  private val accountService: AccountService,
  private val accountRepository: AccountRepository
) {

  @AllowAnonymous
  @D("参数测试", "详细说明......")
  suspend fun test1(
    @D("name", "姓名") name: String?,
    @D("age", "年龄") age: Int?,
    @D("list", "列表") list: List<String>?,
    @D("status", "状态-0正常,1禁用,2删除") status: Status?,
    @D("account", "账号") account: Account?
  ) {
    // 业务逻辑
  }
}

2. 据库支持

Repository 模式

interface AccountRepository : Repository<Long, Account> {
  suspend fun getByName(name: String): Account?
  suspend fun getUserList(userName: String?, phone: String?): List<Account>
}

事务管理

suspend fun testTransaction() {
  withTransaction {
    accountRepository.update(1L, mapOf("avatar" to "test0001"))
    
    // 嵌套事务
    try {
      withTransaction {
        accountRepository.update(1L, mapOf("avatar" to "test002"))
        throw Meta.error("test transaction", "test transaction")
      }
    } catch (e: Exception) {
      logger.info { "内层事务失败已处理: ${e.message}" }
    }
  }
}

数据库迁移

支持通过实体类注解自动生成数据库变更脚本，遵循版本化管理。

3. 安全与认证

• JWT 认证
• 基于角色的权限控制
• 自定义安全注解: @AllowAnonymous, @CheckRole, @CheckPermission

4. API 文档生成

自动生成 OpenAPI 规范文档，支持与 ApiFox 等 API 工具集成。

5. 统一响应处理

标准化的 JSON 响应格式:

{
  "code": 200,
  "message": "Success",
  "data": { ... },
  "requestId": "1899712678486753280"
}

6. 全局异常处理

统一捕获和处理异常，转换为友好的 API 响应。

7. 配置管理

支持 YAML 配置，环境变量和系统属性覆盖，多环境配置。

快速开始

环境要求

• JDK 17+
• PostgreSQL 数据库
• Redis (可选)

构建与运行

1. 克隆项目

git clone https://github.com/yourusername/vertx-pj.git
cd vertx-pj

2. 配置数据库

编辑 vertx-demo/src/main/resources/config/application-database.yml

databases:
  name: vertx-demo
  host: 127.0.0.1
  port: 5432
  username: your_username
  password: your_password

3. 构建项目

./gradlew clean build

4. 运行项目

./gradlew :vertx-demo:run

创建新API

1. 创建实体类

@TableName("users")
class User : BaseEntity() {
  @TableId(type = IdType.ASSIGN_ID)
  var userId: Long = 0L
  
  @TableField("user_name")
  var userName: String? = ""
  
  var status: Status? = Status.ACTIVE
}

2. 创建Repository

interface UserRepository : Repository<Long, User> {
  suspend fun findByName(name: String): User?
}

3. 创建Service

class UserService @Inject constructor(
  private val userRepository: UserRepository
) {
  suspend fun getUserByName(name: String): User? {
    return userRepository.findByName(name)
  }
}

4. 创建Controller

@D("用户管理")
@Controller("/users")
class UserController @Inject constructor(
  private val userService: UserService
) {
  @D("通过用户名获取用户")
  suspend fun getByName(
    @D("name", "用户名") name: String
  ): User? {
    return userService.getUserByName(name)
  }
}

---

快速开发注解说明

@AllowAnonymous

允许匿名访问注解 标记在Controller类上时，表示该类下所有接口都不需要鉴权。 标记在Controller类中的方法上时，表示该接口不需要鉴权。

@Controller

自定义Controller注解，用于路由注册

• 启动时使用反射获取所有标记了@Controller注解的类
• 获取类中所有方法，将其统一注册到router中
• 可选参数prefix：定义请求路径前缀
  • 不填时默认使用类名(去除"Controller"后首字母小写)作为前缀

@D

文档生成注解，可用于以下位置：

1. 类上：为Controller类添加说明
2. 方法上：为方法添加说明
3. 方法参数上：格式如 @D("age", "年龄") age: Int?
   • name: 参数名，用于从query或body中自动获取参数
   • value: 参数说明，用于文档生成

注：参数类型后的?表示可为空，不带?表示必填。框架会根据此进行参数校验。

权限相关注解

仿sa-token实现的权限控制：

• @CheckRole()：角色检查
• @CheckPermission()：权限检查

请求响应相关注解

@CustomizeRequest

请求方式定制

• 全局默认使用POST请求
• 使用@CustomizeRequest("get")可将方法改为GET请求

@CustomizeResponse

响应方式定制

• 全局默认返回JSON格式
• 使用@CustomizeResponse可获取response对象自定义返回内容