255 lines
6.0 KiB
Markdown
255 lines
6.0 KiB
Markdown
# Vertx-pj 说明
|
||
|
||
基于vert.x的web开发框架，提供了一些简单的封装，使得开发更加便捷。<br/>
|
||
**写的简单，问题不少，仅供参考**。
|
||
- **vertx-fw**: 简单封装的web开发框架
|
||
- **vertx-demo**: 使用vertx-fw开发的demo
|
||
|
||
### 项目介绍
|
||
|
||
#### 技术栈
|
||
- **框架**: Vert.x 4.x (响应式异步框架)
|
||
- **语言**: Kotlin + 协程
|
||
- **数据库**: PostgreSQL + Vert.x PgClient
|
||
- **DI**: Google Guice
|
||
- **认证**: JWT + 角色权限体系
|
||
- **工具库**: Hutool(工具包)、mu(日志)、jackson(序列化)
|
||
- **文档**: OpenAPI 3.0 + Apifox集成
|
||
|
||
#### 设计
|
||
```
|
||
├── Application (入口)
|
||
├── Verticles
|
||
│ ├── MainVerticle (主部署器)
|
||
│ └── WebVerticle (WEB服务)
|
||
├── Config
|
||
│ ├── JWT认证
|
||
│ └── 依赖注入配置
|
||
├── Controller (接口层)
|
||
├── Service (业务层)
|
||
├── Repository (数据层)
|
||
└── Domain (领域模型)
|
||
```
|
||
|
||
#### 核心特性
|
||
1. **全异步架构**：基于Vert.x事件循环和Kotlin协程
|
||
2. **自动路由注册**：通过注解自动映射REST接口
|
||
3. **声明式事务**：通过withTransaction函数管理事务
|
||
4. **RBAC权限控制**：支持角色+权限双重验证
|
||
5. **智能参数解析**：自动处理路径/查询/表单/JSON参数
|
||
6. **全链路日志**：包含请求ID、用户上下文、耗时预警
|
||
7. **代码生成**：Repository自动生成基础SQL
|
||
|
||
---
|
||
|
||
### 使用说明
|
||
|
||
#### 1. 快速启动
|
||
```kotlin
|
||
// 配置application.yaml
|
||
server:
|
||
name: vtx_demo
|
||
port: 8080
|
||
context: api
|
||
package: app
|
||
|
||
jwt:
|
||
key: 123456sdfjasdfjl
|
||
|
||
databases:
|
||
name: vertx-demo
|
||
host: 127.0.0.1
|
||
port: 5432
|
||
username: root
|
||
password: 123456
|
||
|
||
redis:
|
||
host: 127.0.0.1
|
||
port: 6379
|
||
database: 0
|
||
password: xxx
|
||
maxPoolSize: 8
|
||
maxPoolWaiting: 2000
|
||
|
||
apifox:
|
||
token: APS-xxxxxxxxxxxxxxx
|
||
projectId: xxxxxx
|
||
folderId: xxxxxx
|
||
```
|
||
|
||
#### 2. 创建Controller
|
||
```kotlin
|
||
@Controller("/user")
|
||
class UserController @Inject constructor(
|
||
private val userService: UserService
|
||
) {
|
||
@D("获取用户详情")
|
||
@CheckRole("admin", mode = Mode.OR) // 权限控制
|
||
suspend fun getDetail(
|
||
ctx: RoutingContext,
|
||
@D("userId") userId: Long
|
||
): User {
|
||
return userService.getDetail(userId)
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. 定义Service
|
||
```kotlin
|
||
class UserService @Inject constructor(
|
||
private val snowflake: Snowflake,
|
||
private val userRepository: UserRepository
|
||
) {
|
||
suspend fun createUser(dto: UserDTO): Long {
|
||
return userRepository.create(dto.toEntity(snowflake))
|
||
}
|
||
|
||
suspend fun batchUpdate(ids: List<Long>) {
|
||
withTransaction() {
|
||
ids.forEach { id ->
|
||
userRepository.update(id, mapOf("status" to 1))
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4. 实现Repository
|
||
```kotlin
|
||
@ImplementedBy(UserRepositoryImpl::class)
|
||
interface UserRepository : Repository<Long, User> {
|
||
suspend fun findByEmail(email: String): User?
|
||
}
|
||
|
||
@Singleton
|
||
class UserRepositoryImpl @Inject constructor(sqlClient: SqlClient)
|
||
: RepositoryImpl<Long, User>(sqlClient), UserRepository {
|
||
|
||
override suspend fun findByEmail(email: String): User? {
|
||
return queryBuilder()
|
||
.eq(User::email, email)
|
||
.getOne()
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5. 数据库实体
|
||
```kotlin
|
||
@TableName("sys_user")
|
||
data class User(
|
||
@TableId(type = IdType.ASSIGN_ID)
|
||
@TableField("user_id")
|
||
val userId: Long = 0,
|
||
|
||
@TableField("user_name")
|
||
val userName: String,
|
||
|
||
@TableField(fill = FieldFill.INSERT)
|
||
val createTime: LocalDateTime = LocalDateTime.now()
|
||
)
|
||
```
|
||
|
||
#### 6. 运行与测试
|
||
```bash
|
||
# 启动应用
|
||
gradle run
|
||
|
||
# 生成的API文档
|
||
http://localhost:8080/api/docs
|
||
|
||
# 示例请求
|
||
POST /api/auth/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"username": "admin",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 高级功能
|
||
|
||
#### 事务管理
|
||
```kotlin
|
||
suspend fun transfer(from: Long, to: Long, amount: Double) {
|
||
withTransaction {
|
||
accountRepository.deductBalance(tx, from, amount)
|
||
accountRepository.addBalance(tx, to, amount)
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 复杂查询
|
||
```kotlin
|
||
val users = queryBuilder()
|
||
.like(User::name, "%张%")
|
||
.between("create_time", start, end)
|
||
.orderByDesc("user_id")
|
||
.getList()
|
||
```
|
||
|
||
#### 自定义响应
|
||
```kotlin
|
||
@CustomizeResponse
|
||
suspend fun customResponse(): RespBean {
|
||
return RespBean.success("自定义格式")
|
||
}
|
||
```
|
||
|
||
#### 权限配置
|
||
```kotlin
|
||
@CheckRole(value = ["admin", "supervisor"], mode = Mode.OR)
|
||
@CheckPermission(value = ["user:write", "user:update"])
|
||
suspend fun sensitiveOperation() {
|
||
// 需要admin或supervisor角色
|
||
// 且拥有user:write或user:update权限
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开发注解说明
|
||
|
||
### @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对象自定义返回内容
|