Java開發中RestFul服務介面規範

REST介紹

representational State Transfer (REST) 是一種架構原則，其中將 web 服務視為資源，可以由其 URL 唯一標識。RESTful Web 服務的關鍵特點是明確使用 HTTP 方法來表示不同的操作的呼叫。

REST 的基本設計原則對典型 CRUD 操作使用 HTTP 協議方法：

POST - 建立資源

GET - 檢索資源

PUT – 更新資源

DELETE - 刪除資源

REST 服務的主要優勢在於：

它們是跨平臺 (Java、.net、PHP 等）高度可重用的，因為它們都依賴基本 HTTP 協議。

它們使用基本的 XML，而不是複雜的 SOAP XML，使用非常方便。

基於 REST 的 web 服務日益成為後端企業服務整合的首選方法。與基於 SOAP 的 web 服務相比，它的程式設計模型簡單，而本機 XML（而不是 SOAP ）的使用減少了序列化和反序列化過程的複雜性，並且不再需要其他作用相同的第三方庫。

​​​​​​​編寫目的

編寫本文的目的是為了規範專案系統功能進行模組化、服務化，將使用者的操作以服務的方式提供。系統與系統之間遵循服務規範，將系統與系統之間的互動轉為定製化服務互動，以實現系統與系統之間的整合。

​​​​​​​編寫原則

1. 可定址性（Addressability）REST 中的所有東西都基於資源 的概念。資源與 OOP 中的物件或其他名詞不同，它是一種抽象，必須可以通過 URI 定址或訪問。
2. 介面一致性（Interface uniformity）與 SOAP 或其他標準不同，REST 要求用來操縱資源的方法或動詞不是任意的。這意味著 RESTful 服務的開發人員只能使用 HTTP 支援的方法，比如 GET、PUT、POST、DELETE 等等。因此不需要使用 WSDL 等服務描述語言。
3. 無狀態（Statelessness）為了增強可伸縮性，伺服器端不儲存客戶機的狀態資訊。這使伺服器不與特定的客戶機相繫結，負載平衡變得簡單多了。這還讓伺服器更容易監視、更可靠。
4. 具象（Representational）客戶機總是與資源的某種具象互動，絕不會直接與資源本身互動。同一資源還可以有多個具象。理論上說，持有資源的具象的任何客戶機應該有操縱底層資源的足夠資訊。
5. 連通性（Connectedness）任何基於 REST 的系統都應該預見到客戶機需要訪問相關的資源，應該在返回的資源具象中包含這些資源。例如，可以以超連結的形式包含特定 RESTful 服務的操作序列中的相關步驟，讓客戶機可以根據需要訪問它們。基於 REST 的 Web 服務日益成為後端企業服務整合的

GET，DELETE，PUT和POST的典型用法

GET用法

​​​​​​​

安全且冪等

獲取表示

變更時獲取表示（快取）

200（OK） - 表示已在響應中發出

204（無內容） - 資源有空表示

301（Moved Permanently） - 資源的URI已被更新

303（See Other） - 其他（如，負載均衡）

304（not modified）- 資源未更改（快取）

400 （bad request）- 指代壞請求（如，引數錯誤）

404 （not found）- 資源不存在

406 （not acceptable）- 服務端不支援所需表示

500 （internal server error）- 通用錯誤響應

503 （Service Unavailable）- 服務端當前無法處理

POST用法

不安全且不冪等 使用服務端管理的（自動產生）的例項號建立資源 建立子資源 部分更新資源 如果沒有被修改，則不過更新資源（樂觀鎖） 200（OK）- 如果現有資源已被更改 201（created）- 如果新資源被建立 202（accepted）- 已接受處理請求但尚未完成（非同步處理） 301（Moved Permanently）- 資源的URI被更新 303（See Other）- 其他（如，負載均衡） 400（bad request）- 指代壞請求 404 （not found）- 資源不存在 406 （not acceptable）- 服務端不支援所需表示 409 （conflict）- 通用衝突 412 （Precondition Failed）- 前置條件失敗（如執行條件更新時的衝突） 415 （unsupported media type）- 接受到的表示不受支援 500 （internal server error）- 通用錯誤響應 503 （Service Unavailable）- 服務當前無法處理請求

PUT用法

不安全但冪等 用客戶端管理的例項號建立一個資源 通過替換的方式更新資源 如果未被修改，則更新資源（樂觀鎖） 200 （OK）- 如果已存在資源被更改 201 （created）- 如果新資源被建立 301（Moved Permanently）- 資源的URI已更改 303 （See Other）- 其他（如，負載均衡） 400 （bad request）- 指代壞請求 404 （not found）- 資源不存在 406 （not acceptable）- 服務端不支援所需表示 409 （conflict）- 通用衝突 412 （Precondition Failed）- 前置條件失敗（如執行條件更新時的衝突） 415 （unsupported media type）- 接受到的表示不受支援 500 （internal server error）- 通用錯誤響應 503 （Service Unavailable）- 服務當前無法處理請求

DELETE用法

不安全但冪等 刪除資源 200 （OK）- 資源已被刪除 301 （Moved Permanently）- 資源的URI已更改 303 （See Other）- 其他，如負載均衡 400 （bad request）- 指代壞請求 404 （not found）- 資源不存在 409 （conflict）- 通用衝突 500 （internal server error）- 通用錯誤響應 503 （Service Unavailable）- 服務端當前無法處理請求

Java開發中RestFul用法舉例

//@RestController 代替 @Controller,省略以後的 @ResponseBody
@RestController
@RequestMapping("/student")
public class StudentController {
    @Autowired
    private StudentService studentservice;
    /**
     * 顯示所有
     * url:"http://localhost/student/findall"
     * 
     * @return
     */
    @RequestMapping(value = "/findall")
    public List<Student> findAllStudent() {
        return studentservice.findAllStudent();
    }

    /**
     * 查詢 restful 風格 
     * url:"http://localhost/student/findone/1"
     * 
     * @param id
     * @return
     */

    // == @RequestMapping(value = "/findone/{id}", method = RequestMethod.GET)
    @GetMapping("/findone/{id}")
    public Student findStudentRestful(@PathVariable("id") Integer id) {
        return studentservice.findStudent(id);
    }

    /**
     * 刪除 restful 風格
     * url:"http://localhost/student/deleteone/4"
     * 注意無法通過瀏覽器的連結來模擬檢驗,可以通過 jquery的 $.ajax方法，並type="delete"
     * 
     * @param id
     */
    // == @RequestMapping(value = "/deleteone/{id}", method = RequestMethod.DELETE)
    @DeleteMapping("/deleteone/{id}")
    public void deleteStudentRestful(@PathVariable("id") Integer id) {
        studentservice.deleteStudent(id);
    }


    /**
     * 增加 restful 風格
     * url:"http://localhost/student/addone"
     * 通過<form>表單模擬驗證
     * 
     * @param student
     */
    // == @RequestMapping(value="/addone",method=RequestMethod.POST)
    @PostMapping("/addone")
    public void addStudentRestful(Student student) {
        studentservice.addStudent(student);
    }


    /**
     * 修改 restful 風格
     * url:"http://localhost/student/updateone"
     * 驗證：可以通過 jquery的 $.ajax方法，並type="put",同時注意data形式——A=a&B=b&C=c
     * 
     * @param student
     */
    // == @RequestMapping(value="/addone",method=RequestMethod.PUT)
    @PutMapping("/updateone")
    public void updateStudentRestful(Student student) {
        studentservice.updateStudent(student);
    }
}