Spring Boot中OpenAPI生成枚举参数的校验与优雅错误处理

/user/search:
  get:
    parameters:
      - in: query
        name: sortBy
        description: Field to sort by
        required: true
        schema:
          $ref: "#/components/schemas/UserSearchSortBy"
schemas:
  UserSearchSortBy:
    type: string
    enum: [first_name, last_name, email, phone_number]

@RequestMapping(
    method = RequestMethod.GET,
    value = "/user/search",
    produces = { "application/json" }
)
default ResponseEntity<UsersResponsePageableModel> _searchUsers(
    // ... 其他参数 ...
    @NotNull @Parameter(name = "sortBy", description = "Field to sort by", required = true) @Valid @RequestParam(value = "sortBy", required = true) UserSearchSortByModel sortBy,
    // ... 其他参数 ...
) {
    return searchUsers(currentPage, pageSize, sortOrder, sortBy, searchQuery);
}

import org.springframework.core.convert.converter.Converter;
import org.springframework.core.convert.converter.ConverterFactory;
import org.springframework.stereotype.Component;

@Component
public class StringToEnumConverterFactory implements ConverterFactory<String, Enum> {

    // 内部类，实现具体的字符串到枚举的转换逻辑
    private static class StringToEnumConverter<T extends Enum> implements Converter<String, T> {
        private final Class<T> enumType;

        public StringToEnumConverter(Class<T> enumType) {
            this.enumType = enumType;
        }

        @Override
        public T convert(String source) {
            // 将输入字符串转换为大写并去除首尾空格，以匹配枚举常量的命名约定
            // 如果枚举常量是小写，则需要调整此处的转换逻辑
            return (T) Enum.valueOf(this.enumType, source.trim().toUpperCase());
        }
    }

    @Override
    public <T extends Enum> Converter<String, T> getConverter(Class<T> targetType) {
        // 返回一个针对特定目标枚举类型的转换器实例
        return new StringToEnumConverter<>(targetType);
    }
}

import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

@RestControllerAdvice // 标记为一个全局异常处理类
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ResponseEntity<Map<String, String>> handleMismatchException(MethodArgumentTypeMismatchException e) {
        String errorMessage = e.getMessage(); // 获取默认错误信息
        Class<?> parameterType = e.getParameter().getParameterType(); // 获取参数的类型

        // 检查异常是否与枚举类型参数有关
        if (parameterType.isEnum()) {
            Object[] enumConstants = parameterType.getEnumConstants(); // 获取枚举的所有常量
            if (enumConstants != null && enumConstants.length > 0) {
                // 如果能获取到参数名和传入的值，则构建更详细的错误信息
                if (e.getName() != null && !e.getName().isEmpty() && e.getValue() != null) {
                    errorMessage = String.format("无效的值 '%s' 针对字段 '%s'。", e.getValue(), e.getName()) +
                                   " 有效值包括: " + Arrays.asList(enumConstants);
                } else {
                    errorMessage = String.format("无效的枚举值。有效值包括: %s", Arrays.asList(enumConstants));
                }
            }
        }

        // 构建统一的错误响应体
        Map<String, String> errors = new HashMap<>();
        errors.put("message", errorMessage);

        // 返回 400 Bad Request 状态码和 JSON 格式的错误信息
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                             .header("Content-Type", MediaType.APPLICATION_JSON_VALUE)
                             .body(errors);
    }
}