【无标题】

如何有效组织Spring MVC API端点

在开发基于Spring MVC的RESTful API时，有效地组织和设计端点是至关重要的。本文将介绍如何使用路径参数、请求参数对象和JSON请求体来实现灵活而清晰的API设计。

1. 路径传参 (@PathVariable)

定义：@PathVariable 用于从URL路径中提取参数。通常用于RESTful风格的API中，用于标识资源。

示例：

@GetMapping("/products/{id}")
public ResponseEntity<Product> getProductById(@PathVariable("id") Long id) {
    // 使用id获取产品信息
    return ResponseEntity.ok(productService.getProductById(id));
}

请求URL：/products/123

说明：{id} 是URL路径的一部分，@PathVariable("id") 注解会将路径中的 123 提取出来并赋值给方法参数 id。

2. 请求参数 (@RequestParam)

定义：@RequestParam 用于从URL查询参数中提取参数。通常用于传递简单的查询条件、过滤条件等。

示例：

@GetMapping("/products")
public ResponseEntity<List<Product>> getProductsByCategory(@RequestParam("category") String category) {
    // 使用category过滤产品列表
    return ResponseEntity.ok(productService.getProductsByCategory(category));
}

请求URL：/products?category=electronics

说明：category 是URL查询参数的一部分，@RequestParam("category") 注解会将查询参数中的 electronics 提取出来并赋值给方法参数 category。

3. 使用对象封装请求参数

定义：使用对象封装多个请求参数，使代码更加简洁和可读。Spring MVC会自动将查询参数映射到对象的对应字段中。

示例：

控制器方法：

@GetMapping("/page")
@ApiOperation("区域服务分页查询")
public PageResult<ServeResDTO> page(ServePageQueryReqDTO servePageQueryReqDTO) {
    return serveService.page(servePageQueryReqDTO);
}

DTO类：

public class ServePageQueryReqDTO {
    private Integer page;
    private Integer size;
    private String sortBy;
    private String order;
    // Getter和Setter方法
}

请求URL：/page?page=1&size=10&sortBy=name&order=asc

说明：Spring MVC会自动将查询参数 page=1、size=10、sortBy=name 和 order=asc 映射到 ServePageQueryReqDTO 对象中的对应字段。

4. 结合使用 @PathVariable 和 @RequestParam

定义：在同一个方法中同时使用路径变量和请求参数，适用于更复杂的查询场景。

假设我们有一个RESTful API，用于获取某个用户的订单列表，并可以根据订单状态进行筛选。

示例：

@GetMapping("/users/{userId}/orders")
public ResponseEntity<List<Order>> getUserOrders(
    @PathVariable("userId") Long userId,
    OrderFilterRequest filterRequest) {
    // 根据userId获取用户的订单列表，并根据filterRequest中的条件进行过滤
    List<Order> orders = orderService.getUserOrders(userId, filterRequest);
    return ResponseEntity.ok(orders);
}

// OrderFilterRequest.java
public class OrderFilterRequest {
    private String status;
    // 可以添加其他过滤条件的字段
    // Getter和Setter方法
}

请求URL：/users/123/orders?status=completed

说明：

• userId 是路径参数，通过 @PathVariable 注解提取。
• OrderFilterRequest 是一个请求参数对象，它包含了过滤条件，Spring MVC会自动将查询参数映射到该对象的对应字段中。

5. JSON格式的请求体

除了使用路径参数和请求参数对象形式外，还可以通过JSON格式的请求体传递数据，适用于传递更复杂的结构化数据，例如创建或更新资源时。

示例

假设我们有一个RESTful API，用于创建新的用户。

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody CreateUserRequest createUserRequest) {
    // 创建用户，并返回创建的用户信息
    User newUser = userService.createUser(createUserRequest);
    return ResponseEntity.status(HttpStatus.CREATED).body(newUser);
}

// CreateUserRequest.java
public class CreateUserRequest {
    private String username;
    private String email;
    // 可以添加其他需要的字段
    // Getter和Setter方法
}

请求URL：POST /users

请求体：

{
  "username": "john_doe",
  "email": "john.doe@example.com"
}

说明：

• @RequestBody 注解用于将HTTP请求的JSON体映射到方法参数中的对象。
• CreateUserRequest 是一个包含用户创建信息的POJO类。

使用场景选择

• 路径参数和请求参数对象形式适合简单的查询和过滤条件，通常用于GET请求。
• JSON格式的请求体适合传递更复杂的结构化数据，例如创建或更新资源时使用POST、PUT等请求。

总结

• 路径传参 (@PathVariable)：

  • 通过在方法参数中使用 @PathVariable 注解，从URL路径中提取变量。
  • 适用于标识资源的场景。
  • 示例：/products/{id}。

• 请求参数 (@RequestParam)：

  • 通过在方法参数中使用 @RequestParam 注解，从URL查询参数中提取变量。
  • 适用于传递简单的查询条件、过滤条件等。
  • 示例：/products?category=electronics。

• 对象封装请求参数：

  • 通过创建一个DTO对象，将多个请求参数封装在一个对象中，Spring MVC自动映射。
  • 适用于参数较多的场景。
  • 示例：/page?page=1&size=10&sortBy=name&order=asc。

• 结合使用：

  • 在同一个方法中同时使用路径变量和请求参数，处理更复杂的查询场景。
  • 示例：/products/123?currency=USD。
• 路径参数和请求参数对象形式结合使用，能够处理多种不同类型的参数，适用于不同的查询和过滤需求。
• JSON格式的请求体适用于传递更复杂的结构化数据，特别是创建或更新资源时，能够提供更灵活的数据传输方式。