能否为RestEasy的QueryParams提供自定义解析器？

问题场景 #

我正在使用Jakarta搭配RestEasy框架，编写了如下简单接口：

@GET
@Path("expectsLong")
@Produces(MediaType.TEXT_PLAIN)
public Response expectsLong(
    @QueryParam("searchValue") final Long searchValue)
{
    return ok(searchValue);
}

我仅通过注解实现参数校验（不采用ParamConverter方案），示例如下：

@NotNull @Min(1) @Max(10) @QueryParam("searchValue") final Long searchValue)

按照设计，所有校验注解仅在String转Long的初始解析步骤完成后生效，流程如下：

1. 步骤1：解析 "666" -> 666
2. 步骤2：@NotNull -> 判断666是否为空？否 -> 校验通过
3. 步骤3：@Min(1) -> 判断666是否>=1？是 -> 校验通过
4. 步骤4：@Max(10) -> 判断666是否<=10？是 -> 校验通过

注：若使用与参数类型不匹配的注解，比如对Long类型的searchValue使用@Pattern，会触发错误：HV000030: No validator could be found for constraint

问题痛点 #

解析步骤的异常处理与校验注解不一致：

• 注解校验不通过时会返回HTTP 400及明确提示信息；
• 但解析失败时会被RestEasy捕获，返回HTTP 500或404，无法向调用者清晰提示“该字符串无法解析为数字”。

解决方案：自定义参数解析器 #

可以为RestEasy提供自定义解析器来统一处理类型转换异常，让它返回与注解校验一致的HTTP 400错误及提示，具体实现如下：

1. 自定义Long类型转换器 #

实现RestEasy的StringConverter<T>接口，在转换失败时抛出自定义的BadRequest异常：

public class CustomLongConverter implements StringConverter<Long> {
    @Override
    public Long fromString(String value) {
        if (value == null || value.isBlank()) {
            return null; // 空值交由@NotNull注解校验
        }
        try {
            return Long.parseLong(value);
        } catch (NumberFormatException e) {
            throw new BadRequestException("参数searchValue无法解析为有效数字");
        }
    }

    @Override
    public String toString(Long value) {
        return value != null ? value.toString() : null;
    }
}

2. 注册自定义转换器 #

通过@Provider注解标记转换器，让RestEasy自动扫描加载，或者在应用启动类中手动注册：

@ApplicationPath("/api")
public class RestApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<>();
        classes.add(CustomLongConverter.class);
        // 添加你的资源类、其他Provider等
        return classes;
    }
}

3. 统一异常返回格式 #

自定义ExceptionMapper来捕获BadRequestException，返回规范的HTTP 400响应：

@Provider
public class BadRequestExceptionMapper implements ExceptionMapper<BadRequestException> {
    @Override
    public Response toResponse(BadRequestException exception) {
        return Response.status(Response.Status.BAD_REQUEST)
                .entity(exception.getMessage())
                .type(MediaType.TEXT_PLAIN)
                .build();
    }
}

这样配置后，当调用者传入无法解析为Long的字符串时，接口会返回HTTP 400状态码及“参数searchValue无法解析为有效数字”的提示，与注解校验的返回逻辑保持一致。

内容的提问来源于stack exchange，提问作者jeancallisti