Quarkus从1.x升级到3.6后API路径匹配失败求助

核心现象 #

Quarkus从1.x升级到3.6（完成javax到jakarta迁移）后，带有/v1/maps/前缀的API返回404，请求无法到达控制器，但将前缀改为/v2/maps/后路径匹配恢复正常。

排查方向与解决办法 #

• 清理构建缓存
  升级后构建缓存可能残留旧路由配置，导致新路由未正确生成。执行以下操作清理后重新构建：

  # Maven项目
  mvn clean install
  # Gradle项目
  gradle clean build
  # 开发模式重启时强制清理缓存
  quarkus dev --clean
  

  这是最快速的排查手段，多数奇怪的路由匹配问题都能通过此方式解决。

• 检查路由冲突
  Quarkus 3.x默认使用Resteasy Reactive作为REST实现，路由匹配优先级与旧版Resteasy Classic有差异。排查项目中所有带有/v1/前缀的路由定义：

  • 其他标注@Path的资源类
  • Vertx原生路由配置
  • 全局过滤器、拦截器的路径匹配规则
    确认是否有其他路由抢占了/v1/maps/的匹配权。

• 修改路径参数命名格式
  路径中使用的{map-id}这类带连字符的参数，虽然符合JAX-RS规范，但Resteasy Reactive在新版本中对其解析逻辑可能有变化。尝试改为下划线格式：

  @POST
  @Path("/v1/maps/{map_id}/omap-stats")
  public Response addStats(@PathParam("map_id") Long mapId) { 
      // ...
  }
  

  同步修改所有带连字符的路径参数（如{edge-id}改为{edge_id}）后重新测试。

• 验证版本特定Bug
  Quarkus 3.6.x可能存在路由匹配的版本专属Bug，建议尝试升级到3.7+或回退到3.5.x版本，确认问题是否消失。如果是版本Bug，可关注Quarkus官方Issue跟踪后续修复进展。

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