1 
  
  
  
  
  
 、接口的响应要明确表示接口的处理结果

为了将接口设计得更合理 
  
  
  
  
  
 ，我们需要考虑如下两个原则：

对外隐藏内部实现 
  
  
  
  
  
 。即服务A调用服务B
  
  
  
  
  
  ，如果服务B异常
 


 


 


 


 


 

，但是我们不要直接把服务B的状态码
  
  
  
  
  
  、错误描述直接暴露给用户；

设计接口结构时 
 
 
 
 
 
，明确每个字段的含义
   
   
   
   
   
   ，以及客户端的处理方式
  
  
  
  
  
  。

比如下面这个是我们设计的接口的响应：

@Data public class APIResponse<T> { private boolean success; private T data; private int code; private String message; }

接口的设计逻辑：

如果出现非 200 的 HTTP 响应状态码
 

 

 

 

 

 
，就代表请求没有到服务 

 

 

 

 

 

，可能是网络出问题
 


 


 


 


 


 

、网络超时            ，或者网络配置的问题
 


 


 


 


 


 

。这时

 
 

 
 

 
 

 
 

 
 

 
 ，肯定无法拿到服务端的响应体











，客户端可以给予友好提示                  ，比如让用户重试
 
 
 
 
 
 
 
 
 
 
 
 ，不需要继续解析响应结构体 
 
 
 
 
 
。

如果 HTTP 响应码是 200

















，解析响应体查看 success            ，为 false 代表下单请求处理失败
  
 
  
 
  
 
  
 
  
 
  
 ，可能是因为服务参数验证错误











，也可能是因为服务操作失败
   
   
   
   
   
   。这时 
  
  
  
  
  
 ，根据服务定义的错误码表和 code
  
  
  
  
  
  ，做不同处理
 

 

 

 

 

 
。比如友好提示
 


 


 


 


 


 

，或是让用户重新填写相关信息 
 
 
 
 
 
，其中友好提示的文字内容可以从 message 中获取 

 

 

 

 

 

。

success 为 true 的情况下
   
   
   
   
   
   ，才需要继续解析响应体中的 data 结构体            。data 结构体代表了业务数据

 
 

 
 

 
 

 
 

 
 

 
 。

1.1 
 
 
 
 
 
、通过ResponseBodyAdvice完成自动包装响应体

为了代码会更简洁
 

 

 

 

 

 
，我们的业务逻辑中可以通过ResponseBodyAdvice完成响应体的包装











。

@RestControllerAdvice @Slf4j public class APIResponseAdvice implements ResponseBodyAdvice<Object> { //自动处理APIException 

 

 

 

 

 

，包装为APIResponse @ExceptionHandler(APIException.class) public APIResponse handleApiException(HttpServletRequest request, APIException ex) { log.error("process url {} failed", request.getRequestURL().toString(), ex); APIResponse apiResponse = new APIResponse(); apiResponse.setSuccess(false); apiResponse.setCode(ex.getErrorCode()); apiResponse.setMessage(ex.getErrorMessage()); return apiResponse; } //仅当方法或类没有标记@NoAPIResponse才自动包装 @Override public boolean supports(MethodParameter returnType, Class converterType) { return returnType.getParameterType() != APIResponse.class && AnnotationUtils.findAnnotation(returnType.getMethod(), NoAPIResponse.class) == null && AnnotationUtils.findAnnotation(returnType.getDeclaringClass(), NoAPIResponse.class) == null; } //自动包装外层APIResposne响应 @Override public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) { APIResponse apiResponse = new APIResponse(); apiResponse.setSuccess(true); apiResponse.setMessage("OK"); apiResponse.setCode(2000); apiResponse.setData(body); return apiResponse; } }

实现了 @NoAPIResponse 自定义注解                  。如果某些 @RestController 的接口不希望实现自动包装的话            ，可以标记这个注解：

@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface NoAPIResponse { }

在 ResponseBodyAdvice 的 support 方法中

 
 

 
 

 
 

 
 

 
 

 
 ，我们排除了标记有这个注解的方法或类的自动响应体包装
 
 
 
 
 
 
 
 
 
 
 
 。比如











，对于刚才我们实现的测试客户端 client 方法不需要包装为 APIResponse                  ，就可以标记上这个注解：

@GetMapping("client") @NoAPIResponse public String client(@RequestParam(value = "error", defaultValue = "0") int error){ }

这样我们在代码中
 
 
 
 
 
 
 
 
 
 
 
 ，就统一了响应体的处理

















，不用担心有些程序员别出心裁自己搞一套

















。

2
   
   
   
   
   
   、要考虑接口变迁的版本控制策略

接口不可能一成不变            ，需要根据业务需求不断增加内部逻辑            。如果做大的功能调整或重构
  
 
  
 
  
 
  
 
  
 
  
 ，涉及参数定义的变化或是参数废弃











，导致接口无法向前兼容 
  
  
  
  
  
 ，这时接口就需要有版本的概念
  
 
  
 
  
 
  
 
  
 
  
 。在考虑接口版本策略设计时
  
  
  
  
  
  ，我们需要注意的是
 


 


 


 


 


 

，最好一开始就明确版本策略 
 
 
 
 
 
，并考虑在整个服务端统一版本策略











。

第一
   
   
   
   
   
   ，版本策略最好一开始就考虑 
  
  
  
  
  
 。 第二
 

 

 

 

 

 
，版本实现方式要统一
  
  
  
  
  
  。

为了实现上面的目的 

 

 

 

 

 

，我们可以通过注解的方式为接口增加基于 URL 的版本号：首先            ，创建一个注解来定义接口的版本
 


 


 


 


 


 

。@APIVersion 自定义注解可以应用于方法或 Controller 上：

@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface APIVersion { String[] value(); }

然后

 
 

 
 

 
 

 
 

 
 

 
 ，定义一个 APIVersionHandlerMapping 类继承 RequestMappingHandlerMapping 
 
 
 
 
 
。

public class APIVersionHandlerMapping extends RequestMappingHandlerMapping { @Override protected boolean isHandler(Class<?> beanType) { return AnnotatedElementUtils.hasAnnotation(beanType, Controller.class); } @Override protected void registerHandlerMethod(Object handler, Method method, RequestMappingInfo mapping) { Class<?> controllerClass = method.getDeclaringClass(); //类上的APIVersion注解 APIVersion apiVersion = AnnotationUtils.findAnnotation(controllerClass, APIVersion.class); //方法上的APIVersion注解 APIVersion methodAnnotation = AnnotationUtils.findAnnotation(method, APIVersion.class); //以方法上的注解优先 if (methodAnnotation != null) { apiVersion = methodAnnotation; } String[] urlPatterns = apiVersion == null ? new String[0] : apiVersion.value(); PatternsRequestCondition apiPattern = new PatternsRequestCondition(urlPatterns); PatternsRequestCondition oldPattern = mapping.getPatternsCondition(); PatternsRequestCondition updatedFinalPattern = apiPattern.combine(oldPattern); //重新构建RequestMappingInfo mapping = new RequestMappingInfo(mapping.getName(), updatedFinalPattern, mapping.getMethodsCondition(), mapping.getParamsCondition(), mapping.getHeadersCondition(), mapping.getConsumesCondition(), mapping.getProducesCondition(), mapping.getCustomCondition()); super.registerHandlerMethod(handler, method, mapping); } }

RequestMappingHandlerMapping 的作用











，是根据类或方法上的 @RequestMapping 来生成 RequestMappingInfo 的实例
   
   
   
   
   
   。我们覆盖 registerHandlerMethod 方法的实现                  ，从 @APIVersion 自定义注解中读取版本信息
 
 
 
 
 
 
 
 
 
 
 
 ，拼接上原有的
 

 

 

 

 

 
、不带版本号的 URL Pattern

















，构成新的 RequestMappingInfo            ，来通过注解的方式为接口增加基于 URL 的版本号
 

 

 

 

 

 
。

最后
  
 
  
 
  
 
  
 
  
 
  
 ，要通过实现 WebMvcRegistrations 接口











，来生效自定义的 APIVersionHandlerMapping

@SpringBootApplication public class CommonMistakesApplication implements WebMvcRegistrations { @Override public RequestMappingHandlerMapping getRequestMappingHandlerMapping() { return new APIVersionHandlerMapping(); } }

这样 
  
  
  
  
  
 ，就实现了在 Controller 上或接口方法上通过注解
  
  
  
  
  
  ，来实现以统一的 Pattern 进行版本号控制
 


 


 


 


 


 

，使用时：

@GetMapping(value = "/api/user") @APIVersion("v4") public int right4() { return 4; }

访问url为 http://localhost:8080/v4/api/user

使用框架来明确 API 版本的指定策略 
 
 
 
 
 
，不仅实现了标准化
   
   
   
   
   
   ，更实现了强制的 API 版本控制 

 

 

 

 

 

。假如我们的接口强制要求必须要有版本号
 

 

 

 

 

 
，可以改动APIVersionHandlerMapping代码 

 

 

 

 

 

，在获取不到@APIVersion注解时            ，就给予报错提示            。