Spring Boot REST API 端点映射最佳实践

Posted 2023-03-08

【中文标题】Spring Boot REST API 端点映射最佳实践

【英文标题】：Spring Boot REST API Endpoint Mapping best practice

【发布时间】：2018-12-04 18:20:51

【问题描述】：

我正在使用以下端点 URL 映射和 HTTP 方法，例如（POST、DELETE、GET、PUT）

POST 创建新交易 -

@PostMapping("/trade")

DELETE 用于删除具有特定 ID 的交易 -

@DeleteMapping("/trade/id")

GET 获取特定交易的详细信息 -

@GetMapping("/trade/id")

PUT 用于更新交易详情 -

@PutMapping(“/trade/id”)

GET for Retrieve all Trade list of the collection -

@GetMapping("/trades")

Spring 目前支持五种类型的内置注解，用于处理不同类型的传入 HTTP 请求方法，即 GET、POST、PUT、DELETE 和 PATCH。这些注释是：

@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@PatchMapping

从命名约定可以看出，每个注解都是为了处理各自传入的请求方法类型，即@GetMapping用于处理GET类型的请求方法，@PostMapping用于处理POST类型的请求方法，等等

如果我在这里遗漏了什么请提出建议

【问题讨论】：

您需要指定API版本

【参考方案1】：

添加API版本如

@RestController
@RequestMapping("/API/V1")
public class TestController 

@RequestMapping("/greeting")
    public String greeting( 
        return "welcome";
    

【讨论】：

这个答案好像少了一个RequestMethod？

【参考方案2】：

对于版本控制，您可以使用多种方法：

URI 路径： 在端点的 URL 路径中包含版本号。 例如v1 中的/api/v1/trade：

public class TradeController 

  @GetMapping("v1/trade")
  public Trade tradeVersionOne() 
    return new Trade("123","Trade Result");
  

  @GetMapping("v2/trade")
  public Trade tradeVersionTwo() 
    return new Trade(new RealTimeTrade("123", "Real Time Trade Result"));
  

查询参数： 将版本号作为具有指定名称的查询参数传递。 例如：?version=1 in /api/trade?version=1：

public class TradeController 

  @GetMapping(name = "v1/trade", params = "version=1")
  public Trade tradeVersionOne() 
    return new Trade("123","Trade Result");
  

  @GetMapping(name = "v2/trade", params = "version=2")
  public Trade tradeVersionTwo() 
    return new Trade(new RealTimeTrade("123", "Real Time Trade Result"));
  
 

自定义 HTTP 标头： 在请求中定义一个包含版本号的新标头。

内容协商： 在Accept 标头中包含版本号以及接受的内容类型。