tomevault-io Handler Transformer（处理器转换器）
当用户需要创建新的 HTTP API 接口时，使用 handler-transformer 通过 DSL 生成 Controller + Service + DTO 代码。
前置条件
确保用户项目的 pom.xml 包含 Allison1875 Maven 插件配置。如果缺失，先添加：
<plugin>
<groupId>com.spldeolin.allison1875</groupId>
<artifactId>allison1875-maven-plugin</artifactId>
<version>${allison1875.version}</version>
<configuration>
<common>
<basePackage>用户项目的根包</basePackage>
<author>作者名</author>
</common>
<handlerTransformer>
<pageTypeQualifier>分页包装类的全限定名</pageTypeQualifier>
<enableOneService>false</enableOneService>
</handlerTransformer>
</configuration>
</plugin>
还需要添加 support 依赖：
<dependency>
<groupId>com.spldeolin.allison1875</groupId>
<artifactId>allison1875-support</artifactId>
<version>${allison1875.version}</version>
</dependency>
执行步骤
第一步：在 Controller 中编写 DSL
在现有的 @RestController 或 @Controller 类中插入实例初始化代码块 { ... }。
DSL 模板：
{
String handler = "方法名", desc = "接口描述";
class req {
/**
* 字段说明（会成为 Javadoc）
*/
@NotNull // JSR-303 注解会保留
String fieldName;
// 嵌套类会生成嵌套 DTO
class nestedObject {
String nestedField;
}
}
// @P 表示分页返回，@L 标注在嵌套类上表示 List 字段
@P
class resp {
String userId;
@L
class items {
String itemName;
}
}
}
DSL 规则速查：
| 元素 | 说明 |
|---|---|
String handler = "methodName" 或 String h = "methodName" |
方法名和 URL 路径 |
String desc = "描述" 或 String d = "描述" |
JavaDoc 描述 |
class req { ... } |
请求体 DTO 字段定义 |
class resp { ... } |
响应 DTO 字段定义 |
@P 标注在 resp 上 |
响应包装为分页类型 |
@L 标注在嵌套 class 上 |
字段变为 List<XxxDTO> |
字段默认值如 int pageSize = 20 |
保留在生成的 DTO 中 |
| 字段上的 Javadoc 注释 | 保留为 DTO 字段的 Javadoc |
完整示例：
@RestController
@RequestMapping("/users")
public class UserController {
{
String handler = "listUsersAsPage", desc = "获取学生分页列表";
class req {
/**
* 学校名称，模糊匹配，非必填
*/
String schoolName;
/**
* 地区
*/
class address {
String province;
String city;
}
@NotNull
int pageNum;
@NotNull
int pageSize = 20;
}
@P
class resp {
String userId;
String userName;
@L
class address {
String province;
String city;
}
}
}
}
第二步：执行 Maven 命令
mvn allison1875:handler-transformer
生成结果
Controller 方法（DSL 代码块被替换）：
@PostMapping("listUsersAsPage") public ApiBaseResult<PageResult<ListUsersAsPageResp>> listUsersAsPage( @RequestBody @Valid ListUsersAsPageReq req) { return ApiBaseResult.successRet(userService.listUsersAsPage(req)); }请求 DTO：
ListUsersAsPageReq.java响应 DTO：
ListUsersAsPageResp.java嵌套 DTO：
AddressDTO.java（如有嵌套类）Service 接口方法
Service 实现方法（返回 null，用户填充业务逻辑）
故障排查
| 问题 | 解决方案 |
|---|---|
| 命令失败提示 "plugin not found" | Allison1875 未发布到 Maven Central，需要用户克隆仓库并运行 mvn install -DskipTests |
| DSL 代码块没有被识别 | 确保是实例初始化代码块（不是 static 块），且类有 @RestController 或 @Controller 注解 |
| 生成代码使用 javax.validation | 在 <common> 中设置 <enableJavaxMoveToJakarta>true</enableJavaxMoveToJakarta> |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.