ArgumentResolver — chuỗi resolver, type conversion, custom annotation

TL;DR: Khi Spring MVC gọi một controller method, nó không truyền thẳng HttpServletRequest vào — thay vào đó RequestMappingHandlerAdapter iterate qua một danh sách HandlerMethodArgumentResolver, hỏi từng resolver "mày handle được param này không?" qua supportsParameter(), rồi để resolver nào trả true thực hiện resolveArgument() trả về giá trị Java. Type conversion (String → int, LocalDate, Enum) chạy qua ConversionService bên trong resolver. Thiết kế này cho phép thêm resolver mới mà không sửa code Spring — đó là lý do @CurrentUser custom hoạt động như annotation built-in. Pitfall cốt lõi: mass assignment khi DTO expose field nhạy cảm cho client gán.

Bài Request binding đã trình bày 6 annotation source (@PathVariable, @RequestParam, @RequestBody…). Bài này bóc tầng bên dưới chúng: chuỗi resolver chạy ra sao, type conversion xảy ra ở đâu, và vì sao bạn có thể tự thêm resolver mà framework không cần biết.

1. Bức tranh tổng: request đến controller

Trước khi mổ resolver, cần nhìn toàn bộ con đường một request đi qua:

flowchart TB
  Req["HTTP Request"] --> DS["DispatcherServlet"]
  DS --> RMHA["RequestMappingHandlerAdapter"]
  RMHA --> Resolvers["HandlerMethodArgumentResolver list<br/>(iterate cho moi param)"]
  Resolvers --> Method["controller.method(arg1, arg2, ...)"]
  Method --> HMReturnValueHandler["HandlerMethodReturnValueHandler"]
  HMReturnValueHandler --> Res["HTTP Response"]

RequestMappingHandlerAdapter là trái tim — nó nhận handler method đã match URL, rồi làm hai việc: resolve argument (bài này) và handle return value (bài ResponseEntity & HTTP status codes). Bài này tập trung nửa đầu.

2. Cơ chế bên dưới — chuỗi HandlerMethodArgumentResolver

HandlerMethodArgumentResolver là interface SPI (Service Provider Interface) — ai implement được, Spring chấp nhận:

// org/springframework/web/method/support/HandlerMethodArgumentResolver.java
public interface HandlerMethodArgumentResolver {

    // Buoc 1: Spring hoi "nguoi nay co handle duoc param nay khong?"
    boolean supportsParameter(MethodParameter parameter);

    // Buoc 2: neu supportsParameter() tra true, Spring goi de lay gia tri
    Object resolveArgument(
        MethodParameter parameter,
        ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest,
        WebDataBinderFactory binderFactory
    ) throws Exception;
}

Tại sao thiết kế này mở rộng được? Spring đăng ký khoảng 30+ resolver built-in (mỗi annotation một resolver). Khi bạn thêm resolver custom, nó xếp vào đầu danh sách — Spring iterate từ đầu, resolver nào trả true trước thì được gọi. Không cần sửa Spring, không cần subclass gì — chỉ thêm vào list. Đây là Open/Closed Principle ở framework level.

Luồng đầy đủ khi RequestMappingHandlerAdapter invoke method:

flowchart TB
  Param["MethodParameter: @PathVariable Long id"] --> Iter["iterate resolver list"]
  Iter --> Q1{"supportsParameter()"}
  Q1 -->|"false"| Next["next resolver"]
  Next --> Q1
  Q1 -->|"true"| Resolve["resolveArgument()<br/>lay gia tri tu request"]
  Resolve --> Value["Long 42"]
  Value --> Invoke["method(42, ...)"]

Mỗi parameter được xử lý độc lập — 5 param trong method signature thì 5 lần iterate resolver list. Thứ tự resolver quyết định ai thắng khi hai resolver cùng supportsParameter() trả true (hiếm nhưng xảy ra khi custom resolver không kiểm tra kỹ).

2.1 Các resolver built-in quan trọng

Pageable không có annotation — resolver của nó dùng type check thay annotation: supportsParameter() trả true khi parameter.getParameterType() == Pageable.class.

3. Type conversion — String vào Java type

HTTP chỉ truyền byte. Query param, path variable, header — tất cả đều là String ở tầng HTTP. Spring cần convert "42" → Long, "2026-04-01" → LocalDate, "ACTIVE" → OrderStatus.

Cơ chế đứng sau: ConversionService — một registry các Converter<S, T> và Formatter<T>. Resolver gọi ConversionService.convert(stringValue, targetType) trước khi trả về giá trị.

flowchart LR
  Raw["String: '42'<br/>(tu URL path)"] --> CS["ConversionService"]
  CS --> Conv["StringToNumberConverter<br/>(built-in)"]
  Conv --> Result["Long: 42"]

3.1 Conversion built-in

Spring Boot auto-configure DefaultConversionService với nhiều converter sẵn:

Khi conversion thất bại (vd ?id=abc cho Long), resolver throw MethodArgumentTypeMismatchException và Spring map thành 400 Bad Request. Fail-fast an toàn.

3.2 Enum conversion — case-sensitive pitfall

public enum OrderStatus { PENDING, ACTIVE, COMPLETED, CANCELLED }

@GetMapping("/orders")
public List<OrderDto> list(@RequestParam OrderStatus status) { ... }

Với request ?status=active, StringToEnumConverter gọi OrderStatus.valueOf("active") và nhận IllegalArgumentException — client lãnh 400. Default case-sensitive — "ACTIVE" đúng, "active" sai.

Fix: custom Converter<String, OrderStatus>:

@Component
public class OrderStatusConverter implements Converter<String, OrderStatus> {

    public OrderStatus convert(String source) {
        try {
            return OrderStatus.valueOf(source.toUpperCase());
        } catch (IllegalArgumentException e) {
            throw new MethodArgumentTypeMismatchException(
                source, OrderStatus.class, "status", null, e
            );
        }
    }
}

Spring Boot tự detect @Component implement Converter và đăng ký vào ConversionService. Không cần config thêm.

3.3 Date format — ISO vs custom

Boot 3 mặc định parse LocalDate theo ISO 8601 (yyyy-MM-dd). Format khác cần @DateTimeFormat:

@GetMapping("/orders")
public List<OrderDto> list(
    // ISO default -- Boot 3 khong can annotation
    @RequestParam LocalDate from,

    // Custom format -- phai khai @DateTimeFormat
    @RequestParam @DateTimeFormat(pattern = "dd/MM/yyyy") LocalDate to
) { ... }

Annotation @DateTimeFormat không liên quan Bean Validation — nó chỉ hướng dẫn ConversionService dùng DateTimeFormatter nào để parse String.

3.4 Custom Converter cho type phức tạp

Khi cần parse "USD:42.50" → Money record:

public record Money(String currency, BigDecimal amount) {
    public static Money parse(String s) {
        String[] parts = s.split(":");
        return new Money(parts[0], new BigDecimal(parts[1]));
    }
}

@Component
public class MoneyConverter implements Converter<String, Money> {
    public Money convert(String source) {
        return Money.parse(source);   // throw IllegalArgumentException -> 400
    }
}

// Use:
@GetMapping("/products")
public List<ProductDto> list(@RequestParam Money priceRange) { ... }
// ?priceRange=USD:10.00

Một lần đăng ký — dùng được mọi endpoint.

4. Custom ArgumentResolver — @CurrentUser

Scenario: 80% endpoint cần "user hiện tại" từ JWT. Nếu mỗi method tự parse SecurityContextHolder, code lặp và khó test.

// Truoc: verbose, kho test
@GetMapping("/profile")
public UserDto profile() {
    Authentication auth = SecurityContextHolder.getContext().getAuthentication();
    User user = (User) auth.getPrincipal();
    return UserDto.from(user);
}

Custom resolver encapsulate logic một lần, dùng qua annotation:

Bước 1 — định nghĩa annotation:

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface CurrentUser {}

@Retention(RUNTIME) bắt buộc — annotation phải còn khi resolver đọc qua reflection.

Bước 2 — implement resolver:

@Component
public class CurrentUserResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        // Chi nhan param co annotation @CurrentUser
        return parameter.hasParameterAnnotation(CurrentUser.class);
    }

    @Override
    public Object resolveArgument(
        MethodParameter parameter,
        ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest,
        WebDataBinderFactory binderFactory
    ) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth == null || !auth.isAuthenticated()) {
            throw new IllegalStateException("No authenticated user in context");
        }
        return auth.getPrincipal();   // tra ve User object
    }
}

Bước 3 — đăng ký vào Spring MVC:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private CurrentUserResolver currentUserResolver;

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(currentUserResolver);   // them vao dau list
    }
}

Bước 4 — sử dụng:

// Sau: concise, declarative, de test
@GetMapping("/profile")
public UserDto profile(@CurrentUser User user) {
    return UserDto.from(user);
}

@PostMapping("/orders")
public OrderDto create(@CurrentUser User user, @Valid @RequestBody OrderRequest req) {
    return orderService.create(user, req);
}

4.1 Vì sao thiết kế này tốt hơn @RequestAttribute

So sánh 3 cách inject current user:

Custom resolver thắng về tất cả: declarative, type-safe, test chỉ cần mock hoặc inject resolver trong WebMvcTest slice.

5. Pitfall — mass assignment vulnerability

Mass assignment xảy ra khi DTO expose field client không được phép gán, và resolver bind toàn bộ JSON body vào DTO đó.

// DTO nguy hiem
public record UserUpdateRequest(
    String name,
    String email,
    boolean isAdmin,          // CLIENT KHONG DUOC SET truong nay
    String role               // Tuong tu
) {}

@PutMapping("/users/{id}")
public UserDto update(@PathVariable Long id,
                      @RequestBody UserUpdateRequest req) {
    userService.update(id, req);
}

Client gửi:

{
  "name": "Alice",
  "email": "[email protected]",
  "isAdmin": true,
  "role": "ADMIN"
}

Jackson bind toàn bộ body vào record — isAdmin = true, role = "ADMIN" được gán. Đây là privilege escalation — lỗ hổng nghiêm trọng.

Fix đúng — split DTO theo authority:

// DTO cho user thuong
public record UserPublicUpdate(
    @NotBlank String name,
    @Email String email
) {}

// DTO cho admin (endpoint rieng, role rieng)
public record UserAdminUpdate(
    @NotBlank String name,
    @Email String email,
    boolean isAdmin,
    String role
) {}

@PutMapping("/users/{id}")
@PreAuthorize("hasRole('USER')")
public UserDto update(@PathVariable Long id,
                      @RequestBody @Valid UserPublicUpdate req) {
    return userService.updatePublic(id, req);
}

@PutMapping("/admin/users/{id}")
@PreAuthorize("hasRole('ADMIN')")
public UserDto adminUpdate(@PathVariable Long id,
                           @RequestBody @Valid UserAdminUpdate req) {
    return userService.updateAdmin(id, req);
}

Vì sao @JsonIgnore không đủ an toàn: @JsonIgnore ngăn serialize, nhưng theo config Jackson, đôi khi vẫn deserialize được nếu setter tồn tại hoặc có annotation override. Cách duy nhất tin cậy: DTO không chứa field nhạy cảm từ đầu.

@Bean
public ObjectMapper objectMapper() {
  return JsonMapper.builder()
      .configure(StreamReadConstraints.builder()
          .maxNestingDepth(20)
          .maxStringLength(5_000_000)
          .build())
      .build();
}

6. Cơ chế bên dưới — resolver registration và ordering

Khi Spring Boot khởi động, WebMvcAutoConfiguration tạo RequestMappingHandlerAdapter và đăng ký resolver theo thứ tự cố định. Custom resolver qua addArgumentResolvers() được thêm vào đầu list (ưu tiên cao hơn built-in).

flowchart TB
  Boot["Spring Boot startup"] --> RMHA["RequestMappingHandlerAdapter init"]
  RMHA --> BuiltIn["built-in resolvers<br/>(PathVariable, RequestParam, RequestBody...)"]
  RMHA --> Custom["WebMvcConfigurer.addArgumentResolvers()<br/>xu ly truoc built-in"]
  Custom --> List["resolver list<br/>[CustomResolver, ..., PathVariableResolver, ...]"]

Hệ quả thứ tự: nếu custom resolver có supportsParameter() quá rộng (vd return true cho mọi param), nó sẽ intercept cả param built-in. Kiểm tra annotation cụ thể (hasParameterAnnotation) hoặc type cụ thể (getParameterType() == MyType.class) để tránh conflict.

Tại sao không kế thừa resolver built-in? Mỗi resolver đã optimize cho annotation/type cụ thể. Kế thừa → phụ thuộc implementation detail có thể thay đổi giữa Spring versions. Compose annotation mới + resolver riêng an toàn hơn.

7. Liên hệ các bài khác

• Request binding: bài trước trình bày 6 annotation source (@PathVariable, @RequestParam…). Bài này giải thích cơ chế bên dưới mà 6 annotation đó dựa vào — mỗi annotation là một HandlerMethodArgumentResolver implementation.
• ResponseEntity & HTTP status codes: bài tiếp giải quyết nửa còn lại — khi method controller trả về, HandlerMethodReturnValueHandler xử lý return value thành HTTP response. Đối xứng hoàn toàn với resolver.
• Bean Validation (bài 06 module 03): @Valid trên @RequestBody không liên quan resolver — nó trigger WebDataBinder.validate() sau khi resolver trả về object. Pitfall quên @Valid → constraint không chạy dù DTO có annotation đầy đủ.
• Spring Security @AuthenticationPrincipal: resolver built-in của Spring Security — cùng pattern với custom @CurrentUser bài này trình bày, nhưng tích hợp sẵn auth context.

Tóm tắt

• HandlerMethodArgumentResolver là interface SPI: supportsParameter() quyết định ai handle, resolveArgument() trả giá trị Java từ request.
• Spring iterate danh sách resolver cho mỗi parameter; custom resolver thêm qua WebMvcConfigurer.addArgumentResolvers() được ưu tiên trước built-in.
• Type conversion chạy qua ConversionService: String → primitive/Enum/UUID/Date. Enum mặc định case-sensitive — custom Converter<String, E> để fix.
• @DateTimeFormat hướng dẫn formatter cho date; Boot 3 default ISO 8601 cho LocalDate/LocalDateTime.
• Custom resolver (@CurrentUser) encapsulate logic một chỗ — type-safe, testable, không lặp.
• Mass assignment: DTO chứa field nhạy cảm → split DTO theo authority; không dựa vào @JsonIgnore.

Tự kiểm tra

@Component
public class OrderStatusConverter implements Converter<String, OrderStatus> {
  public OrderStatus convert(String source) {
      return OrderStatus.valueOf(source.toUpperCase());
  }
}

spring.mvc.converters.preferred-json-mapper=jackson
# Hoac dung DeserializationFeature tren ObjectMapper:
spring.jackson.deserialization.read-enums-using-to-string=false

Bài tiếp theo: ResponseEntity & HTTP status codes