從零搭建Spring Boot腳手架(2):增加通用的功能
1. 前言
今天開始搭建我們的kono Spring Boot腳手架,首先會整合Spring MVC並進行定製化以滿足日常開發的需要,我們先做一些剛性的需求定製,後續再補充細節。如果你看了本文有什麼問題可以留言討論。多多持續關注,共同學習,共同進步。
2. 統一返回體
在開發中統一返回資料非常重要。方便前端統一處理。通常設計為以下結構:
{ "code": 200, "data": { "name": "felord.cn", "age": 18 }, "msg": "", "identifier": "" }
- code 業務狀態碼,設計時應該區別於http狀態碼。
- data 資料載體,用以裝載返回給前端展現的資料。
- msg 提示資訊,用於前端呼叫後返回的提示資訊,例如 “新增成功”、“刪除失敗”。
- identifier 預留的標識位,作為一些業務的處理標識。
根據上面的一些定義,聲明瞭一個統一返回體物件RestBody<T>
並聲明瞭一些靜態方法來方便定義。
package cn.felord.kono.advice; import lombok.Data; import java.io.Serializable; /** * @author felord.cn * @since 22:32 2019-04-02 */ @Data public class RestBody<T> implements Rest<T>, Serializable { private static final long serialVersionUID = -7616216747521482608L; private int code = 200; private T data; private String msg = ""; private String identifier = ""; public static Rest<?> ok() { return new RestBody<>(); } public static Rest<?> ok(String msg) { Rest<?> restBody = new RestBody<>(); restBody.setMsg(msg); return restBody; } public static <T> Rest<T> okData(T data) { Rest<T> restBody = new RestBody<>(); restBody.setData(data); return restBody; } public static <T> Rest<T> okData(T data, String msg) { Rest<T> restBody = new RestBody<>(); restBody.setData(data); restBody.setMsg(msg); return restBody; } public static <T> Rest<T> build(int code, T data, String msg, String identifier) { Rest<T> restBody = new RestBody<>(); restBody.setCode(code); restBody.setData(data); restBody.setMsg(msg); restBody.setIdentifier(identifier); return restBody; } public static Rest<?> failure(String msg, String identifier) { Rest<?> restBody = new RestBody<>(); restBody.setMsg(msg); restBody.setIdentifier(identifier); return restBody; } public static Rest<?> failure(int httpStatus, String msg ) { Rest<?> restBody = new RestBody< >(); restBody.setCode(httpStatus); restBody.setMsg(msg); restBody.setIdentifier("-9999"); return restBody; } public static <T> Rest<T> failureData(T data, String msg, String identifier) { Rest<T> restBody = new RestBody<>(); restBody.setIdentifier(identifier); restBody.setData(data); restBody.setMsg(msg); return restBody; } @Override public String toString() { return "{" + "code:" + code + ", data:" + data + ", msg:" + msg + ", identifier:" + identifier + '}'; } }
但是每次都要顯式宣告返回體也不是很優雅的辦法,所以我們希望無感知的來實現這個功能。Spring Framework正好提供此功能,我們藉助於@RestControllerAdvice
和ResponseBodyAdvice<T>
來對專案的每一個@RestController
標記的控制類的響應體進行後置切面通知處理。
/** * 統一返回體包裝器 * * @author felord.cn * @since 14:58 **/ @RestControllerAdvice public class RestBodyAdvice implements ResponseBodyAdvice<Object> { @Override public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) { return true; } @Override public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) { // 如果為空 返回一個不帶資料的空返回體 if (o == null) { return RestBody.ok(); } // 如果 RestBody 的 父類 是 返回值的父型別 直接返回 // 方便我們可以在介面方法中直接返回RestBody if (Rest.class.isAssignableFrom(o.getClass())) { return o; } // 進行統一的返回體封裝 return RestBody.okData(o); } }
當我們介面返回一個實體類時會自動封裝到統一返回體RestBody<T>
中。
既然有
ResponseBodyAdvice
,就有一個RequestBodyAdvice
,它似乎是來進行前置處理的,以後可能有一些用途。
2. 統一異常處理
統一異常也是@RestControllerAdvice
能實現的,可參考之前的Hibernate Validator校驗引數全攻略。這裡初步集成了校驗異常的處理,後續會新增其他異常。
/**
* 統一異常處理
*
* @author felord.cn
* @since 13 :31 2019-04-11
*/
@Slf4j
@RestControllerAdvice
public class ApiExceptionHandleAdvice {
@ExceptionHandler(BindException.class)
public Rest<?> handle(HttpServletRequest request, BindException e) {
logger(request, e);
List<ObjectError> allErrors = e.getAllErrors();
ObjectError objectError = allErrors.get(0);
return RestBody.failure(700, objectError.getDefaultMessage());
}
@ExceptionHandler(MethodArgumentNotValidException.class)
public Rest<?> handle(HttpServletRequest request, MethodArgumentNotValidException e) {
logger(request, e);
List<ObjectError> allErrors = e.getBindingResult().getAllErrors();
ObjectError objectError = allErrors.get(0);
return RestBody.failure(700, objectError.getDefaultMessage());
}
@ExceptionHandler(ConstraintViolationException.class)
public Rest<?> handle(HttpServletRequest request, ConstraintViolationException e) {
logger(request, e);
Optional<ConstraintViolation<?>> first = e.getConstraintViolations().stream().findFirst();
String message = first.isPresent() ? first.get().getMessage() : "";
return RestBody.failure(700, message);
}
@ExceptionHandler(Exception.class)
public Rest<?> handle(HttpServletRequest request, Exception e) {
logger(request, e);
return RestBody.failure(700, e.getMessage());
}
private void logger(HttpServletRequest request, Exception e) {
String contentType = request.getHeader("Content-Type");
log.error("統一異常處理 uri: {} content-type: {} exception: {}", request.getRequestURI(), contentType, e.toString());
}
}
3. 簡化型別轉換
簡化Java Bean之間轉換也是一個必要的功能。 這裡選擇mapStruct,型別安全而且容易使用,比那些BeanUtil
要好用的多。但是從我使用的經驗上來看,不要使用mapStruct提供的複雜功能只做簡單對映。詳細可參考文章Spring Boot 2 實戰:整合 MapStruct 型別轉換。
整合進來非常簡單,由於它只在編譯期生效所以引用時的scope
最好設定為compile
,我們在kono-dependencies中加入其依賴管理:
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>${mapstruct.version}</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${mapstruct.version}</version>
<scope>compile</scope>
</dependency>
在kono-app
中直接引用上面兩個依賴,但是這樣還不行,和lombok一起使用編譯容易出現SPI錯誤。我們還需要整合相關的Maven外掛到kono-app編譯的生命週期中去。參考如下:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<showWarnings>true</showWarnings>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
</path>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${mapstruct.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
然後我們就很容易將一個Java Bean轉化為另一個Java Bean。下面這段程式碼將UserInfo
轉換為UserInfoVO
而且自動為UserInfoVO.addTime
賦值為當前時間,同時這個工具也自動注入了Spring IoC,而這一切都發生在編譯期。
編譯前:
/**
* @author felord.cn
* @since 16:09
**/
@Mapper(componentModel = "spring", imports = {LocalDateTime.class})
public interface BeanMapping {
@Mapping(target = "addTime", expression = "java(LocalDateTime.now())")
UserInfoVO toUserInfoVo(UserInfo userInfo);
}
編譯後:
package cn.felord.kono.beanmapping;
import cn.felord.kono.entity.UserInfo;
import cn.felord.kono.entity.UserInfoVO;
import java.time.LocalDateTime;
import javax.annotation.Generated;
import org.springframework.stereotype.Component;
@Generated(
value = "org.mapstruct.ap.MappingProcessor",
date = "2020-07-30T23:11:24+0800",
comments = "version: 1.3.0.Final, compiler: javac, environment: Java 1.8.0_252 (AdoptOpenJDK)"
)
@Component
public class BeanMappingImpl implements BeanMapping {
@Override
public UserInfoVO toUserInfoVo(UserInfo userInfo) {
if ( userInfo == null ) {
return null;
}
UserInfoVO userInfoVO = new UserInfoVO();
userInfoVO.setName( userInfo.getName() );
userInfoVO.setAge( userInfo.getAge() );
userInfoVO.setAddTime( LocalDateTime.now() );
return userInfoVO;
}
}
其實mapStruct也就是幫我們寫了Getter和Setter,但是不要使用其比較複雜的轉換,會增加學習成本和可維護的難度。
4. 單元測試
將以上功能整合進去後分別做一個單元測試,全部通過。
@Autowired
MockMvc mockMvc;
@Autowired
BeanMapping beanMapping;
/**
* 測試全域性異常處理.
*
* @throws Exception the exception
* @see UserController#getUserInfo()
*/
@Test
void testGlobalExceptionHandler() throws Exception {
String rtnJsonStr = "{\n" +
" \"code\": 700,\n" +
" \"data\": null,\n" +
" \"msg\": \"test global exception handler\",\n" +
" \"identifier\": \"-9999\"\n" +
"}";
mockMvc.perform(MockMvcRequestBuilders.get("/user/get"))
.andExpect(MockMvcResultMatchers.content()
.json(rtnJsonStr))
.andDo(MockMvcResultHandlers.print());
}
/**
* 測試統一返回體.
*
* @throws Exception the exception
* @see UserController#getUserVO()
*/
@Test
void testUnifiedReturnStruct() throws Exception {
// "{\"code\":200,\"data\":{\"name\":\"felord.cn\",\"age\":18,\"addTime\":\"2020-07-30T13:08:53.201\"},\"msg\":\"\",\"identifier\":\"\"}";
mockMvc.perform(MockMvcRequestBuilders.get("/user/vo"))
.andExpect(MockMvcResultMatchers.jsonPath("code", Is.is(200)))
.andExpect(MockMvcResultMatchers.jsonPath("data.name", Is.is("felord.cn")))
.andExpect(MockMvcResultMatchers.jsonPath("data.age", Is.is(18)))
.andExpect(MockMvcResultMatchers.jsonPath("data.addTime", Is.is(notNullValue())))
.andDo(MockMvcResultHandlers.print());
}
/**
* 測試 mapStruct型別轉換.
*
* @see BeanMapping
*/
@Test
void testMapStruct() {
UserInfo userInfo = new UserInfo();
userInfo.setName("felord.cn");
userInfo.setAge(18);
UserInfoVO userInfoVO = beanMapping.toUserInfoVo(userInfo);
Assertions.assertEquals(userInfoVO.getName(), userInfo.getName());
Assertions.assertNotNull(userInfoVO.getAddTime());
}
5. 總結
自制腳手架初步具有了統一返回體、統一異常處理、快速型別轉換,其實引數校驗也已經支援了。後續就該整合資料庫了,常用的資料庫訪問技術主要為Mybatis、Spring Data JPA、JOOQ等,不知道你更喜歡哪一款?歡迎留言討論。
關注公眾號:Felordcn 獲取更多資訊