如何在MicroProfile中验证Path Parameter？数值超限未触发校验

问题现象 #

当PathParam参数key传入大于9的值（如11）时，接口未触发校验错误，反而返回有效响应。

请求示例 #

curl --location --request GET 'localhost:8080/v1/batch-tokens/11/action/count'

代码示例 #

@Path("/v1/batch-tokens")
public class BatchTokenResource implements Serializable {

    private static final Logger LOGGER = Logger.getLogger(BatchTokenResource.class.getName());
    private static final String LOG_HEADER = "[" + BatchTokenResource.class.getSimpleName() + "]::";

    @GET
    @Path("/{key}/action/count")
    public Response countTokenPerKey(
            @PathParam("key") @Min(value = 0) @Max(value = 9) 
            @Pattern(regexp = "^\\d$") String key
    ) {
        LOGGER.log(Level.INFO, () -> LOG_HEADER + "countTokenPerKey " +
                "key=" + key
        );
        try {
            Long tokenCount = 100L;
            return Response.ok(new TokenModel(key, tokenCount)).build();
        } catch (Exception ex) {
            LOGGER.log(Level.WARNING, () -> LOG_HEADER + "countTokenPerKey failed." +
                    "key=" + key +
                    "exception=" + ex.getMessage()
            );
            throw ex;
        }
    }
}

排查背景 #

已查阅Quarkus官方校验指南及MicroProfile《用MicroProfile和Bean Validation校验微服务》文档，但仅找到Bean参数校验相关内容，未明确路径参数校验的配置方式。

问题原因及解决方案 #

核心原因 #

1. 注解类型不匹配：@Min/@Max注解仅对数值类型（如Integer、Long）生效，当前参数为String类型，这两个注解不会触发校验。
2. 校验扩展未启用：项目可能未添加Quarkus校验依赖，导致Bean Validation拦截器未生效。

解决步骤 #

1. 添加Quarkus校验依赖

确保项目中引入quarkus-hibernate-validator扩展，这是Quarkus实现Bean Validation的核心依赖：

• Maven：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-validator</artifactId>
</dependency>

• Gradle：

implementation 'io.quarkus:quarkus-hibernate-validator'

2. 修复参数校验逻辑

有两种方案可选：

方案一：将参数类型改为数值类型

把key的类型从String改为Integer，这样@Min/@Max注解会正常生效：

@GET
@Path("/{key}/action/count")
public Response countTokenPerKey(
        @PathParam("key") @Min(0) @Max(9) Integer key
) {
    LOGGER.log(Level.INFO, () -> LOG_HEADER + "countTokenPerKey " +
            "key=" + key
    );
    try {
        Long tokenCount = 100L;
        // 若TokenModel需要String类型，将key转换为字符串
        return Response.ok(new TokenModel(key.toString(), tokenCount)).build();
    } catch (Exception ex) {
        LOGGER.log(Level.WARNING, () -> LOG_HEADER + "countTokenPerKey failed." +
                "key=" + key +
                "exception=" + ex.getMessage()
        );
        throw ex;
    }
}

方案二：保留String类型，优化校验注解

如果必须保留String类型，使用@Pattern注解限制输入为单个数字，同时可手动校验数值范围：

@GET
@Path("/{key}/action/count")
public Response countTokenPerKey(
        @PathParam("key") @Pattern(regexp = "^\\d$") String key
) {
    // 手动校验数值范围
    int keyNum = Integer.parseInt(key);
    if (keyNum < 0 || keyNum > 9) {
        throw new ConstraintViolationException("key必须在0-9之间", null);
    }
    
    LOGGER.log(Level.INFO, () -> LOG_HEADER + "countTokenPerKey " +
            "key=" + key
    );
    try {
        Long tokenCount = 100L;
        return Response.ok(new TokenModel(key, tokenCount)).build();
    } catch (Exception ex) {
        LOGGER.log(Level.WARNING, () -> LOG_HEADER + "countTokenPerKey failed." +
                "key=" + key +
                "exception=" + ex.getMessage()
        );
        throw ex;
    }
}

3. 检查异常处理器

确认项目中没有自定义的ExceptionMapper错误地将ConstraintViolationException（校验异常）转换为200成功响应，否则会导致校验不生效的假象。

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