Restful風格對接接口使用的規(guī)范

概要

本實例適合所有的開發(fā)，不僅僅是前后端分離項目，不分離項目使用的AJAX請求后臺也可以使用！

例如：

/**
	初學者都喜歡使用@RequestMapping注解直接在Controller的方法中進行映射
 */
	@RequestMapping("/queryById")
    public Demo queryById(Integer id) {
        ......
    }

大多數(shù)接口都包含新增、刪除、修改、分頁查詢、部分也查詢、按ID查詢等6個接口，這樣如果業(yè)務復雜的請求，一個Controller里面有過多的@RequestMapping映射，那里面映射的單詞都不一樣，那樣開發(fā)出來的代碼一眼看就是很糟糕?。?/p>

使用Restful風格只有在Controller類上有@RequestMapping注解，其中的方法只對應請求方式，比如分頁查詢的get請求直接使用 @GetMapping在方法上即可！如果有過多的get請求比如通過id查詢則使用地址傳參的方式 @GetMapping("{id}")然后在方法參數(shù)中加入@PathVariable("id") Integer id即可使用參數(shù)id!

@GetMapping("{id}")
    public Demo queryById(@PathVariable("id") Integer id) {
       ....
    }

以上只是對請求方式以及請求參數(shù)的一種寫法，這里還有就是返回參數(shù)的問題，在所有的接口請求中都會有著不同的返回，上面都是返回的一個Demo的實體對象，但是在業(yè)務操作中，比如再獲取列表的接口，那我們就需要返回的是一個集合，如果是修改的接口，那我們可能返回的是一個是否修改成功的標識，那樣一個Controller里面就很繁瑣了，如果遇到外鍵查詢可能不是一個實體的對象，則就需要單獨處理，所以我自己使用的就是一個封裝的一個返回對象JsonWrite

package com.ww.talk.util;

/**
 * @author maker
 * @desc 后臺返回前臺json格式
 */
public class JsonWrite {
    public JsonWrite() {
    }

    /**
     * 狀態(tài)碼
     */
    private String code;
    /**
     * 是否成功
     */
    private boolean success;


    /**
     * 提示消息
     */
    private String msg;
    /**
     * 返回的數(shù)據(jù)
     */
    private Object data;

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public boolean isSuccess() {
        return success;
    }

    public void setSuccess(boolean success) {
        this.success = success;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }

    public JsonWrite(String code, boolean success, String msg) {
        this.code = code;
        this.success = success;
        this.msg = msg;
    }


    public JsonWrite(String code, boolean success, String msg, Object data) {
        this.code = code;
        this.success = success;
        this.msg = msg;
        this.data = data;
    }

    /**
     * 自定義返回內容
     *
     * @param code
     * @param success
     * @param msg
     * @param data
     * @return
     */
    public static JsonWrite CUSTOMIZE(String code, boolean success, String msg, Object data) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(code);
        jsonWrite.setSuccess(success);
        jsonWrite.setMsg(msg);
        jsonWrite.setData(data);
        return jsonWrite;
    }

    /**
     * 自定義返回內容
     *
     * @param code
     * @param success
     * @param msg
     * @return
     */
    public static JsonWrite CUSTOMIZE(String code, boolean success, String msg) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(code);
        jsonWrite.setSuccess(success);
        jsonWrite.setMsg(msg);
        return jsonWrite;
    }

    /**
     * 操作成功，無數(shù)據(jù)傳遞
     *
     * @return
     */
    public static JsonWrite SUCCESS() {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(true);
        jsonWrite.setMsg(StatusCode.SUCCESS.getMsg());
        return jsonWrite;
    }

    /**
     * 操作成功，傳遞數(shù)據(jù)
     *
     * @return
     */
    public static JsonWrite SUCCESS(Object data) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(true);
        jsonWrite.setMsg(StatusCode.SUCCESS.getMsg());
        jsonWrite.setData(data);
        return jsonWrite;
    }

    /**
     * 操作失敗，無數(shù)據(jù)傳遞
     *
     * @return
     */
    public static JsonWrite ERROR() {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(false);
        jsonWrite.setMsg(StatusCode.SUCCESS.getMsg());
        return jsonWrite;
    }

    /**
     * 操作失敗，傳遞數(shù)據(jù)
     *
     * @param data
     * @return
     */
    public static JsonWrite ERROR(Object data) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(false);
        jsonWrite.setMsg(StatusCode.SUCCESS.getMsg());
        jsonWrite.setData(data);
        return jsonWrite;
    }

    /**
     * 操作成功，自定義消息
     *
     * @param msg
     * @return
     */
    public static JsonWrite SUCCESS(String msg) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(true);
        jsonWrite.setMsg(msg);
        return jsonWrite;
    }

    /**
     * 操作成功，傳遞數(shù)據(jù)及自定義消息
     *
     * @param msg
     * @param data
     * @return
     */
    public static JsonWrite SUCCESS(String msg, Object data) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(true);
        jsonWrite.setMsg(msg);
        jsonWrite.setData(data);
        return jsonWrite;
    }

    /**
     * 操作失敗，自定義消息
     *
     * @param msg
     * @return
     */
    public static JsonWrite ERROR(String msg) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(false);
        jsonWrite.setMsg(msg);
        return jsonWrite;
    }

    /**
     * 操作失敗，傳遞數(shù)據(jù)以及自定義消息
     *
     * @param msg
     * @param data
     * @return
     */
    public static JsonWrite ERROR(String msg, Object data) {
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SUCCESS.getCode());
        jsonWrite.setSuccess(false);
        jsonWrite.setMsg(msg);
        jsonWrite.setData(data);
        return jsonWrite;
    }

    /**
     * 系統(tǒng)錯誤
     */
    public static JsonWrite SYSTEMERROR(String msg, Object data){
        JsonWrite jsonWrite = new JsonWrite();
        jsonWrite.setCode(StatusCode.SERVERERROR.getCode());
        jsonWrite.setSuccess(false);
        jsonWrite.setMsg(msg);
        jsonWrite.setData(data);
        return jsonWrite;
    }
}

可以看到我們的返回實體JsonWrite有很多的構造方法，這樣可以滿足多種返回格式！比如之前上面的通過id請求的結果我們可以寫成：

/**
     * 通過主鍵查詢單條數(shù)據(jù)
     *
     * @param id 主鍵
     * @return 單條數(shù)據(jù)
     */
    @GetMapping("{id}")
    public JsonWrite queryById(@PathVariable("id") Integer id) {
        return JsonWrite.SUCCESS(this.userService.queryById(id));
    }

因為通過ID查詢一般不會出現(xiàn)查詢錯誤的情況，所以直接就是使用的SUCCESS的方法返回！

介紹

提示：上面的定義的JsonWrite類中也有其他的輔助類：StatusCode（返回狀態(tài)碼枚舉）

public enum StatusCode {
    /**
     * 狀態(tài)碼
     */
    SUCCESS("200", "OK"),
    BADREQUIRED("400", "Bad Request"),
    ACCESSERROR("401", "Access-Token Error"),
    AUTHERROR("403", "沒有權限"),
    NOTFOUND("404", "Not Found"),
    SERVERERROR("500", "Internal Server Error"),
    REPEAT("600", "Repeat request,Request Forbidden"),
    BADGATEWAY("502", "Bad Gateway"),
    SERVICEUNAVAILABLE("503", "Service Unavailable"),
    ACCOUNT_ERROR("1000", "賬戶不存在或被禁用"),
    API_NOT_EXISTS("1001", "請求的接口不存在"),
    API_NOT_PER("1002", "沒有該接口的訪問權限"),
    PARAMS_ERROR("1004", "參數(shù)錯誤或格式錯誤"),
    SIGN_ERROR("1005", "數(shù)據(jù)簽名錯誤"),
    API_DISABLE("1011", "查詢權限已被限制"),
    UNKNOWN_IP("1099", "非法IP請求");

    /**
     * 狀態(tài)碼
     */
    private String code;
    /**
     * 狀態(tài)描述
     */
    private String msg;

    public String getCode() {
        return code;
    }

    public String getMsg() {
        return msg;
    }

    StatusCode(String code, String msg) {
        this.code = code;
        this.msg = msg;
    }
}

不同的返回狀態(tài)嗎對應著不同的含義！這樣前端人員調用接口之后看到了返回狀態(tài)碼就知道對應的是什么問題，只有狀態(tài)碼為200的時候才是正常的返回正確結果！這也是一種對于前后端的規(guī)范！

案例

提示：這里我們編寫了一個案例，大家可以對照案例理解一下思路！

package com.ww.talk.controller;

import com.ww.talk.util.JsonWrite;
import com.ww.talk.util.TableGrid;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;

/**
 * (User)表控制層
 *
 * @author makejava
 */
@RestController
@RequestMapping("user")
public class UserController {
    /**
     * 服務對象
     */
    @Resource
    private UserService userService;
    /**
     * 分頁查詢
     *
     * @param tableGrid  篩選條件
     * @return 查詢結果
     */
    @GetMapping
    public JsonWrite queryByPage(TableGrid tableGrid) {
        return JsonWrite.SUCCESS(this.userService.queryByPage(tableGrid));
    }

    /**
     * 通過主鍵查詢單條數(shù)據(jù)
     *
     * @param id 主鍵
     * @return 單條數(shù)據(jù)
     */
    @GetMapping("{id}")
    public JsonWrite queryById(@PathVariable("id") Integer id) {
        return JsonWrite.SUCCESS(this.userService.queryById(id));
    }

    /**
     * 新增數(shù)據(jù)
     *
     * @param user 實體
     * @return 新增結果
     */
    @PostMapping
    public JsonWrite add(@RequestBody User user) {
        return this.userService.insert(user);
    }

    /**
     * 編輯數(shù)據(jù)
     *
     * @param user 實體
     * @return 編輯結果
     */
    @PutMapping
    public JsonWrite edit(@RequestBody User user) {
        return this.userService.update(user);
    }

    /**
     * 刪除數(shù)據(jù)
     *
     * @param id 主鍵
     * @return 刪除是否成功
     */
    @DeleteMapping("{id}")
    public JsonWrite deleteById(@PathVariable("id") Integer id) {
        return this.userService.deleteById(id);
    }
}

分析：

上面我們創(chuàng)建了一個UserController類，使用@RequestMapping(“user”)注解，這樣前端使用user接口調用都是進入此類中查詢對應的接口；然后我們定義了五個基礎方法，分別是：分頁查詢、通過注解id查詢、新增、修改和刪除；下面我們分析這五個接口對應的寫法

• 分頁查詢：

/**
     * 分頁查詢
     *
     * @param tableGrid  篩選條件
     * @return 查詢結果
     */
    @GetMapping
    public JsonWrite queryByPage(TableGrid tableGrid) {
        return JsonWrite.SUCCESS(this.userService.queryByPage(tableGrid));
    }

查詢都是Get請求，這個不用多說！前端使用接口名稱/user，并使用的是Get請求，則會進入方法中，方法參數(shù)是封裝的分頁實體，因為查詢列表的方法也是不可能有業(yè)務判斷或者業(yè)務報錯的，所以直接使用JsonWrite.SUCCESS返回給前端，查詢的數(shù)據(jù)是通過userService.queryByPage在userService的服務層處理，而JsonWrite.SUCCESS參數(shù)就是我們封裝的JsonWrite返回到前端的data屬性，前端在實體中通過.data獲取返回的查詢到的數(shù)據(jù)！

• 通過注解id查詢

/**
     * 通過主鍵查詢單條數(shù)據(jù)
     *
     * @param id 主鍵
     * @return 單條數(shù)據(jù)
     */
    @GetMapping("{id}")
    public JsonWrite queryById(@PathVariable("id") Integer id) {
        return JsonWrite.SUCCESS(this.userService.queryById(id));
    }

同樣是獲取數(shù)據(jù)的Get請求，前端使用接口名稱/user/3，這里的3是指要查詢的數(shù)據(jù)id，方法正確使用get請求之后進入此方法中，通過@PathVariable("id")注解后臺可以直接使用到參數(shù)id，由于通過id查詢的這個id肯定是數(shù)據(jù)庫存在的，所以這里同樣使用JsonWrite.SUCCESS直接成功返回數(shù)據(jù)！

• 新增

/**
     * 新增數(shù)據(jù)
     *
     * @param user 實體
     * @return 新增結果
     */
    @PostMapping
    public JsonWrite add(@RequestBody User user) {
        return this.userService.insert(user);
    }

新增為Post請求，咱們不多說！前端使用/user接口以及Post請求方式將會進入此方法中，前端傳入的是一個實體對象，所以我們使用@RequestBody來注明我們接受的數(shù)據(jù)是一個User對象，因為新增的時候一般會有業(yè)務判斷，比如用戶名是否存在之類的，如果重復了存在了則是新增失敗，所以我們再Controller中返回的是一個userService.insert服務層返回的結果，我們看下服務層代碼：

/**
     * 新增數(shù)據(jù)
     *
     * @param user 實例對象
     * @return 實例對象
     */
    @Override
    public JsonWrite insert(User user) {
        int count = this.userDao.insert(user);
        if(count >0){
            return JsonWrite.SUCCESS("數(shù)據(jù)新增成功!");
        }else{
            return JsonWrite.ERROR("數(shù)據(jù)新增失敗，請檢查數(shù)據(jù)！");
        }
    }

這里在服務層的新增接口中可以看到，這里是做了一個簡單的判斷，因為對于mysql來說，執(zhí)行新增操作如果成功會返回執(zhí)行成功的條數(shù)，也就是新增一條數(shù)據(jù)成功會返回一個Integer類型的1，如果失敗則為0，直接判斷count執(zhí)行數(shù)據(jù)庫的結果來返回數(shù)據(jù)，前端使用JsonWrite的success屬性是否為true來判斷是否成功！

• 修改

/**
     * 編輯數(shù)據(jù)
     *
     * @param user 實體
     * @return 編輯結果
     */
    @PutMapping
    public JsonWrite edit(@RequestBody User user) {
        return this.userService.update(user);
    }

修改為Put請求，前端直接使用/user并使用put請求方式即進入當前方法中，使用@RequestBody注解接收需要被修改的User對象數(shù)據(jù)，然后執(zhí)行userService.update中的修改接口，因為修改的業(yè)務基本上都需要有判斷所以這里直接就是返回的服務層接口，判斷是否通過以及返回前臺的數(shù)據(jù)由服務層處理！

• 刪除

/**
     * 刪除數(shù)據(jù)
     *
     * @param id 主鍵
     * @return 刪除是否成功
     */
    @DeleteMapping("{id}")
    public JsonWrite deleteById(@PathVariable("id") Integer id) {
        return this.userService.deleteById(id);
    }

刪除請求方式為delete，這里只是簡單的通過id刪除數(shù)據(jù)，從前臺傳入一個id即可，傳入的方式與通過id獲取是一樣的，/user/3這里的3是指需要被刪除的對象的id，因為刪除也是有很多的業(yè)務判斷，所以返回的數(shù)據(jù)結果有service的服務層處理。

小結

提示：細心的同學可能已經發(fā)現(xiàn)了，能夠直接出結果的都是查詢接口，不能出結果的都是操作的數(shù)據(jù)，針對數(shù)據(jù)庫來說就是‘查詢數(shù)據(jù)’和‘操作數(shù)據(jù)’，凡是查詢數(shù)據(jù)的都不應該會有問題，所以直接的success，而操作數(shù)據(jù)的都有可能伴隨著業(yè)務的判斷是失敗所以是在業(yè)務層中區(qū)處理返回對象