2.2.8. Query Parameters (查询参数)
2.2.8. Query Parameters (查询参数)
若请求目标 URI 的查询部分使用 [HTMLURL] 第 5 节 ("application/x-www-form-urlencoded") 所定义格式的 HTML 表单参数, @query-param 派生组成部分允许寻址这些单个查询参数. 查询参数必须按 [HTMLURL] 第 5.1 节 ("application/x-www-form-urlencoded parsing") 解析, 得到 (nameString, valueString) 元组列表. 各组成部分标识符的必需 name 参数包含单个查询参数的编码 nameString, 为 String 值. 单个命名参数的组成部分值为该单个查询参数的编码 valueString. 被覆盖组成部分中可包含若干不同命名的查询参数. 单个命名参数在被覆盖组成部分中可以任意顺序出现, 无论其在查询字符串中的顺序.
name 参数的值与单个命名参数的组成部分值通过下列过程计算:
-
按 [HTMLURL] 第 5.1 节 ("application/x-www-form-urlencoded parsing") 解析命名查询参数的 nameString 或 valueString, 此为百分号编码八位组解码后的值.
-
使用 [HTMLURL] 第 5.2 节 ("application/x-www-form-urlencoded serializing") 定义的 "percent-encode after encoding" 过程编码 nameString 或 valueString, 得到 ASCII 字符串 [ASCII].
-
输出该 ASCII 字符串.
注意组成部分值不包含任何前导问号 (?), 等号 (=) 或分隔和号 (&) 字符. 具有空 valueString 的命名查询参数的组成部分值为空字符串. 注意由于实现不一致, 某些查询参数解析库会丢弃此类空值.
若某查询参数被列为被覆盖组成部分但其未出现在查询参数中, 签名基生成必须产生错误.
例如, 对下列请求:
GET /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 Host: www.example.com
指示 baz, qux 与 param 命名查询参数将产生下列 @query-param 组成部分值:
baz: batman
qux: 空字符串
param: value
以及下列签名基行, (SP) 表示空组成部分值前的单个尾随空格字符:
"@query-param";name="baz": batman "@query-param";name="qux":(SP) "@query-param";name="param": value
该派生组成部分存在若干限制. 具体地, [HTMLURL] 第 5 节 ("application/x-www-form-urlencoded") 提供的算法仅支持使用百分号转义 UTF-8 编码的查询参数. 不支持其他编码. 此外, 现实中对同名参数的多实例支持不可靠. 若参数名在请求中出现多次, 不得包含该命名查询参数. 若某应用中多个参数很常见, 建议使用第 2.2.7 节定义的 @query 组成部分标识符对整个查询字符串签名.
编码过程允许值中包含换行或其他有问题的字符的查询参数, 或使用加号 (+) 表示空格等替代编码. 对本消息中的查询参数:
NOTE: '' line wrapping per RFC 8792
GET /parameters?var=this%20is%20a%20big%0Amultiline%20value&
bar=with+plus+whitespace&fa%C3%A7ade%22%3A%20=something HTTP/1.1
Host: www.example.com
Date: Tue, 20 Apr 2021 02:07:56 GMT
所得值编码如下:
"@query-param";name="var": this%20is%20a%20big%0Amultiline%20value "@query-param";name="bar": with%20plus%20whitespace "@query-param";name="fa%C3%A7ade%22%3A%20": something
若未应用编码, 所得值将为:
"@query-param";name="var": this is a big multiline value "@query-param";name="bar": with plus whitespace "@query-param";name="façade": ": something
该基字符串包含违反组成部分名与值约束的字符, 因此无效.