前言：

一個后端接口大致分為四個部分組成：接口地址（url）禽最、接口請求方式（get腺怯、post等）、請求數(shù)據(jù)（request）川无、響應(yīng)數(shù)據(jù)（response）呛占。如何構(gòu)建這幾個部分每個公司要求都不同，沒有什么“一定是最好的”標準懦趋，但一個優(yōu)秀的后端接口和一個糟糕的后端接口對比起來差異還是蠻大的晾虑，其中最重要的關(guān)鍵點就是看是否規(guī)范!

本文就一步一步演示如何構(gòu)建起一個優(yōu)秀的后端接口體系，體系構(gòu)建好了自然就有了規(guī)范仅叫，同時再構(gòu)建新的后端接口也會十分輕松帜篇。

所需依賴包

這里用的是SpringBoot配置項目，本文講解的重點是后端接口诫咱，所以只需要導(dǎo)入一個spring-boot-starter-web包就可以了：

<!--web依賴包笙隙，web應(yīng)用必備-->org.springframework.bootspring-boot-starter-web

本文還用了swagger來生成API文檔，lombok來簡化類遂跟，不過這兩者不是必須的，可用可不用婴渡。

參數(shù)校驗

一個接口一般對參數(shù)（請求數(shù)據(jù)）都會進行安全校驗幻锁，參數(shù)校驗的重要性自然不必多說，那么如何對參數(shù)進行校驗就有講究了边臼。

業(yè)務(wù)層校驗

首先我們來看一下最常見的做法哄尔，就是在業(yè)務(wù)層進行參數(shù)校驗：

publicString addUser(User user) {if(user ==null|| user.getId() ==null|| user.getAccount() ==null|| user.getPassword() ==null|| user.getEmail() ==null) {return"對象或者對象字段不能為空";? ? }if(StringUtils.isEmpty(user.getAccount()) || StringUtils.isEmpty(user.getPassword()) || StringUtils.isEmpty(user.getEmail())) {return"不能輸入空字符串";? ? }if(user.getAccount().length() <6|| user.getAccount().length() >11) {return"賬號長度必須是6-11個字符";? ? }if(user.getPassword().length() <6|| user.getPassword().length() >16) {return"密碼長度必須是6-16個字符";? ? }if(!Pattern.matches("^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$", user.getEmail())) {return"郵箱格式不正確";? ? }// 參數(shù)校驗完畢后這里就寫上業(yè)務(wù)邏輯? ? return "success"; }

這樣做當(dāng)然是沒有什么錯的，而且格式排版整齊也一目了然柠并，不過這樣太繁瑣了岭接，這還沒有進行業(yè)務(wù)操作呢光是一個參數(shù)校驗就已經(jīng)這么多行代碼，實在不夠優(yōu)雅臼予。

我們來改進一下鸣戴，使用Spring Validator和Hibernate Validator這兩套Validator來進行方便的參數(shù)校驗！這兩套Validator依賴包已經(jīng)包含在前面所說的web依賴包里了粘拾，所以可以直接使用窄锅。

Validator + BindResult進行校驗

Validator可以非常方便的制定校驗規(guī)則，并自動幫你完成校驗缰雇。首先在入?yún)⒗镄枰ｒ灥淖侄渭由献⒔?每個注解對應(yīng)不同的校驗規(guī)則入偷，并可制定校驗失敗后的信息：

@Datapublicclass User {@NotNull(message ="用戶id不能為空")? ? private Long id;@NotNull(message ="用戶賬號不能為空")@Size(min =6, max =11, message ="賬號長度必須是6-11個字符")? ? private String account;@NotNull(message ="用戶密碼不能為空")@Size(min =6, max =11, message ="密碼長度必須是6-16個字符")? ? private String password;@NotNull(message ="用戶郵箱不能為空")@Email(message ="郵箱格式不正確")? ? private String email;}校驗規(guī)則和錯誤提示信息配置完畢后，接下來只需要在接口需要校驗的參數(shù)上加上@Valid注解械哟，并添加BindResult參數(shù)即可方便完成驗證：@RestController@RequestMapping("user")public class UserController {@Autowiredprivate UserService userService;@PostMapping("/addUser")? ? public String addUser(@RequestBody@ValidUser user, BindingResult bindingResult) {// 如果有參數(shù)校驗失敗疏之，會將錯誤信息封裝成對象組裝在BindingResult里? ? ? ? for (ObjectError error : bindingResult.getAllErrors()) {? ? ? ? ? ? return error.getDefaultMessage();? ? ? ? }? ? ? ? return userService.addUser(user);? ? }}

這樣當(dāng)請求數(shù)據(jù)傳遞到接口的時候Validator就自動完成校驗了，校驗的結(jié)果就會封裝到BindingResult中去暇咆，如果有錯誤信息我們就直接返回給前端锋爪，業(yè)務(wù)邏輯代碼也根本沒有執(zhí)行下去丙曙。

此時，業(yè)務(wù)層里的校驗代碼就已經(jīng)不需要了：

publicStringaddUser(User user){// 直接編寫業(yè)務(wù)邏輯? ? return "success"; }

現(xiàn)在可以看一下參數(shù)校驗效果几缭。我們故意給這個接口傳遞一個不符合校驗規(guī)則的參數(shù)河泳，先傳遞一個錯誤數(shù)據(jù)給接口，故意將password這個字段不滿足校驗條件：

{"account":"12345678","email":"123@qq.com","id":0,"password":"123"}

再來看一下接口的響應(yīng)數(shù)據(jù)：

這樣是不是方便很多年栓？不難看出使用Validator校驗有如下幾個好處：

（1）簡化代碼拆挥，之前業(yè)務(wù)層那么一大段校驗代碼都被省略掉了。

（2）使用方便某抓，那么多校驗規(guī)則可以輕而易舉的實現(xiàn)纸兔，比如郵箱格式驗證，之前自己手寫正則表達式要寫那么一長串否副，還容易出錯汉矿，用Validator直接一個注解搞定。（還有更多校驗規(guī)則注解备禀，可以自行去了解哦）

（3）減少耦合度洲拇，使用Validator能夠讓業(yè)務(wù)層只關(guān)注業(yè)務(wù)邏輯，從基本的參數(shù)校驗邏輯中脫離出來曲尸。

使用Validator+ BindingResult已經(jīng)是非常方便實用的參數(shù)校驗方式了赋续，在實際開發(fā)中也有很多項目就是這么做的，不過這樣還是不太方便另患，因為你每寫一個接口都要添加一個BindingResult參數(shù)纽乱，然后再提取錯誤信息返回給前端。

這樣有點麻煩昆箕，并且重復(fù)代碼很多（盡管可以將這個重復(fù)代碼封裝成方法）鸦列。我們能否去掉BindingResult這一步呢？當(dāng)然是可以的鹏倘！

Validator + 自動拋出異常

我們完全可以將BindingResult這一步給去掉：

@PostMapping("/addUser")public String addUser(@RequestBody@ValidUser user) {returnuserService.addUser(user);}

去掉之后會發(fā)生什么事情呢薯嗤？直接來試驗一下，還是按照之前一樣故意傳遞一個不符合校驗規(guī)則的參數(shù)給接口纤泵。此時我們觀察控制臺可以發(fā)現(xiàn)接口已經(jīng)引發(fā)MethodArgumentNotValidException異常了：

其實這樣就已經(jīng)達到我們想要的效果了应民，參數(shù)校驗不通過自然就不執(zhí)行接下來的業(yè)務(wù)邏輯，去掉BindingResult后會自動引發(fā)異常夕吻，異常發(fā)生了自然而然就不會執(zhí)行業(yè)務(wù)邏輯诲锹。也就是說，我們完全沒必要添加相關(guān)BindingResult相關(guān)操作嘛涉馅。

不過事情還沒有完归园，異常是引發(fā)了，可我們并沒有編寫返回錯誤信息的代碼呀稚矿，那參數(shù)校驗失敗了會響應(yīng)什么數(shù)據(jù)給前端呢庸诱？

我們來看一下剛才異常發(fā)生后接口響應(yīng)的數(shù)據(jù)：

沒錯捻浦，是直接將整個錯誤對象相關(guān)信息都響應(yīng)給前端了！這樣就很難受桥爽，不過解決這個問題也很簡單朱灿，就是我們接下來要講的全局異常處理！

全局異常處理

參數(shù)校驗失敗會自動引發(fā)異常钠四，我們當(dāng)然不可能再去手動捕捉異常進行處理盗扒，不然還不如用之前BindingResult方式呢。又不想手動捕捉這個異常缀去，又要對這個異常進行處理侣灶，那正好使用SpringBoot全局異常處理來達到一勞永逸的效果！

基本使用

首先缕碎，我們需要新建一個類褥影，在這個類上加上@ControllerAdvice或@RestControllerAdvice注解，這個類就配置成全局處理類了咏雌。（這個根據(jù)你的Controller層用的是@Controller還是@RestController來決定）

然后在類中新建方法凡怎，在方法上加上@ExceptionHandler注解并指定你想處理的異常類型，接著在方法內(nèi)編寫對該異常的操作邏輯赊抖，就完成了對該異常的全局處理统倒！

我們現(xiàn)在就來演示一下對參數(shù)校驗失敗拋出的MethodArgumentNotValidException全局處理：

@RestControllerAdvicepublicclassExceptionControllerAdvice{@ExceptionHandler(MethodArgumentNotValidException.class)publicStringMethodArgumentNotValidExceptionHandler(MethodArgumentNotValidExceptione){// 從異常對象中拿到ObjectError對象? ? ? ? ObjectError objectError = e.getBindingResult().getAllErrors().get(0);? ? ? ? // 然后提取錯誤提示信息進行返回? ? ? ? return objectError.getDefaultMessage();? ? } }

我們再來看下這次校驗失敗后的響應(yīng)數(shù)據(jù)：

沒錯，這次返回的就是我們制定的錯誤提示信息熏迹！我們通過全局異常處理優(yōu)雅的實現(xiàn)了我們想要的功能檐薯！以后我們再想寫接口參數(shù)校驗凝赛，就只需要在入?yún)⒌某蓡T變量上加上Validator校驗規(guī)則注解注暗，然后在參數(shù)上加上@Valid注解即可完成校驗，校驗失敗會自動返回錯誤提示信息墓猎，無需任何其他代碼捆昏！更多的校驗思路：SpringBoot實現(xiàn)通用的接口參數(shù)校驗

自定義異常

全局處理當(dāng)然不會只能處理一種異常，用途也不僅僅是對一個參數(shù)校驗方式進行優(yōu)化毙沾。在實際開發(fā)中骗卜，如何對異常處理其實是一個很麻煩的事情。傳統(tǒng)處理異常一般有以下煩惱：

是捕獲異常(try…catch)還是拋出異常(throws)

是在controller層做處理還是在service層處理又或是在dao層做處理

處理異常的方式是啥也不做左胞，還是返回特定數(shù)據(jù)寇仓，如果返回又返回什么數(shù)據(jù)

不是所有異常我們都能預(yù)先進行捕捉，如果發(fā)生了沒有捕捉到的異常該怎么辦烤宙？

以上這些問題都可以用全局異常處理來解決遍烦，全局異常處理也叫統(tǒng)一異常處理，全局和統(tǒng)一處理代表什么躺枕？代表規(guī)范服猪！規(guī)范有了供填，很多問題就會迎刃而解！

全局異常處理的基本使用方式大家都已經(jīng)知道了罢猪，我們接下來更進一步的規(guī)范項目中的異常處理方式：自定義異常近她。

在很多情況下，我們需要手動拋出異常膳帕，比如在業(yè)務(wù)層當(dāng)有些條件并不符合業(yè)務(wù)邏輯粘捎，我這時候就可以手動拋出異常從而觸發(fā)事務(wù)回滾。那手動拋出異常最簡單的方式就是throw new RuntimeException("異常信息")了备闲，不過使用自定義會更好一些：

自定義異成味耍可以攜帶更多的信息，不像這樣只能攜帶一個字符串恬砂。

項目開發(fā)中經(jīng)常是很多人負責(zé)不同的模塊咧纠，使用自定義異常可以統(tǒng)一了對外異常展示的方式泻骤。

自定義異常語義更加清晰明了漆羔，一看就知道是項目中手動拋出的異常。

我們現(xiàn)在就來開始寫一個自定義異常：

@Getter //只要getter方法狱掂，無需setterpublic class APIException extends RuntimeException {? ? privateintcode;? ? private String msg;? ? public APIException() {? ? ? ? this(1001,"接口錯誤");? ? }? ? public APIException(String msg) {? ? ? ? this(1001, msg);? ? }? ? public APIException(intcode, String msg) {? ? ? ? super(msg);? ? ? ? this.code = code;? ? ? ? this.msg = msg;? ? }}

在剛才的全局異常處理類中記得添加對我們自定義異常的處理：

@ExceptionHandler(APIException.class)publicString APIExceptionHandler(APIException e) {returne.getMsg();}

這樣就對異常的處理就比較規(guī)范了演痒，當(dāng)然還可以添加對Exception的處理，這樣無論發(fā)生什么異常我們都能屏蔽掉然后響應(yīng)數(shù)據(jù)給前端趋惨，不過建議最后項目上線時這樣做鸟顺，能夠屏蔽掉錯誤信息暴露給前端，在開發(fā)中為了方便調(diào)試還是不要這樣做器虾。

現(xiàn)在全局異常處理和自定義異常已經(jīng)弄好了讯嫂，不知道大家有沒有發(fā)現(xiàn)一個問題，就是當(dāng)我們拋出自定義異常的時候全局異常處理只響應(yīng)了異常中的錯誤信息msg給前端兆沙，并沒有將錯誤代碼code返回欧芽。這就要引申出我們接下來要講的東西了：數(shù)據(jù)統(tǒng)一響應(yīng)

數(shù)據(jù)統(tǒng)一響應(yīng)

現(xiàn)在我們規(guī)范好了參數(shù)校驗方式和異常處理方式，然而還沒有規(guī)范響應(yīng)數(shù)據(jù)葛圃！比如我要獲取一個分頁信息數(shù)據(jù)千扔，獲取成功了呢自然就返回的數(shù)據(jù)列表，獲取失敗了后臺就會響應(yīng)異常信息库正，即一個字符串曲楚，就是說前端開發(fā)者壓根就不知道后端響應(yīng)過來的數(shù)據(jù)會是啥樣的！所以褥符，統(tǒng)一響應(yīng)數(shù)據(jù)是前后端規(guī)范中必須要做的龙誊！

自定義統(tǒng)一響應(yīng)體

統(tǒng)一數(shù)據(jù)響應(yīng)第一步肯定要做的就是我們自己自定義一個響應(yīng)體類，無論后臺是運行正常還是發(fā)生異常属瓣，響應(yīng)給前端的數(shù)據(jù)格式是不變的载迄！那么如何定義響應(yīng)體呢讯柔？關(guān)于異常的設(shè)計：如何更優(yōu)雅的設(shè)計異常

可以參考我們自定義異常類，也來一個響應(yīng)信息代碼code和響應(yīng)信息說明msg：

@GetterpublicclassResultVO{/**? ? * 狀態(tài)碼护昧，比如1000代表響應(yīng)成功? ? */privateint code;/**? ? * 響應(yīng)信息魂迄，用來說明響應(yīng)情況? ? */privateString msg;/**? ? * 響應(yīng)的具體數(shù)據(jù)? ? */privateTdata;publicResultVO(Tdata) {this(1000,"success",data);? ? }publicResultVO(int code, String msg, Tdata) {this.code = code;this.msg = msg;this.data=data;? ? }}

然后我們修改一下全局異常處理那的返回值：

@ExceptionHandler(APIException.class)public ResultVO APIExceptionHandler(APIException e) {//注意哦，這里返回類型是自定義響應(yīng)體returnnew ResultVO<>(e.getCode(),"響應(yīng)失敗", e.getMsg());} @ExceptionHandler(MethodArgumentNotValidException.class)public ResultVO MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {? ? ObjectError objectError = e.getBindingResult().getAllErrors().get(0);//注意哦惋耙，這里返回類型是自定義響應(yīng)體returnnew ResultVO<>(1001,"參數(shù)校驗失敗", objectError.getDefaultMessage());}

我們再來看一下此時如果發(fā)生異常了會響應(yīng)什么數(shù)據(jù)給前端：

OK统台，這個異常信息響應(yīng)就非常好了台妆，狀態(tài)碼和響應(yīng)說明還有錯誤提示數(shù)據(jù)都返給了前端蒲稳，并且是所有異常都會返回相同的格式胳徽！異常這里搞定了，別忘了我們到接口那也要修改返回類型灭美，我們新增一個接口好來看看效果：

@GetMapping("/getUser")publicResultVOgetUser(){? ? User user =newUser();? ? user.setId(1L);? ? user.setAccount("12345678");? ? user.setPassword("12345678");? ? user.setEmail("123@qq.com");returnnewResultVO<>(user);}

看一下如果響應(yīng)正確返回的是什么效果：

這樣無論是正確響應(yīng)還是發(fā)生異常推溃，響應(yīng)數(shù)據(jù)的格式都是統(tǒng)一的，十分規(guī)范届腐！

數(shù)據(jù)格式是規(guī)范了铁坎，不過響應(yīng)碼code和響應(yīng)信息msg還沒有規(guī)范呀！大家發(fā)現(xiàn)沒有犁苏，無論是正確響應(yīng)硬萍，還是異常響應(yīng)，響應(yīng)碼和響應(yīng)信息是想怎么設(shè)置就怎么設(shè)置围详，要是10個開發(fā)人員對同一個類型的響應(yīng)寫10個不同的響應(yīng)碼朴乖，那這個統(tǒng)一響應(yīng)體的格式規(guī)范就毫無意義！所以助赞，必須要將響應(yīng)碼和響應(yīng)信息給規(guī)范起來买羞。

響應(yīng)碼枚舉

要規(guī)范響應(yīng)體中的響應(yīng)碼和響應(yīng)信息用枚舉簡直再恰當(dāng)不過了，我們現(xiàn)在就來創(chuàng)建一個響應(yīng)碼枚舉類：

@GetterpublicenumResultCode {? ? SUCCESS(1000,"操作成功"),? ? FAILED(1001,"響應(yīng)失敗"),? ? VALIDATE_FAILED(1002,"參數(shù)校驗失敗"),? ? ERROR(5000,"未知錯誤");privateintcode;privateString msg;? ? ResultCode(intcode, String msg) {this.code = code;this.msg = msg;? ? } }

然后修改響應(yīng)體的構(gòu)造方法嫉拐，讓其只準接受響應(yīng)碼枚舉來設(shè)置響應(yīng)碼和響應(yīng)信息：

publicResultVO(Tdata) {this(ResultCode.SUCCESS,data);}publicResultVO(ResultCode resultCode, Tdata) {this.code = resultCode.getCode();this.msg = resultCode.getMsg();this.data=data;}

然后同時修改全局異常處理的響應(yīng)碼設(shè)置方式：

@ExceptionHandler(APIException.class)publicResultVOAPIExceptionHandler(APIExceptione){// 注意哦哩都，這里傳遞的響應(yīng)碼枚舉? ? return new ResultVO<>(ResultCode.FAILED, e.getMsg());} @ExceptionHandler(MethodArgumentNotValidException.class)public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {? ? ObjectError objectError = e.getBindingResult().getAllErrors().get(0);? ? // 注意哦魁兼，這里傳遞的響應(yīng)碼枚舉? ? return new ResultVO<>(ResultCode.VALIDATE_FAILED, objectError.getDefaultMessage());}

這樣響應(yīng)碼和響應(yīng)信息只能是枚舉規(guī)定的那幾個婉徘，就真正做到了響應(yīng)數(shù)據(jù)格式、響應(yīng)碼和響應(yīng)信息規(guī)范化咐汞、統(tǒng)一化盖呼！這些可以參考：Java項目構(gòu)建基礎(chǔ)：統(tǒng)一結(jié)果，統(tǒng)一異常化撕，統(tǒng)一日志

全局處理響應(yīng)數(shù)據(jù)

接口返回統(tǒng)一響應(yīng)體 + 異常也返回統(tǒng)一響應(yīng)體几晤，其實這樣已經(jīng)很好了，但還是有可以優(yōu)化的地方植阴。要知道一個項目下來定義的接口搞個幾百個太正常不過了蟹瘾，要是每一個接口返回數(shù)據(jù)時都要用響應(yīng)體來包裝一下好像有點麻煩圾浅，有沒有辦法省去這個包裝過程呢？當(dāng)然是有滴憾朴，還是要用到全局處理狸捕。

首先，先創(chuàng)建一個類加上注解使其成為全局處理類众雷。然后繼承ResponseBodyAdvice接口重寫其中的方法灸拍，即可對我們的controller進行增強操作，具體看代碼和注釋：

@RestControllerAdvice(basePackages = {"com.rudecrab.demo.controller"}) // 注意哦砾省，這里要加上需要掃描的包public class ResponseControllerAdvice implements ResponseBodyAdvice {? ? @Override? ? public boolean supports(MethodParameter returnType, Class> aClass) {//如果接口返回的類型本身就是ResultVO那就沒有必要進行額外的操作鸡岗，返回falsereturn!returnType.getGenericParameterType().equals(ResultVO.class);? ? }? ? @Override? ? public Object beforeBodyWrite(Object data, MethodParameter returnType, MediaType mediaType, Class> aClass, ServerHttpRequest request, ServerHttpResponse response) {//String類型不能直接包裝，所以要進行些特別的處理if(returnType.getGenericParameterType().equals(String.class)) {? ? ? ? ? ? ObjectMapper objectMapper = new ObjectMapper();? ? ? ? ? ? try {//將數(shù)據(jù)包裝在ResultVO里后编兄，再轉(zhuǎn)換為json字符串響應(yīng)給前端returnobjectMapper.writeValueAsString(new ResultVO<>(data));? ? ? ? ? ? } catch (JsonProcessingException e) {? ? ? ? ? ? ? ? throw new APIException("返回String類型錯誤");? ? ? ? ? ? }? ? ? ? }? ? ? ? // 將原本的數(shù)據(jù)包裝在ResultVO里returnnew ResultVO<>(data);? ? }}

重寫的這兩個方法是用來在controller將數(shù)據(jù)進行返回前進行增強操作轩性，supports方法要返回為true才會執(zhí)行beforeBodyWrite方法，所以如果有些情況不需要進行增強操作可以在supports方法里進行判斷狠鸳。對返回數(shù)據(jù)進行真正的操作還是在beforeBodyWrite方法中炮姨，我們可以直接在該方法里包裝數(shù)據(jù)，這樣就不需要每個接口都進行數(shù)據(jù)包裝了碰煌，省去了很多麻煩舒岸。

我們可以現(xiàn)在去掉接口的數(shù)據(jù)包裝來看下效果：

@GetMapping("/getUser")publicUsergetUser(){? ? User user =newUser();? ? user.setId(1L);? ? user.setAccount("12345678");? ? user.setPassword("12345678");? ? user.setEmail("123@qq.com");// 注意哦，這里是直接返回的User類型芦圾，并沒有用ResultVO進行包裝? ? return user;}

然后我們來看下響應(yīng)數(shù)據(jù)：

成功對數(shù)據(jù)進行了包裝蛾派！

注意：beforeBodyWrite方法里包裝數(shù)據(jù)無法對String類型的數(shù)據(jù)直接進行強轉(zhuǎn)，所以要進行特殊處理个少，這里不講過多的細節(jié)洪乍，有興趣可以自行深入了解。

總結(jié)

自此整個后端接口基本體系就構(gòu)建完畢了

通過Validator + 自動拋出異常來完成了方便的參數(shù)校驗

通過全局異常處理 + 自定義異常完成了異常操作的規(guī)范

通過數(shù)據(jù)統(tǒng)一響應(yīng)完成了響應(yīng)數(shù)據(jù)的規(guī)范

多個方面組裝非常優(yōu)雅的完成了后端接口的協(xié)調(diào)夜焦，讓開發(fā)人員有更多的經(jīng)歷注重業(yè)務(wù)邏輯代碼壳澳，輕松構(gòu)建后端接口

加Q群：1106441130? ?免費領(lǐng)取一份學(xué)習(xí)資料，包含（Java學(xué)習(xí)視頻茫经，技術(shù)文檔巷波，電子書籍，面試題等資料...）

還可免費學(xué)習(xí)Java基礎(chǔ)到項目實戰(zhàn)課程卸伞！