Stop Using Map for Spring Boot Controller Parameters

Environment: Spring Boot 3.5.0.

In web development the controller layer is the entry point for client requests. Using explicit Data Transfer Objects (DTO) for request parameters makes the API definition clear, enables validation annotations such as @NotNull and @Size, and improves readability and robustness.

Although a Map<String, Object> can accept arbitrary keys and seems flexible, it introduces a series of problems.

@RestController
@RequestMapping("/api")
public class ApiController {
  @PostMapping("/query")
  public ResponseEntity<?> query(@RequestBody Map<String, Object> params) {
    // TODO
    return ResponseEntity.ok(params);
  }
}

2.1 Poor code readability – A Map parameter is a black box. From the method signature developers cannot tell which keys are required, their types, or optional fields. They must read the whole method body and trace every params.get() call to understand the contract.

What are the required keys? (e.g., keyword, category, platform)

What are their data types? (e.g., articleId as String or Long)

Are there optional parameters?

2.2 Breaks developer tools – Tools such as Swagger, Postman collections, and IDE auto‑completion rely on concrete type information. When a Map is used, Swagger cannot infer the keys and values, so generated API docs become useless, and other tools lose their assistance.

Replacing the Map with a DTO restores clear documentation and tool support.

// Good practice: use DTO
@ApiOperation("Query product information")
@PostMapping("/query")
public ResponseEntity<?> getContent(@RequestBody QueryDto dto) {
  // TODO
}

@ApiModel("Query product request parameters")
public class QueryDto {
  @ApiModelProperty("Query keyword")
  @NotNull(message = "Keyword is required")
  private String keyword;

  @ApiModelProperty("Product category")
  @NotNull(message = "Category is required")
  private Integer category;
  // ...other fields
}

2.3 Messy validation logic – With a Map the developer writes many if statements to check presence, type, and value ranges, which is verbose and error‑prone. Adding or changing a parameter requires manual updates to all checks.

Using a DTO together with Spring’s validation annotations moves the validation to the framework and makes the code concise.

@PostMapping("/query")
public ResponseEntity<?> getContent(@Validated @RequestBody QueryDto dto, BindingResult result) {
  if (result.hasErrors()) {
    List<String> errors = result.getFieldErrors()
        .stream()
        .map(err -> err.getField() + ":" + err.getDefaultMessage())
        .toList();
    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(errors);
  }
  // TODO
}

public class QueryDto {
  @NotNull(message = "Keyword is required")
  private String keyword;

  @NotNull(message = "Category is required")
  private Integer category;
  // ...other fields
}

In summary, the perceived “flexibility” of using a Map is short‑sighted. It sacrifices long‑term maintainability, readability, tool integration, and reliable validation for a small amount of immediate convenience.