谈谈 Spring boot Controller API 怎麽设计

说到了 controller 就不得不说一下 API，简单来说就是负责建立客户所需的内容和产生所需回应的内容。在 Web 世界中可以把它认为是一个取得 Web 资源的中介。RESTful API 是一种规范，它应用了 HTTP 协定来存取资源，可以藉由 GET、PUT、POST 和 DELETE 等 HTTP Method 进行资源操作。

REST API 支援的资料格式有以下，其中 application/json 被广泛使用

• application/json
• application/xml
• application/x-www-form-urlencoded
• multipart/form-data
• 等

在 Spring Boot 中的 controller 我们可以藉由 @RestController 宣告说我要建立 RESTful Web 服务。以下描述了基本的 API 宣告和使用

宣告一个 GET 请求的资源，这通常用来获取资料库单一资源或是整个资源。当中的范例对应请求会是

curl -X GET -H "Content-Type: application/json" -d '{model 的资讯}' http://localhost:8080/api/list

@GetMapping(value = "/api/list", produces = APPLICATION_JSON_VALUE)
public ResponseEntity<?> post(Model model) {
    // do something
}

宣告一个 POST 请求的资源，用於新增资料或是上传档案等。当中的范例对应请求会是

curl -X POST -H "Content-Type: application/json" -d '{model 的资讯}' http://localhost:8080/api/upload

@PostMapping(value = "/api/upload",
            consumes = MULTIPART_FORM_DATA_VALUE,
            produces = APPLICATION_JSON_VALUE)
public ResponseEntity<?> post(Model model) {
    // do something
}

宣告一个 DELETE 请求的资源，用於删除资源。当中的范例对应请求会是

curl -X DELETE http://localhost:8080/api/{id} # {id} 通常会是删除该物件的主键或是可识别该物件的唯一值

@DeleteMapping("/api/{id}")
public ResponseEntity<Void> delete(@PathVariable String id) {
    // do something
}

宣告一个 PUT 请求的资源，用於更新资源。当中的范例对应请求会是

curl -X PUT -H "Content-Type: application/json" -d '{model 资讯}' http://localhost:8080/api/{id} # {id} 通常会是删除该物件的主键或是可识别该物件的唯一值

@PutMapping(value = "/api/{id}", consumes = APPLICATION_JSON_VALUE)
public void update(@PathVariable String id, Model model){
    // do something
}

当中 MULTIPART_FORM_DATA_VALUE（档案）, APPLICATION_JSON_VALUE（JSON 格式） 可以约束 Client 必须传什麽数据，当违反时将会回传 4XX 代码。

• @RequestParam
  • request header
  • 通常用於 GET 请求
  • Content-Type 为 application/x-www-form-urlencoded
    • 表单中插入数据
• @PathVariable
  • URI Template Pattern ex. http://localhost:8080/api/show/101?param1=10&param2=20

@RequestMapping("/show/{id}")
    public String getEmployee(@PathVariable(value="id") String id,
    @RequestParam(value="param1") String param1,
    @RequestParam(value="param2") String param2){
.......
}