跳到主要内容

SpringMVC控制层的请求和应答

本文介绍Spring MVC中控制层接收请求参数,和返回应答数据的规范。

请求

控制层暴露的接口必须按照以上定义设置请求方法。不允许直接使用RequestMapping原则上每个接口只允许支持一种请求方法 (例外的情况:可能第三方回调不规范的情况下会有特殊要求)。如果接口用于第三方回调,应按照第三方回调的要求开发。

所有参数应该定义为参数本身的类型,不允许一切参数都使用 String 类型接收。通过对 Spring 的扩展,可以优雅的处理对 BooleanLocalDateLocalDateTime 的类型转换。

不允许使用 Long 类型或 String 类型替代日期或日期时间类型。

@Schema(description = "用户信息")
@Data
public class UserAddDto {


/**
* 用户名
*/
@NotBlank(message = "用户名不能为空")
@Schema(description = "用户名", required = true)
private String username;

/**
* 密码
*/
@NotBlank(message = "密码不能为空")
@Schema(description = "密码", required = true)
private String password;
}
java

对于 POST、PUT、PATCH 接口,应答使用 requestBody方式接收参数,也即需要要求前端提交请求的Content-Type 类型为 application/json。后端通过 @RequestBody注解解析参数。

UserController#add
@PostMapping("/add")
@Operation(summary = "新增用户信息")
public ResponseBean<String> add(@Valid @RequestBody UserAddDto addDto) {
this.userService.insert(addDto);
return ResponseBean.success();
}
java

@Valid 注解用户数据验证,请参考《接口参数验证》章节。

原则上一个请求对应一个DTO(如果接口功能类似,且参数相同,可以共用),不允许一个大的DTO接收很多方法的参数。DTO可以通过继承来避免重复代码。如下

@Schema(description = "用户信息")
@Data
public class UserUpdateDto extends UserAddDto {
/**
* 用户ID
*/
@NotBlank(message = "用户ID不能为空")
@Schema(description = "用户ID", required = true)
private String userId;
}
java

应答

应答格式

{
"success": true,
"status": 200,
"data": {
"xxx": "xxx"
}
}
json

应答结果应采用泛型封装,全系统通用。

@Schema(name = "应答信息")
@NoArgsConstructor
@Data
public abstract class BaseResponseBean {

/**
* 业务处理是否成功
*/
@Schema(title = "业务处理是否成功", description = "业务处理是否成功", example = "true")
private boolean success;

/**
* 真实的Http状态码,默认200
*
* <p>如果是业务异常,应该为200,因为一般情况下业务异常是当处理业务时因为某些条件不满足或者数据验证未通过等情况,这时候返回的应是给用户
* 友好的提示信息,待用户进一步修改后重新提交
* </p>
*
* <p>针对404、401、403以及其他的非业务异常,一般建议返回对应的真实的状态码</p>
*
* <p>此字段为一个参考字段,非必要,核心字段应该为 {@link #errorCode}</p>
*/
@Schema(title = "真实的Http状态码", description = "真实的Http状态码", example = "200")
private int status = 200;

/**
* 错误编码
*/
@Schema(description = "错误编码", example = "ERR_1001")
private String errorCode;

/**
* 消息(成功消息或失败消息)
*/
@Schema(description = "消息", example = "Token失效,请重新登录")
private String message;

/**
* 错误详情
*/
@Schema(description = "错误详情")
private Object errorDetails;


protected BaseResponseBean(boolean success, int status) {
this.success = success;
this.status = status;
}

protected BaseResponseBean(String errorCode, String message) {
this.errorCode = errorCode;
this.message = message;
this.success = false;
}
}
java

以上代码可在开源项目butterfly 中获取。在使用时必须指定泛型类型。如果没有返回值,则设置泛型类型为:Void

应答数据的返回应遵循以下原则:

  • 应答数据应返回Vo,不允许直接将Model、Dto、Bo等实体类返回前端。
  • 不允许在service层返回 ResponseBean

示例


public class UserService {

/**
* 通过ID获取用户信息详情
*
* @param userId 主键
* @return 实例对象
*/
UserVo getById(String userId);

/**
* 分页查询用户信息
*
* @param query 查询条件和分页参数
* @return 分页信息及数据列表
*/
Page<UserListVo> findByPage(UserListQuery query)
}
java