用于 HTTP 的 Prefer 首部

本规范使用增强巴科斯-诺尔范式（ABNF）表示法，参见 [RFC5234]，并按引用包含 [RFC7230] 第 3.2.1 和 3.2.4 节中定义的 "token"、"word"、"OWS"、"BWS" 规则与 #rule 扩展；以及在 [RFC7231] 第 8.1.3 节中定义的 "delta-seconds" 规则。

1. 如果请求在 10 秒内无法处理完毕，则为异步处理返回 202 (Accepted)。另外示例中也指明了未定义的 "priority" 偏好：

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10
Prefer: priority=5

{...}

2. 使用宽容（lenient）处理：

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: Lenient

{...}

3. 在 return=minimal 偏好上使用一个可选的未定义参数：

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal; foo="some parameter"

{...}

“respond-async” 偏好指示客户端偏好服务器以异步方式响应。例如，当生成响应所需的时间超过服务器设定的某个阈值时，服务器可以通过返回 202 (Accepted) 响应来采纳该偏好。

ABNF:

  respond-async = "respond-async"
      

“respond-async” 偏好的主要动机是通过允许客户端向服务器表明其支持并偏好异步响应，来促进异步请求处理的运作。

示例：在请求中指定 "respond-async" 偏好：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async

{Data}

示例：返回 202 (Accepted) 的异步响应：

HTTP/1.1 202 Accepted
Location: http://example.org/collection/123

尽管 202 (Accepted) 状态由 [RFC7231] 定义，但关于如何使用该状态码以及如何确定操作最终结果的过程未给出详细指导。因此，服务器是否以及如何支持异步响应是实现细节，不在本规范范围之内。

“return=representation” 偏好表示客户端偏好服务器在成功响应中包含表示资源当前状态的实体。

另一方面，“return=minimal” 偏好表示客户端希望服务器在成功响应中仅返回最小响应。通常这样的响应会使用 204 (No Content) 状态，但也可以使用其他合适的状态（例如 200 (OK) 且响应实体长度为零）。什么构成适当的最小响应完全由服务器决定。

ABNF:

  return = "return" BWS "=" BWS ("representation" / "minimal")
      

当采纳 "return=representation" 偏好时，返回的表示在请求影响另一个资源时可能并非对有效请求 URI 的表示。在这种情况下，可使用 Content-Location 首部来标识返回表示的 URI。

“return=representation” 偏好旨在通过消除随后为检索修改后资源当前表示而进行的 GET 请求来优化客户端与服务器之间的通信。

在成功处理诸如 POST 或 PUT 之类的修改请求后，服务器可以选择返回描述操作状态的实体，或返回修改后资源的表示。返回哪种类型的实体（如果返回）完全由服务器决定，但 “return=representation” 和 “return=minimal” 偏好允许服务器在构建响应时考虑客户端的偏好。

示例：在请求中指定 "return=representation" 偏好：

PATCH /item/123 HTTP/1.1
Host: example.org
Content-Type: application/example-patch
Prefer: return=representation

1c1
< ABCDEFGHIJKLMNOPQRSTUVWXYZ
---
> BCDFGHJKLMNPQRSTVWXYZ

示例响应：包含资源表示：

HTTP/1.1 200 OK
Content-Location: http://example.org/item/123
Content-Type: text/plain
ETag: "d3b07384d113edec49eaa6238ad5ff00"

BCDFGHJKLMNPQRSTVWXYZ

相比之下，"return=minimal" 偏好可以减少服务器在请求后需要返回的数据量。这在与带宽受限的移动设备通信或客户端仅需知道请求是否成功而无需进一步信息时尤其有用。

示例：在请求中指定 "return=minimal" 偏好：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal

{Data}

示例最小响应：

HTTP/1.1 201 Created
Location: http://example.org/collection/123

"return=minimal" 与 "return=representation" 是互斥的指令。预计不会出现某个请求同时包含两者的合理情形。任何同时包含两者的请求很可能是客户端编码错误的结果，因此可以按未指定任何偏好来处理。

“wait” 偏好可用于指定客户端期望服务器从接收请求到生成响应所花费时间的上限（以秒为单位）。如果生成响应所需时间超过指定时间，服务器或代理可以选择采用异步处理模型，例如返回 202 (Accepted)。

ABNF:

  wait = "wait" BWS "=" BWS delta-seconds
      

需要注意的是，HTTP 消息在网络传输和经由中间件处理时也会花费时间。这会使客户端等待响应的总体时间增加，超出服务器自身处理请求所需的时间。具有严格时限要求的客户端可以估计这些因素并相应地调整 wait 值。

与其他偏好一样，“wait” 偏好也可以被忽略。客户端可以放弃那些超出其愿意等待时间的请求。

例如，服务器收到如下请求时，如果处理该请求需要超过 10 秒，则可能选择异步响应：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10

{Data}

“handling=strict” 与 “handling=lenient” 偏好指示客户端希望服务器如何处理在请求处理过程中可能出现的错误情况。例如，如果请求负载包含若干小的语法或语义错误，但服务器仍能理解并成功处理请求，则必须决定是以适当的 4xx 错误码拒绝请求，还是继续处理。使用 "handling=strict" 偏好可以指示客户端希望服务器拒绝请求（即使某个错误可能是可恢复的）。相反，"handling=lenient" 表示客户端希望服务器尝试处理请求。

ABNF:

  handling = "handling" BWS "=" BWS ("strict" / "lenient")
    

示例：在请求中指定 "strict" 偏好：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: handling=strict

"handling=strict" 与 "handling=lenient" 为互斥指令。预计不会有使两者同时出现在单个请求中有意义的情况。任何同时包含两者的请求很可能是客户端的编码错误，因此可按未指定任何偏好来处理。

IANA 已在 “Hypertext Transfer Protocol (HTTP) Parameters” 注册表下创建了一个新的注册表 “HTTP Preferences”。新的注册使用 Specification Required 策略 [RFC5226]。偏好的注册要求在 第 4 节 中描述。

注册请求包括下面的注册模板，通常在所需规范中发布。然而，为了在发布之前分配值，指定专家可以在确认规范会被发布后基于单独提交的模板批准注册。在专家认为未及时注册但已被广泛部署且不太可能及时注册的未注册偏好时，第三方也可以提交注册请求。

• Preference:（Prefer 请求首部字段中符合 第 2 节 所给语法规则的值）
• Value:（对偏好标记可能值的枚举或描述）
• Optional Parameters:（偏好标记相关的可选参数及其值的枚举）
• Description:
• Reference:
• Notes: [可选]

若特定偏好标记定义中不包含“Value”或“Optional Parameters”字段，则在注册模板中可以省略这些字段。

注册请求应发送至 <ietf-http-wg@w3.org> 邮件列表，并在主题行中清楚标注（例如，“NEW PREFERENCE - example” 用于注册 "example" 偏好）。指定专家将在最多 14 天内批准或拒绝注册请求，并将决定告知审查列表和 IANA。拒绝应包含解释并在适用时建议如何使请求成功。

专家审查员应确保：

• 请求的偏好名称符合 第 2 节 中的 token 规则，且不与任何已注册偏好名称重复；
• 任何关联的值、参数名和参数值符合 第 2 节 中相关的 ABNF 语法规范；
• 名称应与偏好的特异性相匹配；即若语义高度特定于某应用，则名称应反映该特性，以便为较不具体的用途保留通用名称；
• 请求的偏好不应强制服务器、客户端或任何中间件采用完成处理所必需的行为；
• 定义偏好的规范文档应包含对使用该偏好相关的安全注意事项的完整讨论。

• Preference: respond-async
• Description: 指示客户端偏好服务器对请求以异步方式响应。
• Reference: [本规范], 第 4.1 节

• Preference: return
• Value: "minimal" 或 "representation" 其一
• Description: 当值为 "minimal" 时，表示客户端偏好服务器对请求返回最小响应；当值为 "representation" 时，表示客户端偏好服务器在响应中包含资源当前状态的表示。
• Reference: [本规范], 第 4.2 节

• Preference: wait
• Description: 指示客户端期望服务器在接收请求后处理请求所需时间的上限。
• Reference: [本规范], 第 4.3 节

• Preference: handling
• Value: "strict" 或 "lenient" 其一
• Description: 值为 "strict" 表示客户端希望服务器对请求的处理应用严格的验证和错误处理；值为 "lenient" 表示客户端希望服务器应用宽容的验证和错误处理。
• Reference: [本规范], 第 4.4 节

7.1. 规范性参考文献

[RFC2119]

Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.

[RFC3864]

Klyne, G., Nottingham, M., and J. Mogul, “Registration Procedures for Message Header Fields”, BCP 90, RFC 3864, September 2004, <https://www.rfc-editor.org/info/rfc3864>.

[RFC5226]

Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs”, RFC 5226, May 2008, <https://www.rfc-editor.org/info/rfc5226>.

[RFC5234]

Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF”, STD 68, RFC 5234, January 2008, <https://www.rfc-editor.org/info/rfc5234>.

[RFC7230]

Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing”, RFC 7230, June 2014.

[RFC7231]

Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content”, RFC 7231, June 2014.

7.2. 补充性参考文献

[RFC5023]

Gregorio, J., Ed. and B. de hOra, Ed., “The Atom Publishing Protocol”, RFC 5023, October 2007, <https://www.rfc-editor.org/info/rfc5023>.