Spring Boot控制器如何将路径与查询参数合并为单个DTO？

现有OpenAPI定义 #

参数定义 #

filterParameter:
  name: addCartEntriesByFilterParameter
  in: query
  schema:
    type: object
    required:
      - "applicationCode"
    properties:
      applicationCode:
        type: string
      [...others]

接口定义 #

/api/v1/applications/{applicationCode}/filtered:
put:
  tags:
  - Tag
  operationId: byFilter
  summary: Add filters
  parameters:
    - $ref: '#/components/parameters/applicationCode'
    - $ref: '#/components/parameters/filterParameter'
  responses:
    "400":
      $ref: '#/components/responses/400BadRequest'
    "404":
      $ref: '#/components/responses/404NotFound'
    "200":
      $ref: '#/components/responses/Response'

需求 #

我们希望仅用单个DTO作为接口参数，避免路径和查询参数中重复的applicationCode，期望的OpenAPI定义如下：

/api/v1/applications/{applicationCode}/filtered:
put:
  tags:
  - Tag
  operationId: byFilter
  summary: Add filters
  parameters:
    - $ref: '#/components/parameters/filterParameter'
  responses:
    "400":
      $ref: '#/components/responses/400BadRequest'
    "404":
      $ref: '#/components/responses/404NotFound'
    "200":
      $ref: '#/components/responses/Response'

请问在Spring Boot控制器中，有没有办法把路径参数和查询参数整合到同一个对象中接收？

完全可以实现，以下是具体步骤：

1. 定义整合后的DTO #

创建包含所有所需字段的DTO类，路径参数和查询参数的字段统一放在这里：

public class FilterRequestDTO {
    // 对应路径参数{applicationCode}
    private String applicationCode;
    // 其他查询参数字段
    private String otherParam1;
    private Integer otherParam2;

    // 可手动编写Getter/Setter，或使用Lombok的@Data注解简化
}

2. 配置控制器方法 #

Spring提供两种方式将混合参数绑定到DTO：

方式一：手动映射参数 #

适合需要自定义参数处理逻辑的场景：

@PutMapping("/api/v1/applications/{applicationCode}/filtered")
public ResponseEntity<Response> byFilter(
        @PathVariable String applicationCode,
        @RequestParam Map<String, String> queryParams) {
    FilterRequestDTO dto = new FilterRequestDTO();
    dto.setApplicationCode(applicationCode);
    // 手动将查询参数映射到DTO字段
    dto.setOtherParam1(queryParams.get("otherParam1"));
    dto.setOtherParam2(Integer.parseInt(queryParams.get("otherParam2")));
    
    // 执行业务逻辑
    return ResponseEntity.ok(new Response());
}

方式二：Spring自动绑定（推荐） #

直接在DTO字段上标注对应注解，让Spring自动完成参数绑定：

public class FilterRequestDTO {
    @PathVariable("applicationCode")
    private String applicationCode;
    
    @RequestParam
    private String otherParam1;
    
    @RequestParam
    private Integer otherParam2;

    // Getter/Setter
}

控制器方法直接接收DTO即可：

@PutMapping("/api/v1/applications/{applicationCode}/filtered")
public ResponseEntity<Response> byFilter(FilterRequestDTO dto) {
    // 执行业务逻辑
    return ResponseEntity.ok(new Response());
}

3. 适配OpenAPI定义 #

按照你期望的结构修改OpenAPI定义，仅引用filterParameter即可。需要确保filterParameter的schema包含applicationCode字段，这样API文档会正确展示所有参数（路径+查询）。

如果使用OpenAPI代码生成工具，可能需要调整配置（比如Maven插件的additionalModelTypeAnnotations参数或自定义模板），确保生成的代码能适配Spring的混合参数绑定逻辑。

内容的提问来源于stack exchange，提问作者José Puente Fuentes