中文翻译站Http Reference
此文档介绍了可以在 Quarkus 中使用的各种 HTTP 功能。
使用 Eclipse Vert.x 作为基础的 HTTP 层提供 HTTP。 Servlet 使用 运行于 Vert.x 之上的 undertow 的修改版来支持，RESTEasy 被用于支持 JAX-RS 。 如果启用了 Undertow, RESTEasy 将以 Servlet filter 运行, 否则它以无 Servlet 参与的方式直接运行在 Vert.x 之上。
1. 服务静态资源
要为静态资源提供服务，您必须将其放置在应用程序的 META-INF/resources 目录中。 选择这个位置
是因为它是 jar 文件中的资源标准位置，这是由 Servlet 标准定义的。 虽然
Quarkus 可以在没有 Servlet 的情况下使用，遵循此约定允许现有的代码将其资源放置在这个
位置上正常工作。
2. 配置上下文路径（Context path）
By default Quarkus will serve content from under the root context. 如果你想要更改此项，你可以使用
quarkus.http.root-path 配置键来设置上下文路径。
如果你用 Servlet 可以通过 quarkus.servlet.context-path 控制 Servlet 上下文路径。 此条目相对于上面的 http 根目录
并且只会影响服务器上运行的 Servlet 和之上的东西。 大多数应用程序
都想使用 HTTP root，因为这影响到 Quarkus 所服务的一切。
如果两者都被指定，则所有非 Servlet Web 接口将相对于 quarkus.http.root-path, 而 Servlet 会相对
{quarkus.http.root-path}/{quarkus.servlet.context-path}.
如果测试用了 REST Assured 且设置了 quarkus.http.root-path，那么 Quarkus 会自动配置
base URL 用于Quarkus 测试, 因此测试 URL 不应包含根路径。
3. 支持 SSL 安全连接
若要使用 Quarkus 支持安全连接，您必须提供证书和相关的密钥文件，或者提供 keystore。
在这两种情况下，必须提供密码。 关于如何提供的详细说明，请参阅指定的段落。
|
若要在 native 可执行文件中启用 SSL 支持，请参阅我们的 用 Native Executables 使用 SSL 指南。 |
3.1. 提供证书和密钥文件
如果证书未加载到 keystore，可以直接使用下列属性提供。 Quarkus will first try to load the given files as resources, and uses the filesystem as a fallback. 证书/密钥对将在启动时被加载到新创建的 keystore 。
你的 application.properties 看起来像这样：
quarkus.http.ssl.certificate.file=/path/to/certificate
quarkus.http.ssl.certificate.key-file=/path/to/key3.2. 提供 keystore
另一个解决方案是直接提供一个keystore，该 keystore 已经包含一个缺省证书条目 您至少需要提供文件和密码。
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 中添加以下属性：
quarkus.http.ssl.certificate.key-store-file=/path/to/keystore作为可选提示, keystore type 可以是所列之一。 如果未提供类型，Quarkus 将尝试从文件扩展名中推断它，默认 JKS。
quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]3.3. 设置密码
在上述两个场景中，需要提供密码来创建/加载keystore。
密码可以用以下属性设置在 application.properties (纯文本) 中：
quarkus.http.ssl.certificate.key-store-password=your-password然而，替代在配置文件以纯文本形式提供密码(被认为是错误的做法)，可以 (使用 MicroProfile config)
通过环境变量 QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD 提供密码。
也可与 Kubernetes secrets 配合。
Note: 为了保持与 Quarkus 早期版本的兼容性(在0.16之前)，默认密码设置为 "password"。 因此，它不是一个强制性参数！
4. CORS filter
Cross-origin resource sharing (CORS) 是一种允许网页访问跨域资源的机制。
Quarkus 带有一个 CORS filter，它实现了 javax.servlet.Filter 接口，并且拦截了所有传入的 HTTP
请求。 它可以在 Quarkus 配置文件 src/main/resources/application.properties 中启用：
quarkus.http.cors=true如果 filter 已启用并且一个 HTTP 请求被识别为跨域请求， the CORS policy and headers defined using the following properties will be applied before passing the request on to its actual target (servlet, JAX-RS resource, etc.):
| 属性名称 | 默认 | 描述 |
|---|---|---|
|
逗号分隔的来源列表允许CORS。 如果没有 设置，过滤器允许任何来源。 |
|
|
允许CORS使用逗号分隔的 HTTP 方法列表。 如果没有设置 ，过滤器允许使用任何方法。 |
|
|
允许CORS使用逗号分隔的 HTTP 头列表。 如果没有设置 ，过滤器允许任何头部。 |
|
|
在 CORS 中暴露的 HTTP 头逗号分隔的列表。 |
|
|
持续时间(见下面注)，说明飞行前请求的结果可以缓存多长时间。
此值将在一个 |
|
The format for durations uses the standard You can also provide duration values starting with a number.
In this case, if the value consists only of a number, the converter treats the value as seconds.
Otherwise, |
下面是完整的 CORS 过滤器配置可以看起来像：
quarkus.http.cors=true
quarkus.http.cors.origins=http://foo.com,http://www.bar.io
quarkus.http.cors.methods=GET,PUT,POST
quarkus.http.cors.headers=X-Custom
quarkus.http.cors.exposed-headers=Content-Disposition
quarkus.http.cors.access-control-max-age=24H5. HTTP 限制配置
支持以下属性。
| 属性名称 | 默认 | 描述 |
|---|---|---|
|
|
请求体的最大大小。 |
|
|
所有 header 的最大大小。 |
|
下面的配置选项将识别以此格式表示的字符串大小(显示为正则表达式)：
|
6. Servlet 配置
若要使用 Servlet，您需要明确包含 quarkus-undertow：
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-undertow</artifactId>
</dependency>6.1. undertow-handlers.conf
You can make use of the Undertow predicate language using an undertow-handlers.conf file. 此文件应放在应用 jar 的
META-INF 目录. 此文件包含用
Undertow predicate language 定义的 handlers.
6.2. 配置 HTTP 访问日志
您可以通过配置 undertow-handlers.conf 文件中的 AccessHandler 来记录 HTTP 请求日志。
最简单的配置可以是标准的 Apache `common`日志格式：
access-log('common')每个请求都将用标准的 Quarkus 日志机制记录在 io.undertow.accesslog 类别下。
您可以自定义如下类别：
access-log(format='common', category='my.own.category')最后可以自定义日志格式：
access-log(format='%h %l %u %t "%r" %s %b %D "%{i,Referer}" "%{i,User-Agent}" "%{i,X-Request-ID}"', category='my.own.category')
