HTTP Reference

本文阐明了 Quarkus 中可用的不同 HTTP 功能。

This document clarifies different HTTP functionalities available in Quarkus.

Eclipse Vert.x 提供了基本 HTTP 层。对于 Servlet 支持，Quarkus 采用基于 Vert.x 运行的定制化 Undertow 版本，而 Jakarta REST 支持则通过 RESTEasy 传递。

Eclipse Vert.x supplies the fundamental HTTP layer. For Servlet support, Quarkus employs a customized Undertow version that operates on top of Vert.x, while Jakarta REST support is delivered through RESTEasy.

在存在 Undertow 时，RESTEasy 作为 Servlet 过滤器运行。在不存在时，RESTEasy 直接在 Vert.x 上运行，不涉及 Servlet。

When Undertow is present, RESTEasy functions as a Servlet filter. In its absence, RESTEasy operates directly on Vert.x without involving Servlets.

Serving static resources

如果您正在针对 Web 应用程序使用 Quarkus，请查看 Quarkus for the Web 指南。

If you are looking to use Quarkus for a web application, look at the Quarkus for the Web guide.

From the application jar

若要从应用程序 jar 提供静态资源，您必须将它们放在应用程序的 META-INF/resources 目录中。选择此位置是因为它是 jar 文件中资源的标准位置（如 Servlet 规范中定义的）。尽管 Quarkus 可以独立于 Servlet 使用，但遵循此惯例可以让将资源放在此位置的现有代码正常运行。

To serve static resources from the application jar, you must place them in the META-INF/resources directory of your application. This location was chosen as it is the standard location for resources in jar files as defined by the Servlet spec. Even though Quarkus can be used without Servlet, following this convention allows existing code that places its resources in this location to function correctly.

From web dependencies like webjars or mvnpm

请参阅 Web dependency locator 指南，了解有关如何使用 WebJars、 mvnpm 和 importmaps 的详细信息

Look at the Web dependency locator guide for details on how to use WebJars, mvnpm and importmaps

From a local directory

可以通过在 Vert.x 路由器中安装附加路由，从本地目录提供静态资源。

Static resources can be served from a local directory by installing an additional route in the Vert.x router.

例如，要从相对于 [role="bare"][role="bare"]http://localhost:8080/static/ 的当前路径提供 static/ 目录中的资源，您可以安装以下路由：

For instance, to serve resources from the static/ directory relative to the current path at [role="bare"]http://localhost:8080/static/, you can install the following route:

package org.acme;

import io.quarkus.runtime.StartupEvent;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.StaticHandler;
import jakarta.enterprise.event.Observes;


public class StaticResources {

    void installRoute(@Observes StartupEvent startupEvent, Router router) {
        router.route()
                .path("/static/*")
                .handler(StaticHandler.create("static/"));
    }
}

HTTP Compression

默认情况下，静态资源的响应正文不会被压缩。您可以通过 quarkus.http.enable-compression=true 启用 HTTP 压缩支持。如果启用了压缩支持，则当资源的文件名派生的 Content-Type 标头为通过 quarkus.http.compress-media-types 配置的压缩媒体类型时，响应正文会压缩。

The response body of a static resource is not compressed by default. You can enable the HTTP compression support by means of quarkus.http.enable-compression=true. If compression support is enabled then the response body is compressed if the Content-Type header derived from the file name of a resource is a compressed media type as configured via quarkus.http.compress-media-types.

以下媒体类型列表默认压缩：text/html、text/plain、text/xml、text/css、text/javascript、application/javascript、application/graphql+json。这意味着其他一些值得注意的媒体类型（如 application/json、application/xhtml+xml）默认情况下未压缩。

By default, the following list of media types is compressed: text/html, text/plain, text/xml, text/css, text/javascript, application/javascript, application/graphql+json. It means some other noteworthy media types such as application/json, application/xhtml+xml are NOT compressed by default.

如果客户端在请求标头（例如 Accept-Encoding: deflate, gzip, br）中未表明其支持 HTTP 压缩，那么响应正文不会压缩。

If the client does not indicate its support for HTTP compression in a request header, e.g. Accept-Encoding: deflate, gzip, br, then the response body is not compressed.

默认情况下不提供 Brotli 压缩。您可以通过设置 quarkus.http.compressors=deflate,gzip,br 启用它。在构建原生映像的情况下，它会将大约 1MB 添加到可执行文件大小中。

Brotli compression is not available by default. You can enable it by setting quarkus.http.compressors=deflate,gzip,br. In case of building native image, it adds around 1MB to your executable size.

Other Configurations

此外，可以修改静态资源的索引页面（默认值为 index.html），将隐藏文件（例如点文件）标记为不提供，禁用范围请求，并配置缓存支持（例如缓存标头和文件属性缓存）。

Additionally, the index page for static resources can be changed from default index.html, the hidden files (e.g. dot files) can be indicated as not served, the range requests can be disabled, and the caching support (e.g. caching headers and file properties cache) can be configured.

Unresolved directive in http-reference.adoc - include::{generated-dir}/config/quarkus-vertx-http_quarkus.http.static-resources.adoc[]

Configuring the Context path

默认情况下，Quarkus 将通过根上下文提供内容。如果您想更改此内容，可以使用 quarkus.http.root-path 配置密钥设置上下文路径。

By default, Quarkus will serve content from under the root context. If you want to change this you can use the quarkus.http.root-path config key to set the context path.

如果您正在使用 Servlet，则可以通过 quarkus.servlet.context-path 控制 Servlet 上下文路径。此项相对于上述 http 根，并且只会影响 Servlet 和在 Servlet 上运行的内容。大多数应用程序都会希望使用 HTTP 根，因为这会影响 Quarkus 提供的所有内容。

If you are using Servlet you can control the Servlet context path via quarkus.servlet.context-path. This item is relative to the http root above, and will only affect Servlet and things that run on top of Servlet. Most applications will want to use the HTTP root as this affects everything that Quarkus serves.

如果同时指定，则所有非 Servlet Web 端点将与 quarkus.http.root-path 相关联，而 Servlet 将与 {quarkus.http.root-path}/{quarkus.servlet.context-path} 相关联。

If both are specified then all non-Servlet web endpoints will be relative to quarkus.http.root-path, while Servlet’s will be served relative to {quarkus.http.root-path}/{quarkus.servlet.context-path}.

如果使用 REST Assured 进行测试并且设置了 quarkus.http.root-path，那么 Quarkus 将自动配置基本 URL 以用于 Quarkus 测试，所以测试 URL 不应该包括根目录。

If REST Assured is used for testing and quarkus.http.root-path is set then Quarkus will automatically configure the base URL for use in Quarkus tests, so test URL’s should not include the root path.

通常情况下，Web 内容的路径配置相对于 quarkus.http.root-path（默认情况下为 /）进行解释。

In general, path configurations for web content are interpreted relative to quarkus.http.root-path (which is / by default).

To specify paths within this context root, use a relative path that does not begin with a forward slash.
If you want to specify the URI explicitly, so it is always the same regardless of the value of quarkus.http.root-path, use an absolute path that begins with a forward slash.

例如，如果一个扩展配置了 service 路径，则该端点将从 ${quarkus.http.root-path}/service 提供服务。如果你将该路径的配置更改为 /service，则该端点将从 /service 提供服务。

As an example, if an extension configures a service path, that endpoint will be served from ${quarkus.http.root-path}/service. If you change the configuration of that path to /service, that endpoint will be served from /service.

Path Resolution in Quarkus 博客文章进一步解释了路径解析如何针对用户和扩展定义的路径运行。

The Path Resolution in Quarkus blog post further explains how path resolution works for both user and extension defined paths.

Example 1. Management Interface

quarkus.http.root-path 仅用于主 HTTP 服务器。如果你启用了管理界面（使用 quarkus.management.enabled=true 属性），你可以使用 quarkus.management.root-path 配置管理界面的根路径。

quarkus.http.root-path is only used for the main HTTP server. If you enabled the management interface (using the quarkus.management.enabled=true property), you can configure the root path of the management interface using: quarkus.management.root-path.

请参阅 management interface reference 了解更多信息。

Refer to the management interface reference for more information.

Supporting secure connections with TLS/SSL

为了让 Quarkus 支持安全连接，你必须提供证书和关联密钥文件，或提供密钥库。

To have Quarkus support secure connections, you must either provide a certificate and associated key file, or supply a keystore.

在这两种情况下，都必须提供密码。请参阅指定段落，了解如何提供密码的详细描述。

In both cases, a password must be provided. See the designated paragraph for a detailed description of how to provide it.

若要支持原生可执行文件中的 TLS/SSL，请参阅我们的 Using SSL With Native Executables guide。

To enable TLS/SSL support with native executables, please refer to our Using SSL With Native Executables guide.

Using the TLS centralized configuration

Quarkus 提供一个 TLS centralized configuration，可用于配置服务器的 TLS 上下文。这是配置 HTTPS 的建议方法。

Quarkus provides a TLS centralized configuration that can be used to configure the server’s TLS context. It is the recommended approach to configure HTTPS.

若要配置 HTTP 服务器以使用 HTTPS，可以使用以下配置：

To configure the HTTP server to use HTTPS, you can use the following configuration:

quarkus.tls.key-store.pem.0.cert=server.crt
quarkus.tls.key-store.pem.0.key=server.key
quarkus.http.insecure-requests=disabled # Reject HTTP requests

因此，你使用 p12（PKCS12）密钥库，请使用以下配置：

So you a p12 (PKCS12) key store, use the following configuration:

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled # Reject HTTP requests

你可以使用命名配置，而不是默认配置：

Instead of the default configuration, you can use a named configuration:

quarkus.tls.https.key-store.p12.path=server-keystore.p12
quarkus.tls.https.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=https

Configuring the HTTP server directly

如果你不想使用 TLS 注册表，可以直接配置 HTTP 服务器。

If you do not want to use the TLS registry, you can configure the HTTP server directly.

如果尚未将证书加载到密钥库中，可以使用下面列出的属性直接提供证书。Quarkus 首先会尝试将给定文件加载为资源，并使用文件系统作为后备。证书/密钥对将在启动时加载到新创建的密钥库中。

If the certificate has not been loaded into a keystore, it can be provided directly using the properties listed below. Quarkus will first try to load the given files as resources, and uses the filesystem as a fallback. The certificate / key pair will be loaded into a newly created keystore on startup.

你的 application.properties 的外观如下所示：

Your application.properties would then look like this:

quarkus.http.ssl.certificate.files=/path/to/certificate
quarkus.http.ssl.certificate.key-files=/path/to/key

另一种解决方法是直接提供一个密钥库，其中已经包含具有证书的默认条目。你至少需要提供文件和密码。

An alternate solution is to directly provide a keystore which already contains a default entry with a certificate. You will need to at least provide the file and a password.

与证书/密钥文件组合一样，Quarkus 首先将尝试将给定路径解析为资源，然后尝试从文件系统读取该资源。

As with the certificate/key file combination, Quarkus will first try to resolve the given path as a resource, before attempting to read it from the filesystem.

将以下属性添加到你的 application.properties：

Add the following property to your application.properties:

quarkus.http.ssl.certificate.key-store-file=/path/to/keystore

作为可选提示，可以将密钥库的类型提供为所列选项之一。如果未提供类型，Quarkus 将尝试从文件扩展名推断类型。

As an optional hint, the type of keystore can be provided as one of the options listed. If the type is not provided, Quarkus will try to deduce it from the file extensions.

quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]

在上述两种情况下，都需要提供密码来创建/加载密钥库。可以使用以下属性在 application.properties 中设置密码（纯文本）：

In both aforementioned scenarios, a password needs to be provided to create/load the keystore with. The password can be set in your application.properties (in plain-text) using the following property:

quarkus.http.ssl.certificate.key-store-password=your-password

但是，不要在配置文件中将密码作为纯文本提供（这被认为是不良做法），而是可以使用 MicroProfile Config 作为环境变量 QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD 提供密码。这也可以与 Kubernetes secrets 协同工作。

However, instead of providing the password as plain-text in the configuration file (which is considered bad practice), it can instead be supplied (using MicroProfile Config) as the environment variable QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD. This will also work in tandem with Kubernetes secrets.

Note: To remain compatible with earlier versions of Quarkus (before 0.16) the default password is set to "password". It is therefore not a mandatory parameter!

Configure the HTTPS port

默认情况下，Quarkus 监听端口 8443 以用于 SSL 保护的连接，并监听端口 8444 以运行测试。

By default, Quarkus listens to port 8443 for SSL secured connections and 8444 when running tests.

可以在 application.properties 中使用属性 quarkus.http.ssl-port 和 quarkus.http.test-ssl-port 配置这些端口。

These ports can be configured in your application.properties with the properties quarkus.http.ssl-port and quarkus.http.test-ssl-port.

Disable the HTTP port

可以禁用 HTTP 端口并仅支持安全请求。这是通过 application.properties 中的 quarkus.http.insecure-requests 属性完成的。有三种可能值：

It is possible to disable the HTTP port and only support secure requests. This is done via the quarkus.http.insecure-requests property in application.properties. There are three possible values:

enabled: The default, HTTP works as normal
redirect: HTTP requests will be redirected to the HTTPS port
disabled: The HTTP port will not be opened.

如果你使用 redirect 或 disabled 并且未添加 SSL 证书或密钥库，则你的服务器将无法启动！

if you use redirect or disabled and have not added an SSL certificate or keystore, your server will not start!

Reloading the certificates

密钥库、信任库和证书文件可以定期重新加载。配置 quarkus.http.ssl.certificate.reload-period 属性以指定应重新加载证书的时间间隔：

Key store, trust store and certificate files can be reloaded periodically. Configure the quarkus.http.ssl.certificate.reload-period property to specify the interval at which the certificates should be reloaded:

quarkus.http.ssl.certificate.files=/mount/certs/tls.crt
quarkus.http.ssl.certificate.key-files=/mount/certs/tls.key
quarkus.http.ssl.certificate.reload-period=1h

文件从最初加载时相同的文件夹重新加载。如果没有内容更改，则重新加载将是无操作。如果重新加载失败，则服务器将继续使用以前的证书。

The files are reloaded from the same location as they were initially loaded from. If there is no content change, the reloading is a no-op. It the reloading fails, the server will continue to use the previous certificates.

Additional HTTP Headers

要启用在每个响应上发送 HTTP 标头，请添加以下属性：

To enable HTTP headers to be sent on every response, add the following properties:

quarkus.http.header."X-Content-Type-Options".value=nosniff

这将在对应用程序中任何资源执行的请求的响应上包含 X-Content-Type-Options: nosniff HTTP 标头。

This will include the X-Content-Type-Options: nosniff HTTP Header on responses for requests performed on any resource in the application.

你还可以指定 path 模式和需要应用 HTTP methods 标头的资源：

You can also specify a path pattern and the HTTP methods the header needs to be applied:

quarkus.http.header.Pragma.value=no-cache
quarkus.http.header.Pragma.path=/headers/pragma
quarkus.http.header.Pragma.methods=GET,HEAD

这将仅在使用 GET 或 HEAD 方法调用 /headers/pragma 资源时应用 Pragma 标头

This will apply the Pragma header only when the /headers/pragma resource is called with a GET or a HEAD method

Unresolved directive in http-reference.adoc - include::{generated-dir}/config/quarkus-vertx-http_quarkus.http.header.adoc[]

Additional HTTP Headers per path

如果您根据路径需要不同的标头值，您可以使用以下配置：

If you need different header values depending on the path, you can use the following configuration:

quarkus.http.filter.index.header."Cache-Control"=none
quarkus.http.filter.index.matches=/index.html

当调用 /index.html 时，它会将 Cache-Control 标头设置为 none。

This will set the Cache-Control header to none when /index.html is called.

键中 quarkus.http.filter 后面的 index 用于分组并且（作为一个示例）可以根据您的喜好命名。

The index after quarkus.http.filter in the key is used for grouping and (as an example) can be named as you like.

您可以在路径中使用正则表达式，还可以指定设置 HTTP 标头的 HTTP 方法：

You can use a regular expression in the path and also specify the HTTP methods where the HTTP header will be set:

quarkus.http.filter.static.header."Cache-Control"=max-age=31536000
quarkus.http.filter.static.methods=GET,HEAD
quarkus.http.filter.static.matches=/static/.*

如果配置中重叠的路径，您可以指定一个顺序（较高的值优先）。例如，具有以下配置：

In case of overlapping paths in the configuration, you can specify an order (higher values take precedence). For example, having the following configuration:

quarkus.http.filter.just-order.order=10
quarkus.http.filter.just-order.header."Cache-Control"=max-age=5000
quarkus.http.filter.just-order.matches=/paths/order

quarkus.http.filter.any-order.order=11
quarkus.http.filter.any-order.header."Cache-Control"=max-age=1
quarkus.http.filter.any-order.matches=/paths/order.*

当请求 /paths/order 时，将包含 Cache-Control: max-age=1 标头。

Will include the Cache-Control: max-age=1 header when /paths/order is requested.

Unresolved directive in http-reference.adoc - include::{generated-dir}/config/quarkus-vertx-http_quarkus.http.filter.adoc[]

Support 100-Continue in vert.x

要支持 100-continue，quarkus.http.handle-100-continue-automatically 选项需要显式启用。有关其他信息，请查看 100-continue 和相关的 Vert.x documentation。

To support 100-continue, the quarkus.http.handle-100-continue-automatically option needs to be enabled explicitly For additional information check 100-continue and the related Vert.x documentation.

quarkus.http.handle-100-continue-automatically=true

HTTP/2 Support

HTTP/2 默认已启用，如果使用 SSL，浏览器将使用它。即使在没有使用 SSL 的情况下，也支持通过明文升级的 HTTP/2，非浏览器客户端也可能使用它。

HTTP/2 is enabled by default, and will be used by browsers if SSL is in use. Even if SSL is not in use HTTP/2 via cleartext upgrade is supported, and may be used by non-browser clients.

如果您想禁用 HTTP/2，则可以设置：

If you want to disable HTTP/2 you can set:

quarkus.http.http2=false

请注意，某些配置属性特定于 HTTP/2。例如，为了配置最大标头列表大小（~ 标头），您需要配置 quarkus.http.limits.max-header-list-size 属性。您还可以使用 quarkus.http.http2-push-enabled 启用或禁用 HTTP/2 推送。

Note that some configuration attributes are specific to HTTP/2. For example, to configure the max header list size (~ header), you need to configure the quarkus.http.limits.max-header-list-size attribute. You can also enable or disable HTTP/2 push using quarkus.http.http2-push-enabled.

Listening on a Random Port

如果您不想指定端口，则可以设置 quarkus.http.port=0 或 quarkus.http.test-port=0。系统会选择一个随机打开的端口，并在控制台中打印一条日志消息。绑定端口时， quarkus.http.port 系统属性将被设置为实际选择的端口，因此您可以使用它从应用程序内部获取实际端口号。如果您正在进行测试，则可以正常注入 URL，对此进行实际端口配置，并且 REST Assured 也将被适当地配置。

If you don’t want to specify a port you can set quarkus.http.port=0 or quarkus.http.test-port=0. A random open port will be picked by the OS, and a log message printed in the console. When the port is bound the quarkus.http.port system property will be set to the actual port that was selected, so you can use this to get the actual port number from inside the application. If you are in a test you can inject the URL normally and this will be configured with the actual port, and REST Assured will also be configured appropriately.

由于这会设置系统属性，因此您可以通过 MicroProfile Config 访问 quarkus.http.port，但是如果您使用注入，注入的值可能并不总是正确的。此端口分配是 Quarkus 启动中最后要发生的事情之一，因此如果您被注入的对象在端口打开前就被急切创建，那么注入的值将不正确。

As this sets a system property you can access quarkus.http.port via MicroProfile Config, however if you use injection the injected value may not always be correct. This port allocation is one of the last things to happen in Quarkus startup, so if your object that is being injected is created eagerly before the port has opened the injected value will not be correct.

CORS filter

为了使您的 Quarkus 应用程序可供在不同域上运行的另一个应用程序访问，您需要配置跨源资源共享 (CORS)。有关 Quarkus 提供的 CORS 过滤器的详细信息，请参阅“跨源资源共享”指南的 Quarkus CORS filter 小节。

To make your Quarkus application accessible to another application running on a different domain, you need to configure cross-origin resource sharing (CORS). For more information about the CORS filter that Quarkus provides, see the Quarkus CORS filter section of the "Cross-origin resource sharing" guide.

HTTP Limits Configuration

Unresolved directive in http-reference.adoc - include::{generated-dir}/config/quarkus-vertx-http_quarkus.http.limits.adoc[]

Configure traffic shaping

流量整形允许您限制所有信道（即连接）中的带宽，而不管打开信道的数量。当您想控制整体网络流量以防止拥塞或优先处理某些类型的流量时，这将非常有用。

Traffic shaping allows you to limit the bandwidth across all channels (i.e. connections), regardless of the number of open channels. This can be useful when you want to control the overall network traffic to prevent congestion or prioritize certain types of traffic.

要启用流量整形，请在应用程序配置中添加以下属性：

To enable traffic shaping, add the following property in your application configuration:

quarkus.http.traffic-shaping.enabled=true # Required to enable traffic shaping

流量整形允许您配置各种参数，例如写和读限制（以每秒字节为单位）、检查间隔（两个带宽计算之间的延迟）和最长等待时间：

The traffic shaping allows you to configure various parameters, such as write and read limitations (in bytes per second), check interval (the delay between two computations of the bandwidth), and maximum time to wait:

quarkus.http.traffic-shaping.enabled=true # Required to enable traffic shaping
quarkus.http.traffic-shaping.check-interval=30s
quarkus.http.traffic-shaping.outbound-global-bandwidth=1M
quarkus.http.traffic-shaping.inbound-global-bandwidth=1M
quarkus.http.traffic-shaping.max-delay=10s

检查间隔表示计算流量的时间段，较高的间隔可能导致不那么精确的流量整形。尽管接受 0（没有计算），但建议为检查间隔设置一个正值，即使它是高的，因为流量整形精度取决于计算流量的时间段。在这种情况下，建议的值接近 5 或 10 分钟。

The check interval represents the period at which the traffic is computed, and a higher interval may result in less precise traffic shaping. Despite 0 being accepted (no accounting), it is recommended to set a positive value for the check interval, even if it is high since the precision of the traffic shaping depends on the period where the traffic is computed. In this case, a suggested value is something close to 5 or 10 minutes.

outbound-global-bandwidth 和 inbound-global-bandwidth 参数分别表示写入和读取操作中每秒的最大字节数。您还应考虑在读取或写入操作中使对象大小相对地适应您需要的带宽。例如，为 10KB/s 处理 10 MB 大小的对象会导致突发，而为 1 MB/s 处理 100 KB 大小的对象则应由流量整形平稳进行处理。

The outbound-global-bandwidth and inbound-global-bandwidth parameters represent the maximum number of bytes per second for write and read operations, respectively. You shall also consider to have object size in read or write operations relatively adapted to the bandwidth you required. For instance having 10 MB objects for 10KB/s will lead to burst effect, while having 100 KB objects for 1 MB/s should be smoothly handle by the traffic shaping.

此外，您可以设置允许的最大等待时间（max-delay），它为时间整形设置一个上限。默认情况下设置为 15 秒。它必须小于 HTTP 超时时间。当某个阈值达到时，在此时间段内不进行任何写入操作。

Additionally, you can set the maximum time to wait (max-delay), which specifies an upper bound for time shaping. By default, it is set to 15 seconds. It must be less than the HTTP timeout. When one of the threshold is reached, no write happens for that period of time.

Configuring HTTP Access Logs

您可以在 application.properties 中进行配置，以添加 HTTP 请求记录。记录有两个选项，可以在标准 JBoss 记录输出中记录，也可以记录到一个专用文件中。

You can add HTTP request logging by configuring it in application.properties. There are two options for logging, either logging to the standard JBoss logging output, or logging to a dedicated file.

Unresolved directive in http-reference.adoc - include::{generated-dir}/config/quarkus-vertx-http_quarkus.http.access-log.adoc[]

Attribute Short Form Long Form

Attribute	Short Form	Long Form
Remote IP address	`%a`	`%{REMOTE_IP}`
Local IP address	`%A`	`%{LOCAL_IP}`
Bytes sent, excluding HTTP headers, or '-' if no bytes were sent	`%b`
Bytes sent, excluding HTTP headers	`%B`	`%{BYTES_SENT}`
Remote host name	`%h`	`%{REMOTE_HOST}`
Request protocol	`%H`	`%{PROTOCOL}`
Request method	`%m`	`%{METHOD}`
Local port	`%p`	`%{LOCAL_PORT}`
Query string (prepended with a '?' if it exists, otherwise an empty string)	`%q`	`%{QUERY_STRING}`
First line of the request	`%r`	`%{REQUEST_LINE}`
HTTP status code of the response	`%s`	`%{RESPONSE_CODE}`
Date and time, in Common Log Format format	`%t`	`%{DATE_TIME}`
Date and time as defined by a DateTimeFormatter compliant string		`%{time,date_fime_formatter_string}`
Remote user that was authenticated	`%u`	`%{REMOTE_USER}`
Requested URL path	`%U`	`%{REQUEST_URL}`
Request relative path	`%R`	`%{REQUEST_PATH}`
Local server name	`%v`	`%{LOCAL_SERVER_NAME}`
Time taken to process the request, in millis	`%D`	`%{RESPONSE_TIME}`
Time taken to process the request, in seconds	`%T`
Time taken to process the request, in micros		`%{RESPONSE_TIME_MICROS}`
Time taken to process the request, in nanos		`%{RESPONSE_TIME_NANOS}`
Current request thread name	`%I`	`%{THREAD_NAME}`
SSL cypher		`%{SSL_CIPHER}`
SSL client certificate		`%{SSL_CLIENT_CERT}`
SSL session id		`%{SSL_SESSION_ID}`
All request headers		`%{ALL_REQUEST_HEADERS}`
Cookie value		`%{c,cookie_name}`
Query parameter		`%{q,query_param_name}`
Request header		`%{i,request_header_name}`
Response header		`%{o,response_header_name}`
Vert.x Routing Context Internal Data		`%{d,map_key}`
Vert.x MDC data (e.g. 'traceId' for OpenTelemetry)		`%{X,mdc-key}`

Remote IP address

%a

%{REMOTE_IP}

Local IP address

%A

%{LOCAL_IP}

Bytes sent, excluding HTTP headers, or '-' if no bytes were sent

%b

Bytes sent, excluding HTTP headers

%B

%{BYTES_SENT}

Remote host name

%h

%{REMOTE_HOST}

Request protocol

%H

%{PROTOCOL}

Request method

%m

%{METHOD}

Local port

%p

%{LOCAL_PORT}

Query string (prepended with a '?' if it exists, otherwise an empty string)

%q

%{QUERY_STRING}

First line of the request

%r

%{REQUEST_LINE}

HTTP status code of the response

%s

%{RESPONSE_CODE}

Date and time, in Common Log Format format

%t

%{DATE_TIME}

Date and time as defined by a DateTimeFormatter compliant string

%{time,date_fime_formatter_string}

Remote user that was authenticated

%u

%{REMOTE_USER}

Requested URL path

%U

%{REQUEST_URL}

Request relative path

%R

%{REQUEST_PATH}

Local server name

%v

%{LOCAL_SERVER_NAME}

Time taken to process the request, in millis

%D

%{RESPONSE_TIME}

Time taken to process the request, in seconds

%T

Time taken to process the request, in micros

%{RESPONSE_TIME_MICROS}

Time taken to process the request, in nanos

%{RESPONSE_TIME_NANOS}

Current request thread name

%I

%{THREAD_NAME}

SSL cypher

%{SSL_CIPHER}

SSL client certificate

%{SSL_CLIENT_CERT}

SSL session id

%{SSL_SESSION_ID}

All request headers

%{ALL_REQUEST_HEADERS}

Cookie value

%{c,cookie_name}

Query parameter

%{q,query_param_name}

Request header

%{i,request_header_name}

Response header

%{o,response_header_name}

Vert.x Routing Context Internal Data

%{d,map_key}

Vert.x MDC data (e.g. 'traceId' for OpenTelemetry)

%{X,mdc-key}

将 quarkus.http.access-log.consolidate-rerouted-requests=true 设置为启用对修饰符 < 的支持。对于已在内部重定向以咨询原始请求的请求，可以使用此修饰符。下列属性支持该修饰符：

Set quarkus.http.access-log.consolidate-rerouted-requests=true to enable support for the modifier <. This modifier can be used for requests that have been internally redirected to consult the original request. The following attributes support this modifier:

Attribute Short Form Long Form

Attribute	Short Form	Long Form
First line of the request	`%<r`	`%{<REQUEST_LINE}`
Request method	`%<m`	`%{<METHOD}`
Request relative path	`%<R`	`%{<REQUEST_PATH}`
Requested URL path	`%<U`	`%{<REQUEST_URL}`
Query string (prepended with a '?' if it exists, otherwise an empty string)	`%<q`	`%{<QUERY_STRING}`
Query parameter		`%{<q,query_param_name}`

First line of the request

%<r

%{<REQUEST_LINE}

Request method

%<m

%{<METHOD}

Request relative path

%<R

%{<REQUEST_PATH}

Requested URL path

%<U

%{<REQUEST_URL}

Query string (prepended with a '?' if it exists, otherwise an empty string)

%<q

%{<QUERY_STRING}

Query parameter

%{<q,query_param_name}

使用任何与记录请求处理时间相关的属性时，将 quarkus.http.record-request-start-time=true 设置为启用记录请求开始时间。

Set quarkus.http.record-request-start-time=true to enable recording request start times when using any of the attributes related to logging request processing times.

假设已为该应用程序设置了安全性（请参阅我们的 guide 了解更多详情），则记录属性 Remote user that was authenticated 被设置为 io.quarkus.security.identity.SecurityIdentity 主体的值。如果您的应用程序使用自定义 Jakarta REST SecurityContext，则使用上下文主体。请参阅 Logging guide 了解如何自行添加上下文日志信息。

Assuming security has been set up for the application (see our guide for more details), logging attribute Remote user that was authenticated is set to the value of the io.quarkus.security.identity.SecurityIdentity principal. If your application use custom Jakarta REST SecurityContext, the context principal is used instead. Please refer to the Logging guide for options how to add contextual log information yourself.

使用 quarkus.http.access-log.exclude-pattern=/some/path/.* 从日志中排除有关路径 /some/path/… (including subsequent paths) 的所有条目。

Use quarkus.http.access-log.exclude-pattern=/some/path/.* to exclude all entries concerning the path /some/path/… (including subsequent paths) from the log.

Arbitrary customizations

Quarkus 允许用户通过使用 io.quarkus.vertx.http.HttpServerOptionsCustomizer 任意自定义 Quarkus 启动的 HTTP 服务器的选项。例如，如果需要以编程方式设置 HTTP 端口，则可以使用以下代码：

Quarkus allows users to arbitrarily customize the options of HTTP servers started by Quarkus via the use of io.quarkus.vertx.http.HttpServerOptionsCustomizer. For example, if the HTTP port needs to be set programmatically, then the following code could be used:

import jakarta.inject.Singleton;
import io.quarkus.vertx.http.HttpServerOptionsCustomizer;

@Singleton 1
public class MyCustomizer implements HttpServerOptionsCustomizer {

    @Override
    public void customizeHttpServer(HttpServerOptions options) { 2
        options.setPort(9998);
    }
}

1	By making the class a managed bean, Quarkus will take the customizer into account when it starts the Vert.x servers
2	In this case, we only care about customizing the HTTP server, so we just override the `customizeHttpServer` method, but users should be aware that `HttpServerOptionsCustomizer` allows configuring the HTTPS and Domain Socket servers as well

How to execute logic when HTTP server started

为了在启动 HTTP 服务器时执行某些自定义操作，您需要声明一个 asynchronous CDI 观察者方法。Quarkus asynchronously 在相应的 HTTP 服务器开始侦听已配置的主机和端口上时触发 io.quarkus.vertx.http.HttpServerStart、io.quarkus.vertx.http.HttpsServerStart 和 io.quarkus.vertx.http.DomainSocketServerStart 类型事件。

In order to execute some custom action when the HTTP server is started you’ll need to declare an asynchronous CDI observer method. Quarkus asynchronously fires CDI events of types io.quarkus.vertx.http.HttpServerStart, io.quarkus.vertx.http.HttpsServerStart and io.quarkus.vertx.http.DomainSocketServerStart when the corresponding HTTP server starts listening on the configured host and port.

HttpServerStart example

@ApplicationScoped
public class MyListener {

   void httpStarted(@ObservesAsync HttpServerStart start) { 1
      // ...notified when the HTTP server starts listening
   }
}

1	An asynchronous `HttpServerStart` observer method may be declared by annotating an `HttpServerStart` parameter with `@jakarta.enterprise.event.ObservesAsync`.

对于此特定用例来说，不能使用 StartupEvent，因为在启动 HTTP 服务器之前会触发此 CDI 事件。

It’s not possible to use the StartupEvent for this particular use case because this CDI event is fired before the HTTP server is started.

Running behind a reverse proxy

Quarkus 可以通过代理访问，代理会另外生成标头（例如 X-Forwarded-Host），以防止来自代理服务器客户端所面对端的信息在它们被涉及时遭到更改或丢失。在此类场景中，Quarkus 可以被配置为自动更新协议、主机、端口和 URI，反映这些标头中的值。

Quarkus could be accessed through proxies that additionally generate headers (e.g. X-Forwarded-Host) to keep information from the client-facing side of the proxy servers that is altered or lost when they are involved. In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI reflecting the values in these headers.

激活此功能后，服务器将面临多个安全问题（即，信息欺骗）。请考虑仅在反向代理后面运行的情况下激活此功能。

Activating this feature leaves the server exposed to several security issues (i.e. information spoofing). Consider activate it only when running behind a reverse proxy.

要设置此功能，请在 src/main/resources/application.properties 中包含以下行：

To set up this feature, please include the following lines in src/main/resources/application.properties:

quarkus.http.proxy.proxy-address-forwarding=true

仅要考虑事实上的标准标头（Forwarded 标头），请在 src/main/resources/application.properties 中包含以下行：

To consider only de-facto standard header (Forwarded header), please include the following lines in src/main/resources/application.properties:

quarkus.http.proxy.allow-forwarded=true

仅要考虑非标准标头，请改在 src/main/resources/application.properties 中包含以下行：

To consider only non-standard headers, please include the following lines instead in src/main/resources/application.properties:

quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-x-forwarded=true
quarkus.http.proxy.enable-forwarded-host=true
quarkus.http.proxy.enable-forwarded-prefix=true
quarkus.http.proxy.trusted-proxies=127.0.0.1 1

1	Configure trusted proxy with the IP address `127.0.0.1`. Request headers from any other address are going to be ignored.

与标准标头和非标准标头相关的配置都可以组合，尽管标准标头配置将具有优先权。然而，组合它们会产生安全影响，因为客户端可以伪造转发标头请求，而代理不会覆盖此类标头。因此，代理应该从客户端剥离意外的 X-Forwarded 或 X-Forwarded-* 标头。

Both configurations related to standard and non-standard headers can be combined, although the standard headers configuration will have precedence. However, combining them has security implications as clients can forge requests with a forwarded header that is not overwritten by the proxy. Therefore, proxies should strip unexpected X-Forwarded or X-Forwarded-* headers from the client.

支持的转发地址标头包括：

Supported forwarding address headers are:

Forwarded
X-Forwarded-Proto
X-Forwarded-Host
X-Forwarded-Port
X-Forwarded-Ssl
X-Forwarded-Prefix

可以通过列出 cookie 名称和 SameSite 属性轻松地向 Quarkus 端点设置的任何 cookie 添加 SameSite cookie 属性，例如：

One can easily add a SameSite cookie property to any of the cookies set by a Quarkus endpoint by listing a cookie name and a SameSite attribute, for example:

quarkus.http.same-site-cookie.jwt.value=Lax
quarkus.http.same-site-cookie.session.value=Strict

使用此配置后，jwt cookie 将具有 SameSite=Lax 属性，session cookie 将具有 SameSite=Strict 属性。

Given this configuration, the jwt cookie will have a SameSite=Lax attribute and the session cookie will have a SameSite=Strict attribute.

Servlet Config

要使用 Servlet，你需要明确包含 quarkus-undertow：

To use Servlet you need to explicitly include quarkus-undertow:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-undertow</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-undertow")

undertow-handlers.conf

你可以使用 undertow-handlers.conf 文件来利用 Undertow 断言语言。此文件应放置在你应用程序 jar 的 META-INF 目录中。此文件包含使用 Undertow predicate language 定义的处理器。

You can make use of the Undertow predicate language using an undertow-handlers.conf file. This file should be placed in the META-INF directory of your application jar. This file contains handlers defined using the Undertow predicate language.

web.xml

如果使用 web.xml 文件作为你的配置文件，则可以将其放置在 src/main/resources/META-INF 目录中。

If you are using a web.xml file as your configuration file, you can place it in the src/main/resources/META-INF directory.

Built-in route order values

路由顺序值是通过 Vert.x 路由 io.vertx.ext.web.Route.order(int) 函数指定的值。

Route order values are the values that are specified via Vert.x route io.vertx.ext.web.Route.order(int) function.

Quarkus 用特定的顺序值注册了几条路由。常量在 io.quarkus.vertx.http.runtime.RouteConstants 类中定义，如下表所示。自定义路由应定义 20000 或更高版本的值，以便它不会干扰 Quarkus 和扩展提供的功能。

Quarkus registers a couple of routes with specific order values. The constants are defined in the io.quarkus.vertx.http.runtime.RouteConstants class and listed in the table below. A custom route should define the order of value 20000 or higher so that it does not interfere with the functionality provided by Quarkus and extensions.

在 io.quarkus.vertx.http.runtime.RouteConstants 中定义的路由顺序常量和已知扩展：

Route order constants defined in io.quarkus.vertx.http.runtime.RouteConstants and known extensions:

Route order value

Constant name

Origin

Integer.MIN_VALUE

ROUTE_ORDER_ACCESS_LOG_HANDLER

Access-log handler, if enabled in the configuration.

Integer.MIN_VALUE

ROUTE_ORDER_RECORD_START_TIME

Handler adding the start-time, if enabled in the configuration.

Integer.MIN_VALUE

ROUTE_ORDER_HOT_REPLACEMENT

-replacement body handler.

Integer.MIN_VALUE

ROUTE_ORDER_BODY_HANDLER_MANAGEMENT

Body handler for the management router.

Integer.MIN_VALUE

ROUTE_ORDER_HEADERS

Handlers that add headers specified in the configuration.

Integer.MIN_VALUE

ROUTE_ORDER_CORS_MANAGEMENT

CORS-Origin handler of the management router.

Integer.MIN_VALUE + 1

ROUTE_ORDER_BODY_HANDLER

Body handler.

-2

ROUTE_ORDER_UPLOAD_LIMIT

Route that enforces the upload body size limit.

0

ROUTE_ORDER_COMPRESSION

Compression handler.

1000

ROUTE_ORDER_BEFORE_DEFAULT

Route with priority over the default route (add an offset from this value).

10000

ROUTE_ORDER_DEFAULT

Default route order (i.e. Static Resources, Servlet).

20000

ROUTE_ORDER_AFTER_DEFAULT

Route without priority over the default route (add an offset from this value)

HTTP Reference

Serving static resources

From the application jar

From web dependencies like webjars or mvnpm

From a local directory

HTTP Compression

Other Configurations

Configuring the Context path

Supporting secure connections with TLS/SSL

Using the TLS centralized configuration

Configuring the HTTP server directly

Configure the HTTPS port

Disable the HTTP port

Reloading the certificates

Additional HTTP Headers

Additional HTTP Headers per path

Support 100-Continue in vert.x

HTTP/2 Support

Listening on a Random Port

CORS filter

HTTP Limits Configuration

Configure traffic shaping

Configuring HTTP Access Logs

Arbitrary customizations

How to execute logic when HTTP server started

Running behind a reverse proxy

SameSite cookies

Servlet Config

undertow-handlers.conf

web.xml

Built-in route order values