Quarkus反应式与非反应式JAX-RS端点PathParam URL解码差异咨询

问题背景 #

将Web应用从DropWizard迁移至Quarkus 3.1（使用resteasy-reactive）后，发现URL路径参数中百分号编码的%2F（斜杠）处理逻辑和阻塞模式、Jersey（DropWizard依赖框架）存在明显差异：

定义的端点代码：

@ApplicationScoped
@Path("/path")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class PathResource
{
    @GET
    @Path("/list/{primaryKey: .+}")
    public String pathAsList(@PathParam("primaryKey") List<PathSegment> path)
    {
        // 业务处理逻辑
    }
}

当访问URL http://localhost:8081/path/list/ab%2Fcd/ef%2Fgh 时：

• 阻塞模式/Jersey：得到2个分段：ab/cd、ef/gh（符合预期，解码后的斜杠不会被当作路径分隔符拆分）
• Reactive模式：得到4个分段：ab、cd、ef、gh（错误地将解码后的斜杠视为路径分隔符，拆分了原本的分段）

原因分析 #

该差异源于两种模式的路径处理顺序不同：

• 阻塞模式/Jersey：先按原始URL中的/拆分路径段，再对每个分段单独解码
• resteasy-reactive：默认先对整个路径做全解码，再根据解码后的/拆分路径段，导致%2F解码后的斜杠被误判为分隔符

可行解决方案 #

方案1：手动处理编码与拆分 #

在@PathParam上添加@Encoded注解获取原始未解码参数，手动完成拆分和解码逻辑：

@GET
@Path("/list/{primaryKey: .+}")
public String pathAsList(@Encoded @PathParam("primaryKey") String rawPath) {
    String[] rawSegments = rawPath.split("/");
    List<PathSegment> segments = new ArrayList<>();
    for (String seg : rawSegments) {
        String decoded = URLDecoder.decode(seg, StandardCharsets.UTF_8);
        segments.add(new PathSegment() {
            @Override
            public String getPath() {
                return decoded;
            }

            @Override
            public Map<String, String> getMatrixParameters() {
                return Collections.emptyMap();
            }
        });
    }
    // 后续业务处理
}

方案2：修改Quarkus配置对齐行为 #

在application.properties中添加配置，禁用resteasy-reactive的路径预解码，使其和阻塞模式处理逻辑一致：

quarkus.resteasy-reactive.path-parsing-decode-slash=false

该配置会让框架先按原始URL的/拆分路径段，再对每个分段单独解码，保留%2F解码后的斜杠在分段内。

关于提交Issue #

该差异属于resteasy-reactive与标准JAX-RS行为不一致的问题，提交到Quarkus仓库时建议包含：

• 完整的端点代码示例
• 两种模式下的测试URL及结果对比
• 阻塞模式/Jersey的预期行为说明

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