An excellent Controller layer logic
Speaking of Controller, I believe everyone is familiar with it. It can easily provide external data interfaces. Its positioning, I think it is an "indispensable supporting role".
It is indispensable because whether it is the traditional three-tier architecture or the current COLA architecture, the Controller layer still has a place, which shows its necessity.
It is said to be a supporting role because the code of the Controller layer is generally not responsible for the implementation of specific logical business logic, but it is responsible for receiving and responding to requests.
Looking at the problem from the status quo
The main tasks of the Controller are as follows:
- Receive the request and parse the parameters
- Call Service to execute specific business code (may include parameter verification)
- Capture business logic exceptions and give feedback
- Business logic execution succeeds in response
//DTO
@Data
public class TestDTO {
private Integer num;
private String type;
}
//Service
@Service
public class TestService {
public Double service(TestDTO testDTO) throws Exception {
if (testDTO.getNum() <= 0) {
throw new Exception("输入的数字需要大于0");
}
if (testDTO.getType().equals("square")) {
return Math.pow(testDTO.getNum(), 2);
}
if (testDTO.getType().equals("factorial")) {
double result = 1;
int num = testDTO.getNum();
while (num > 1) {
result = result * num;
num -= 1;
}
return result;
}
throw new Exception("未识别的算法");
}
}
//Controller
@RestController
public class TestController {
private TestService testService;
@PostMapping("/test")
public Double test(@RequestBody TestDTO testDTO) {
try {
Double result = this.testService.service(testDTO);
return result;
} catch (Exception e) {
throw new RuntimeException(e);
}
}
@Autowired
public DTOid setTestService(TestService testService) {
this.testService = testService;
}
}
If you really develop the Controller code according to the work items listed above, there will be several problems:
- Parameter verification couples business code too much, which violates the principle of single responsibility
- The same exception may be thrown in multiple businesses, resulting in code duplication
- Various abnormal feedback and successful response formats are not uniform, and the interface is not friendly
Retrofit Controller layer logic
uniform return structure
It is very necessary to unify the return value type regardless of whether the front and back ends of the project are separated, so that developers who interface with the interface can more clearly know whether the call of this interface is successful (you can’t simply judge whether the return value is null or not, because This is how some interfaces are designed).
Use a status code and status information to clearly understand the interface call situation:
//定义返回数据结构
public interface IResult {
Integer getCode();
String getMessage();
}
//常用结果的枚举
public enum ResultEnum implements IResult {
SUCCESS(2001, "接口调用成功"),
VALIDATE_FAILED(2002, "参数校验失败"),
COMMON_FAILED(2003, "接口调用失败"),
FORBIDDEN(2004, "没有权限访问资源");
private Integer code;
private String message;
//省略get、set方法和构造方法
}
//统一返回数据结构
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> {
private Integer code;
private String message;
private T data;
public static <T> Result<T> success(T data) {
return new Result<>(ResultEnum.SUCCESS.getCode(), ResultEnum.SUCCESS.getMessage(), data);
}
public static <T> Result<T> success(String message, T data) {
return new Result<>(ResultEnum.SUCCESS.getCode(), message, data);
}
public static Result<?> failed() {
return new Result<>(ResultEnum.COMMON_FAILED.getCode(), ResultEnum.COMMON_FAILED.getMessage(), null);
}
public static Result<?> failed(String message) {
return new Result<>(ResultEnum.COMMON_FAILED.getCode(), message, null);
}
public static Result<?> failed(IResult errorResult) {
return new Result<>(errorResult.getCode(), errorResult.getMessage(), null);
}
public static <T> Result<T> instance(Integer code, String message, T data) {
Result<T> result = new Result<>();
result.setCode(code);
result.setMessage(message);
result.setData(data);
return result;
}
}
After the unified return structure, it can be used in the Controller, but each Controller has to write such a piece of final encapsulation logic, which is very repetitive work, so we need to continue to find ways to further process the unified return structure.
Unified packaging processing
Spring provides a class ResponseBodyAdvice that can help us achieve the above requirements:
public interface ResponseBodyAdvice<T> {
boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType);
@Nullable
T beforeBodyWrite(@Nullable T body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response);
}
ResponseBodyAdvice intercepts the content returned by the Controller before HttpMessageConverter performs type conversion, performs corresponding processing operations, and then returns the result to the client.
Then you can put the unified packaging work into this class:
- supports: determine whether to hand over to the beforeBodyWrite method for execution, ture: required; false: not required
- beforeBodyWrite: perform specific processing on the response
// 如果引入了swagger或knife4j的文档生成组件，这里需要仅扫描自己项目的包，否则文档无法正常生成
@RestControllerAdvice(basePackages = "com.example.demo")
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
// 如果不需要进行封装的，可以添加一些校验手段，比如添加标记排除的注解
return true;
}
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
// 提供一定的灵活度，如果body已经被包装了，就不进行包装
if (body instanceof Result) {
return body;
}
return Result.success(body);
}
}
After such a transformation, it is possible to realize the unified packaging of the data returned by the Controller without making a lot of changes to the original code.
Parameter check
The Java API specification JSR303 defines the standard validation-api for verification, and one of the more famous implementations is hibernate validation.
Spring validation is its secondary encapsulation. It is often used for automatic parameter verification of SpringMVC. The code for parameter verification does not need to be coupled with business logic code.
① @PathVariable and @RequestParam parameter verification
The parameter reception of the Get request generally depends on these two annotations, but due to the length limit of the url and the maintainability of the code, it is best to use entities to pass parameters for more than 5 parameters.
Validation of @PathVariable and @RequestParam parameters requires annotations to declare constraints on the input parameters.
If the validation fails, a MethodArgumentNotValidException will be thrown.
@RestController(value = "prettyTestController")
@RequestMapping("/pretty")
public class TestController {
private TestService testService;
@GetMapping("/{num}")
public Integer detail(@PathVariable("num") @Min(1) @Max(20) Integer num) {
return num * num;
}
@GetMapping("/getByEmail")
public TestDTO getByAccount(@RequestParam @NotBlank @Email String email) {
TestDTO testDTO = new TestDTO();
testDTO.setEmail(email);
return testDTO;
}
@Autowired
public void setTestService(TestService prettyTestService) {
this.testService = prettyTestService;
}
}
Calibration principle
In SpringMVC, there is a class RequestResponseBodyMethodProcessor, which has two functions (in fact, you can get a little inspiration from the name)
- Parameters for parsing @RequestBody annotations
- Handle the return value of @ResponseBody annotation method
The method for resolving @RequestBoyd annotation parameters is resolveArgument.
public class RequestResponseBodyMethodProcessor extends AbstractMessageConverterMethodProcessor {
/**
* Throws MethodArgumentNotValidException if validation fails.
* @throws HttpMessageNotReadableException if {@link RequestBody#required()}
* is {@code true} and there is no body content or if there is no suitable
* converter to read the content with.
*/
@Override
public Object resolveArgument(MethodParameter parameter, @Nullable ModelAndViewContainer mavContainer,
NativeWebRequest webRequest, @Nullable WebDataBinderFactory binderFactory) throws Exception {
parameter = parameter.nestedIfOptional();
//把请求数据封装成标注的DTO对象
Object arg = readWithMessageConverters(webRequest, parameter, parameter.getNestedGenericParameterType());
String name = Conventions.getVariableNameForParameter(parameter);
if (binderFactory != null) {
WebDataBinder binder = binderFactory.createBinder(webRequest, arg, name);
if (arg != null) {
//执行数据校验
validateIfApplicable(binder, parameter);
//如果校验不通过，就抛出MethodArgumentNotValidException异常
//如果我们不自己捕获，那么最终会由DefaultHandlerExceptionResolver捕获处理
if (binder.getBindingResult().hasErrors() && isBindExceptionRequired(binder, parameter)) {
throw new MethodArgumentNotValidException(parameter, binder.getBindingResult());
}
}
if (mavContainer != null) {
mavContainer.addAttribute(BindingResult.MODEL_KEY_PREFIX + name, binder.getBindingResult());
}
}
return adaptArgumentIfNecessary(arg, parameter);
}
}
public abstract class AbstractMessageConverterMethodArgumentResolver implements HandlerMethodArgumentResolver {
/**
* Validate the binding target if applicable.
* <p>The default implementation checks for {@code @javax.validation.Valid},
* Spring's {@link org.springframework.validation.annotation.Validated},
* and custom annotations whose name starts with "Valid".
* @param binder the DataBinder to be used
* @param parameter the method parameter descriptor
* @since 4.1.5
* @see #isBindExceptionRequired
*/
protected void validateIfApplicable(WebDataBinder binder, MethodParameter parameter) {
//获取参数上的所有注解
Annotation[] annotations = parameter.getParameterAnnotations();
for (Annotation ann : annotations) {
//如果注解中包含了@Valid、@Validated或者是名字以Valid开头的注解就进行参数校验
Object[] validationHints = ValidationAnnotationUtils.determineValidationHints(ann);
if (validationHints != null) {
//实际校验逻辑，最终会调用Hibernate Validator执行真正的校验
//所以Spring Validation是对Hibernate Validation的二次封装
binder.validate(validationHints);
break;
}
}
}
}
② @RequestBody parameter verification
The parameters of Post and Put requests are recommended to use @RequestBody request body parameters.
To verify the @RequestBody parameter, you need to add the verification condition to the DTO object, and then use @Validated to complete the automatic verification.
If the verification fails, a ConstraintViolationException will be thrown.
//DTO
@Data
public class TestDTO {
@NotBlank
private String userName;
@NotBlank
@Length(min = 6, max = 20)
private String password;
@NotNull
@Email
private String email;
}
//Controller
@RestController(value = "prettyTestController")
@RequestMapping("/pretty")
public class TestController {
private TestService testService;
@PostMapping("/test-validation")
public void testValidation(@RequestBody @Validated TestDTO testDTO) {
this.testService.save(testDTO);
}
@Autowired
public void setTestService(TestService testService) {
this.testService = testService;
}
}
Calibration principle
In the way of declaring constraints, annotations are added to the parameters, and it is easier to guess that AOP is used to enhance the method.
In fact, Spring also dynamically registers the AOP aspect through MethodValidationPostProcessor, and then uses MethodValidationInterceptor to weave and enhance the pointcut method.
public class MethodValidationPostProcessor extends AbstractBeanFactoryAwareAdvisingPostProcessor implements InitializingBean {
//指定了创建切面的Bean的注解
private Class<? extends Annotation> validatedAnnotationType = Validated.class;
@Override
public void afterPropertiesSet() {
//为所有@Validated标注的Bean创建切面
Pointcut pointcut = new AnnotationMatchingPointcut(this.validatedAnnotationType, true);
//创建Advisor进行增强
this.advisor = new DefaultPointcutAdvisor(pointcut, createMethodValidationAdvice(this.validator));
}
//创建Advice，本质就是一个方法拦截器
protected Advice createMethodValidationAdvice(@Nullable Validator validator) {
return (validator != null ? new MethodValidationInterceptor(validator) : new MethodValidationInterceptor());
}
}
public class MethodValidationInterceptor implements MethodInterceptor {
@Override
public Object invoke(MethodInvocation invocation) throws Throwable {
//无需增强的方法，直接跳过
if (isFactoryBeanMetadataMethod(invocation.getMethod())) {
return invocation.proceed();
}
Class<?>[] groups = determineValidationGroups(invocation);
ExecutableValidator execVal = this.validator.forExecutables();
Method methodToValidate = invocation.getMethod();
Set<ConstraintViolation<Object>> result;
try {
//方法入参校验，最终还是委托给Hibernate Validator来校验
//所以Spring Validation是对Hibernate Validation的二次封装
result = execVal.validateParameters(
invocation.getThis(), methodToValidate, invocation.getArguments(), groups);
}
catch (IllegalArgumentException ex) {
...
}
//校验不通过抛出ConstraintViolationException异常
if (!result.isEmpty()) {
throw new ConstraintViolationException(result);
}
//Controller方法调用
Object returnValue = invocation.proceed();
//下面是对返回值做校验，流程和上面大概一样
result = execVal.validateReturnValue(invocation.getThis(), methodToValidate, returnValue, groups);
if (!result.isEmpty()) {
throw new ConstraintViolationException(result);
}
return returnValue;
}
}
③ Custom verification rules
Sometimes the verification rules provided in the JSR303 standard do not meet complex business requirements, and you can also customize the verification rules.
Custom validation rules need to do two things:
- Customize the annotation class, define error messages and some other required content
- Annotation validator, define judgment rules
//自定义注解类
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Constraint(validatedBy = MobileValidator.class)
public @interface Mobile {
/**
* 是否允许为空
*/
boolean required() default true;
/**
* 校验不通过返回的提示信息
*/
String message() default "不是一个手机号码格式";
/**
* Constraint要求的属性，用于分组校验和扩展，留空就好
*/
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
//注解校验器
public class MobileValidator implements ConstraintValidator<Mobile, CharSequence> {
private boolean required = false;
private final Pattern pattern = Pattern.compile("^1[34578][0-9]{9}$"); // 验证手机号
/**
* 在验证开始前调用注解里的方法，从而获取到一些注解里的参数
*
* @param constraintAnnotation annotation instance for a given constraint declaration
*/
@Override
public void initialize(Mobile constraintAnnotation) {
this.required = constraintAnnotation.required();
}
/**
* 判断参数是否合法
*
* @param value object to validate
* @param context context in which the constraint is evaluated
*/
@Override
public boolean isValid(CharSequence value, ConstraintValidatorContext context) {
if (this.required) {
// 验证
return isMobile(value);
}
if (StringUtils.hasText(value)) {
// 验证
return isMobile(value);
}
return true;
}
private boolean isMobile(final CharSequence str) {
Matcher m = pattern.matcher(str);
return m.matches();
}
}
Automatically verifying parameters is really a very necessary and meaningful work. JSR303 provides a wealth of parameter verification rules, coupled with custom verification rules for complex businesses, completely decouples parameter verification from business logic, makes the code more concise, and conforms to the principle of single responsibility.
Custom exceptions and unified interception exceptions
You can see several problems in the original code:
- The exception thrown is not specific enough, just simply put the error message in Exception
- After an exception is thrown, the Controller cannot give feedback specifically based on the exception
- Although the parameters are automatically checked, the exception return structure is inconsistent with the normal return structure
The purpose of custom exceptions is to have a more fine-grained distinction between exceptions in the business when intercepting exceptions uniformly later, and to respond differently to different exceptions when intercepting.
The purpose of unified interception of exceptions is to correspond to the unified packaging return structure defined above, and the other is that we hope that no matter what exceptions occur in the system, the Http status code must be 200, and the business can distinguish the system as much as possible abnormal.
//自定义异常
public class ForbiddenException extends RuntimeException {
public ForbiddenException(String message) {
super(message);
}
}
//自定义异常
public class BusinessException extends RuntimeException {
public BusinessException(String message) {
super(message);
}
}
//统一拦截异常
@RestControllerAdvice(basePackages = "com.example.demo")
public class ExceptionAdvice {
/**
* 捕获 {@code BusinessException} 异常
*/
@ExceptionHandler({BusinessException.class})
public Result<?> handleBusinessException(BusinessException ex) {
return Result.failed(ex.getMessage());
}
/**
* 捕获 {@code ForbiddenException} 异常
*/
@ExceptionHandler({ForbiddenException.class})
public Result<?> handleForbiddenException(ForbiddenException ex) {
return Result.failed(ResultEnum.FORBIDDEN);
}
/**
* {@code @RequestBody} 参数校验不通过时抛出的异常处理
*/
@ExceptionHandler({MethodArgumentNotValidException.class})
public Result<?> handleMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
BindingResult bindingResult = ex.getBindingResult();
StringBuilder sb = new StringBuilder("校验失败:");
for (FieldError fieldError : bindingResult.getFieldErrors()) {
sb.append(fieldError.getField()).append("：").append(fieldError.getDefaultMessage()).append(", ");
}
String msg = sb.toString();
if (StringUtils.hasText(msg)) {
return Result.failed(ResultEnum.VALIDATE_FAILED.getCode(), msg);
}
return Result.failed(ResultEnum.VALIDATE_FAILED);
}
/**
* {@code @PathVariable} 和 {@code @RequestParam} 参数校验不通过时抛出的异常处理
*/
@ExceptionHandler({ConstraintViolationException.class})
public Result<?> handleConstraintViolationException(ConstraintViolationException ex) {
if (StringUtils.hasText(ex.getMessage())) {
return Result.failed(ResultEnum.VALIDATE_FAILED.getCode(), ex.getMessage());
}
return Result.failed(ResultEnum.VALIDATE_FAILED);
}
/**
* 顶级异常捕获并统一处理，当其他异常无法处理时候选择使用
*/
@ExceptionHandler({Exception.class})
public Result<?> handle(Exception ex) {
return Result.failed(ex.getMessage());
}
}
Summarize
After making all these changes, you can find that the code of the Controller has become very concise, you can clearly know the validation rules of each parameter and each DTO, and you can clearly see what data each Controller method returns , It can also facilitate how each exception should be fed back.
The above is all the content shared today. Interested partners are welcome to contact me by private message. I hope it can be helpful to everyone's study, leave "useful" in the comment area, remember the triplet. There is more knowledge to continue to share, welcome to visit the link: Home