打造 Java Spring Boot 标准化 API ： 告别请求、响应重复造轮子！ResultVO + RequestVO

告别重复造轮子！ResultVO + RequestVO 打造 Spring Boot 标准化 API 设计体系

前言：每个 Java 项目都在重复的那件事

打开任何一个 Spring Boot 项目的 common 包，你大概率会看到这样的代码：

public class Result<T> {
private Integer code;
private String message;
private T data;
// 省略 getter/setter…
public static <T> Result<T> success(T data) { ... }
public static <T> Result<T> error(String msg) { ... }
}

每个团队都在写，字段名却各不相同：有的叫 code，有的叫 retCode；有的分页数据嵌套在 data 里，有的平铺在顶层。前后端联调时，接口文档写的是 data.list，前端拿到的却是 data.records——这类低效沟通，几乎每天都在发生。

更麻烦的是请求参数的解析：Controller 里 @RequestParam、@RequestBody、@PathVariable 各自为政，遇到 XML、FormData、文件上传，又得重新写一套解析逻辑。

ResultVO + RequestVO 就是为了解决这两个问题而生的。它们一起构成了一个完整的 API 设计规范：

• ResultVO：统一响应结构，支持状态码自适应（Integer/String）、字段名可配置、分页平铺
• RequestVO：统一请求封装，支持 JSON/Form/FormData/XML/二进制流全类型，提供嵌套路径取值、对象自动转换

本文将以实际项目场景为线索，带你彻底搞懂这套 API 设计体系。

一、ResultVO：统一响应，一套规范走天下

1.1 核心设计

ResultVO 的响应结构只有 4 个字段，简洁但够用：

{
"code": 200,
"msg": "成功",
"data": { … },
"pager": { "page": 1, "pageSize": 10, "total": 100, "totalPages": 10 }
}

两个关键设计点：

1.2 快速上手：suc / fail 全系列

ResultVO 提供丰富的静态方法，覆盖几乎所有响应场景：

// ========== 成功响应 ==========

// 无数据成功（默认 code=200, msg="成功"）
ResultVO<Void> res1 = ResultVO.suc();

// 仅自定义消息（无数据）
ResultVO<Void> res2 = ResultVO.sucMsg("操作成功");

// 携带数据
ResultVO<User> res3 = ResultVO.suc(user);

// 携带数据 + 分页
ResultVO<List<User>> res4 = ResultVO.suc(userList, pager);

// 自定义状态码 + 消息
ResultVO<User> res5 = ResultVO.suc(201, "创建成功", user);

// ========== 失败响应 ==========

// 默认失败（code=500, msg="失败"）
ResultVO<Void> err1 = ResultVO.fail();

// 仅自定义消息
ResultVO<Void> err2 = ResultVO.fail("用户名不能为空");

// 自定义状态码 + 消息
ResultVO<Void> err3 = ResultVO.fail(400, "参数错误");

// 携带错误数据（如校验失败字段）
ResultVO<Map<String, Object>> err4 = ResultVO.failData(errorMap);

方法命名约定（看名字就知道用途）：

1.3 业务状态码管理：ResultMessage 接口

当项目变复杂后，状态码不能散落在业务代码里。ResultMessage<C> 接口让你统一管理所有业务状态码：

// 定义业务错误枚举，实现 ResultMessage 接口（String 类型的状态码）
public enum BizError implements ResultMessage<String> {
SUCCESS("200", "成功"),
ORDER_NOT_FOUND("SYS_ORDER_404", "订单不存在"),
STOCK_INSUFFICIENT("SYS_STOCK_500", "库存不足"),
USER_DISABLED("SYS_USER_403", "用户已禁用");

private final String code;
private final String message;

BizError(String code, String message) {
this.code = code;
this.message = message;
}

@Override
public String getCode() { return code; }

@Override
public String getMessage() { return message; }
}

使用时，直接把枚举传给 ResultVO，无需每次手写状态码：

// 成功
return ResultVO.suc(BizError.SUCCESS);
// 失败
return ResultVO.fail(BizError.ORDER_NOT_FOUND);
// 失败 + 携带数据
return ResultVO.failData(BizError.STOCK_INSUFFICIENT, orderInfo);

内置默认状态码（DefaultResultMessage）已覆盖常用 HTTP 状态：

1.4 字段名自定义：适配不同团队的规范

有些团队要求返回 retCode 而不是 code，有些要求 body 而不是 data。不需要改源码，只需实现 ResultFieldMapping 接口并注入 Spring：

@Component
public class BankFieldMapping implements ResultFieldMapping {
@Override public String getCodeFieldName() { return "retCode"; }
@Override public String getMsgFieldName() { return "retMsg"; }
@Override public String getDataFieldName() { return "body"; }
@Override public String getPagerFieldName() { return "pageInfo"; }
}

配置生效后，原本返回：

{"code": 200, "msg": "成功", "data": {…}}

自动变为：

{"retCode": 200, "retMsg": "成功", "body": {…}}

全局生效，无需修改任何 Controller 代码。 这对多项目/多团队协作非常实用。

1.5 Pager 分页：与 Vue 生态完美对齐

Pager 对象与 data 平级返回，前端拿到的结构一目了然：

{
"code": 200,
"msg": "成功",
"data": […],
"pager": {
"startRow": 0,
"endRow": 10,
"page": 1,
"pageSize": 10,
"total": 100,
"totalPages": 10
}
}

Pager 提供以下字段：

setTotal() 会自动计算总页数：

Pager pager = new Pager();
pager.setPage(1);
pager.setPageSize(20);
pager.setTotal(95); // 自动计算 totalPages = 5

二、RequestVO：一个对象搞定所有请求类型

2.1 核心设计

RequestVO 配合 @RequestVo 注解，将 HTTP 请求数据自动注入到 Controller 方法参数中。它的设计哲学是：不管前端用什么 Content-Type，后端用同一套 API 取参数。

支持的请求类型：

2.2 快速上手

@RestController
public class UserController {

@PostMapping("/user")
public ResultVO<?> createUser(@RequestVo RequestVO vo) {
// 单值参数（类型自动转换）
String name = vo.getStr("name");
Integer age = vo.getInt("age");
Long uid = vo.getLong("uid");
Boolean vip = vo.getBoolean("vip");

// 数组参数（逗号分隔自动拆分）
String[] tags = vo.getStrArray("tags");
Long[] ids = vo.getLongArray("ids");

// 整体转换为 JavaBean
User user = vo.toBean(User.class);

// 获取分页
Pager pager = vo.getPager();

return ResultVO.suc(user);
}
}

2.3 请求头：三种方式

// 1. 获取请求头对象
RequestHeader header = vo.getHeader();
String auth = header.get("Authorization");

// 2. 直接获取指定请求头（更简洁）
String auth = vo.getHeader("Authorization");

// 3. 获取所有请求头
Map<String, String> allHeaders = vo.getHeaders();

2.4 类型安全取值：get 方法家族

RequestVO 提供完整的类型安全取值方法，自动处理类型转换：

// String 取值（Number 自动 toString）
String name = vo.getStr("name");

// Integer 取值（String 自动解析，无效抛 ParseException）
Integer age = vo.getInt("age");

// Long 取值
Long uid = vo.getLong("uid");

// Boolean 取值（支持 true/false、1/0）
Boolean vip = vo.getBoolean("vip");

// 指定类型取值（Map/List 自动通过 JSON 库转换）
UserDTO dto = vo.get("user", UserDTO.class);

// 数组取值（逗号分隔自动拆分）
String[] tags = vo.getStrArray("tags"); // "java,spring" → ["java", "spring"]
Integer[] ids = vo.getIntArray("ids"); // "1,2,3" → [1, 2, 3]
Long[] uids = vo.getLongArray("uids"); // "100,200" → [100L, 200L]

Boolean 转换规则：

• Boolean 类型：直接返回
• String 类型："true" → true，"false" → false
• Number 类型：非 0 → true，0 → false

2.5 嵌套路径取值：点号语法

当请求参数包含嵌套对象时，无需手动层层取值，直接用点号路径：

// 请求体 JSON：
// {
// "user": {
// "address": {
// "city": "北京",
// "street": "长安街"
// }
// }
// }

// 直接取值
String city = vo.getPathNode("user.address.city", String.class); // "北京"
String street = vo.getPathNode("user.address.street", String.class); // "长安街"

规则：

• 路径中每层必须是 Map 类型（JSON 对象）
• 不支持数组索引（如 user.cityList[0].city）
• 路径不存在时返回 null，不会抛异常

2.6 对象转换：toBean / toListBean

// 将全部请求参数转换为 JavaBean（JSON 反序列化）
User user = vo.toBean(User.class);

// 将 JSON 数组请求体转换为 List（仅 JSON 请求有效）
List<User> users = vo.toListBean(User.class);

2.7 文件上传与二进制流

// 获取 FormData 中的文件
WebFile webFile = vo.getWebFile();
if (webFile != null) {
MultipartFile avatar = webFile.getFile("avatar");
// 处理文件…
}

// 获取原始二进制流（application/octet-stream）
InputStream binaryStream = vo.getBinaryStream();
// 注意：二进制流需要调用方自行关闭

2.8 XML 处理

// 获取原始 XML 字符串
String xml = vo.getXml();

// XML 自动转 Bean（默认根节点为 <data>）
// 请求体：<data><name>张三</name><age>25</age></data>
User user = vo.getXml(User.class);

// 自定义根节点别名
// 请求体：<root><name>张三</name></root>
User user2 = vo.getXml(User.class, "root");

2.9 自定义分页参数名

@RequestVo 注解支持自定义分页参数名，适配不同前端团队的命名习惯：

// 前端传 pageNum / size
@PostMapping("/list")
public ResultVO<?> list(
@RequestVo(page = "pageNum", pageSize = "size", defaultPageSize = 20) RequestVO vo
) {
Pager pager = vo.getPager(); // 自动用 pageNum / size 解析
List<User> users = userService.list(pager);
return ResultVO.suc(users, pager);
}

三、实战：完整 Controller 示例

以一个用户管理模块为例，展示 ResultVO + RequestVO 的完整配合使用：

@RestController
@RequestMapping("/api/users")
public class UserController {

/**
* 查询用户详情
* GET /api/users/123
*/
@GetMapping("/{id}")
public ResultVO<User> getUser(@PathVariable Long id) {
User user = userService.findById(id);
if (user == null) {
return ResultVO.fail(404, "用户不存在");
}
return ResultVO.suc(user);
}

/**
* 分页查询用户列表
* GET /api/users?page=1&pageSize=20
*/
@GetMapping
public ResultVO<List<User>> listUsers(@RequestVo RequestVO requestVO) {
Pager pager = requestVO.getPager();
List<User> users = userService.list(pager);
return ResultVO.suc(users, pager);
}

/**
* 创建用户（JSON 请求）
* POST /api/users
* Body: {"name": "张三", "age": 25, "address": {"city": "北京"}}
*/
@PostMapping
public ResultVO<User> createUser(@RequestVo RequestVO vo) {
// 取嵌套字段
String city = vo.getPathNode("address.city", String.class);

// 整体转 Bean
User user = vo.toBean(User.class);
User created = userService.create(user);

return ResultVO.suc(201, "创建成功", created);
}

/**
* 更新用户（Form 表单）
* PUT /api/users/123
* Content-Type: application/x-www-form-urlencoded
* Body: name=李四&age=30
*/
@PutMapping("/{id}")
public ResultVO<User> updateUser(@PathVariable Long id, @RequestVo RequestVO vo) {
String name = vo.getStr("name");
Integer age = vo.getInt("age");
User updated = userService.update(id, name, age);
return ResultVO.suc(updated);
}

/**
* 上传头像（FormData）
* POST /api/users/123/avatar
* Content-Type: multipart/form-data
*/
@PostMapping("/{id}/avatar")
public ResultVO<String> uploadAvatar(@PathVariable Long id, @RequestVo RequestVO vo) {
WebFile webFile = vo.getWebFile();
if (webFile == null) {
return ResultVO.fail(400, "请选择文件");
}
MultipartFile file = webFile.getFile("avatar");
String url = fileService.upload(file);
return ResultVO.suc(url);
}

/**
* 批量删除
* DELETE /api/users?ids=1,2,3
*/
@DeleteMapping
public ResultVO<Void> deleteUsers(@RequestVo RequestVO vo) {
Long[] ids = vo.getLongArray("ids");
if (ids == null || ids.length == 0) {
return ResultVO.fail(400, "请选择要删除的用户");
}
userService.deleteByIds(ids);
return ResultVO.suc();
}

/**
* 接收 XML 请求
* POST /api/users/xml
* Content-Type: application/xml
* Body: <data><name>王五</name><age>28</age></data>
*/
@PostMapping("/xml")
public ResultVO<User> createFromXml(@RequestVo RequestVO vo) {
User user = vo.getXml(User.class);
User created = userService.create(user);
return ResultVO.suc(created);
}
}

四、API 速查表

ResultVO 方法速查

RequestVO 方法速查

五、最佳实践与注意事项

5.1 响应设计最佳实践

@RestControllerAdvice
public class GlobalExceptionHandler {

@ExceptionHandler(BizException.class)
public ResultVO<?> handleBizException(BizException e) {
return ResultVO.fail(e.getCode(), e.getMessage());
}

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResultVO<?> handleValidation(MethodArgumentNotValidException e) {
String msg = e.getBindingResult().getFieldErrors().stream()
.map(FieldError::getDefaultMessage)
.collect(Collectors.joining("; "));
return ResultVO.fail(400, msg);
}
}

5.2 请求参数最佳实践

5.3 注意事项

六、总结

ResultVO + RequestVO 提供了一套完整的 API 设计规范：

两者的配合使用，可以让你的 API 设计更加规范、前后端协作更加高效。无论是互联网项目还是企业级应用，这套设计体系都能很好地适配。

源码地址：pan-common

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，后续将持续更新 Java 工具类实战系列。