RestFul API

一般的API都是什麼樣子的呢？

查詢 /user/query?name=tom              GET
詳情 /user/getInfo?id=1                GET
建立 /user/create?name=tom            POST
修改 /user/update?id=1&name=jay       POST
刪除 /user/delete?id=1                 GET

那麼我們希望的RESTFul API 是什麼樣子的呢？

查詢    /user?name=tom             GET
詳情    /user/1                    GET
建立    /user                      POST
修改    /user/1                    PUT
刪除    /user/1                    DELETE
 

簡單的說，RESTFul就是：1、用URL描述資源2、使用HTTP方法描述行為，使用HTTP狀態碼來表示不同的結果3、使用json互動資料4、RESTFul只是一種風格，並不是強制的標準

RESTFul 成熟度模型

Level0：使用Http作為傳輸方式Level1：引入資源概念，每個資源都有對應的URLLevel2：使用HTTP方法進行不同的操作，使用HTTP狀態碼來表示不同的結果Level3：使用超媒體，在資源的表達中包含了連結資訊

編寫第一個RESTFul API

首先我們先了解一些常用的註解

1、@RestController 標明此Controller提供RestAPI2、@RequestMapping及其變體。對映http請求URL到java方法3、@RequestParam 對映請求引數到java方法的引數4、@PageableDefault指定分頁引數預設值

直接拿出程式碼模組來講解吧！

package com.myself.web.controller;

import com.fasterxml.jackson.annotation.JsonView;
import com.myself.dto.User;
import com.myself.dto.UserQueryCondition;
import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import org.springframework.data.domain.Pageable;
import org.springframework.data.web.PageableDefault;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
 * @author  MySelf
 * @create  2018/9/15
 * @desc User Controller 層
 **/
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 獲取使用者列表
     * @RequestMapping(value = "/user", method = RequestMethod.GET)
     * @RequestParam(name = "username",required = false,defaultValue = "tom") String nickname
     * @param condition {@link UserQueryCondition}
     * @return {@link List}
     */
    @GetMapping()
    @JsonView(User.UserSimpleView.class)
    public List<User> query(UserQueryCondition condition,@PageableDefault(page = 2,size = 17,sort = "username,asc") Pageable pageable){
        //反射工具
        System.out.println(ReflectionToStringBuilder.toString(condition, ToStringStyle.MULTI_LINE_STYLE));

        System.out.println(pageable.getPageSize());
        System.out.println(pageable.getPageNumber());
        System.out.println(pageable.getSort());

        List<User> users = new ArrayList<>();
        users.add(new User());
        users.add(new User());
        users.add(new User());
        return users;
    }

    /**
     * 獲取使用者資訊 正則校驗引數必須為數字
     * @RequestMapping(value = "/user/{id:\\d+}", method = RequestMethod.GET)
     * @param idxxx {@link String}
     * @return {@link User}
     */
    @GetMapping("/{id:\\d+}")
    @JsonView(User.UserDetailView.class)
    public User getInfo(@PathVariable(name = "id") String idxxx){
        User user = new User();
        user.setUsername("tom");
        return user;
    }

}
 

User Bean 物件

package com.myself.dto;


import com.fasterxml.jackson.annotation.JsonView;

/**
 * @author  MySelf
 * @create  2018/9/15
 * @desc User Bean
 **/
public class User {

    /** 使用者簡單檢視 */
    public interface UserSimpleView {}

    /** 使用者詳情檢視 */
    public interface UserDetailView extends UserSimpleView {}

    /** 使用者名稱 */
    private String username;

    /** 使用者密碼 */
    private String password;

    @JsonView(UserSimpleView.class)
    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    @JsonView(UserDetailView.class)
    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

接下來我們就來講解一些註解的使用點，其實看著註解也能大致瞭解了。

首先我們在接受引數時，可以使用@PathVariable對映url片段到java方法的引數，同時也支援在url宣告中使用正則表示式，使用@JsonView控制json輸出內容。

我們需要在Bean中宣告對應的介面，並在值物件的get方法上指定檢視，最後在Controller方法上指定檢視即可。

還有就是，當我們在處理建立請求時，還要注意可以使用@RequestBody對映請求體到java方法引數，且要注意對日期型別引數的處理，也可以使用@Valid註解和BindingResult驗證請求引數的合法性並處理校驗結果。

本文是針對UncleCatMySelf/myself-security（基於Spring Security + Spring Social + Spring Security OAuth + REST服務開發的案例教程，Maven多模組開發）的GitHub專案的基礎演進。

如果本文對你有所幫助，歡迎關注本人技術公眾號，謝謝。