Quarkus 中的路径解析

曾经，Quarkus 为健康检查和指标等事物定义了其他端点。它们与应用程序定义的任何端点一起，从 quarkus.http.root-path 提供服务。这并不总是显而易见的，因为 quarkus.http.root-path 默认为 /，使其几乎不可见。

随着这些端点的激增，我们开始担心污染应用程序端点命名空间，并考虑如何将这些非应用程序端点分组在一起，以避免与应用程序端点冲突，并使其更容易处理安全和访问策略。一些用户还询问我们是否可以从另一个端口提供这些非应用程序端点（我们还没有做到）。

第一步是将所有这些由扩展定义的端点分组在一起。这就是非应用程序端点路径的起源。此新路径的默认位置是 /q，它嵌套在 HTTP 根路径下，就像其他端点一样。举例来说，效果是将 /health 移动到 /q/health。

我们知道，移动某些端点（如指标和健康状况）会对已部署的应用程序和人类的肌肉记忆造成问题。为了缓解过渡，我们为其中一些端点添加了重定向，这样如果您访问 /metrics，您将被重定向到 /q/metrics。

非应用程序端点支持已在 1.11.0.Final 中发布。

然后事情开始变得糟糕。例如，一些云托管提供商只接受 200 作为健康的定义，所以重定向（一个 301）没有达到预期的效果。关于如何关闭非应用程序端点以恢复先前行为，以及如何将特定端点移出此非应用程序端点集合，也存在一些困惑。

顺便说一句，我们陷入这种状况的原因还受到库行为差异的影响。例如，Vert.x 在创建路由时总是希望段以斜杠开头，而 JAX-RS 在 @Path 注释中实际上会忽略前导斜杠。习惯了 Vert.x 的开发者总是会添加前导斜杠，而使用 JAX-RS 的开发者则随便做什么，它就会神奇地奏效。

在 Quarkus 中，一个实现细节被意外暴露：扩展定义的非应用程序端点基于 Vert.x 路由。默认路径配置值以斜杠开头，以启用快速路由创建并允许简单的追加行为。在 Quarkus 的早期，没有什么表明这是一个坏主意，并且有 JAX-RS 经验的开发人员也没有任何警告，因为 JAX-RS 会处理它。

然而，现在我们面临的情况是，路径没有按人们预期的那样解析，而解决这种情况所需的配置更改要么不直观，要么会导致其他问题。我们最终将所有可能的配置排列组合放入一个电子表格中，以便我们可以并排查看组合不同配置值时会发生什么。结果并不理想。然而，这项练习使我们能够退一步，着眼于大局，评估需要改变什么才能让应用程序和非应用程序端点的行为符合您的需求。

虽然用于配置 Quarkus 中路径的配置属性集保持不变，但配置值的解释方式不同了。

这些更新已经可用，并且随着 1.11.5.Final 和 1.12.1.Final 的发布，混乱应该已经平息。

请注意，非应用程序端点的便捷重定向仍然存在，但可以通过将 quarkus.http.redirect-to-non-application-root-path 设置为 false 来禁用它们。这一点完全没有改变。

让我们通过一些示例来了解在我们的新规则下路径是如何解析的。我们将从以下假设开始

我们最关心的配置属性是

我们还将重点介绍一些值得关注的可配置非应用程序端点

让我们看看当我们开始调整参数时会发生什么。在下面的示例中，请注意配置中的标点符号，这将是它们行为方式的关键。

在大多数情况下，我们希望这会是透明的。在此过程中，我们发现了一些非常不一致的路径处理，这使我们相信许多（甚至大多数）这些值从未被自定义过。

如果您自定义了 HTTP 根路径，您最有可能看到行为上的变化。在这种情况下，我们希望新的规则和上面的示例能帮助您了解如何调整您的配置以使一切按照您想要的方式运行。

扩展作者将看到最大的变化。已更新编写扩展指南，以描述用于创建非应用程序端点的构建项的变化。但是，总的规则是避免自行构造端点路径，并依赖 NonApplicationRootPathBuildItem 和 HttpRootPathBuildItem 来为您构建它们。

虽然我们知道不可能让每个人都满意，但我们希望我们至少已经实现了更可预测和一致结果的配置模式。我们再次为在整理过程中您可能观察到的任何行为变更表示歉意。