网址查询接口规范 0.1.0
本包提供三个只做字符串运算的函数，按 WHATWG application/x-www-form-urlencoded 规则生成、解析查询串，并改写网址的一个查询参数。三者无权限要求、无外部副作用；当前只有云工适配（用宿主的 URLSearchParams 与 URL），其他宿主若实现须给出相同结果。
编码查询串 项列 接受有序的（名称，值）列表，返回表单编码的查询串（即 new URLSearchParams(项列).toString()）：空格写作 +；除字母、数字与 *-._ 外一律按 UTF-8 百分号编码，因此 !'()~ 也被编码；同名项按原序保留；空列表得空字符串；名称、值可含任意 UTF-8 与控制字符。限额：最多 1024 项，全部名称与值的总字节数不超过 1 MiB，超限为违规（“查询项超过 1024 项”“查询项总长度超过 1 MiB”）。
解析表单键值 文字 按 WHATWG application/x-www-form-urlencoded 规则解析：以 & 分项，忽略空项，首个 = 前为名称，其后为值，+ 视为空格，百分号解码，非法 UTF-8 序列以 U+FFFD 替换；输入首字符若是 ?，先去掉这一个（与 URLSearchParams 构造器一致，故可直接传入含开头问号的原查询串）。返回保持原序的 [["名","值"],…] JSON 数组文字，同名项各占一项，空输入得 []；返回文字是宿主序列化的紧凑 JSON，应用应把它当 JSON 解析，不依赖空白或转义细节。输入不超过 1 MiB，超限为违规（“表单文字超过 1 MiB”）。
设置网址查询参数 网址 键 值 按 URL 与 searchParams.set 的语义设置一个查询参数：同名旧项全部替换为一项，位置在第一个同名项处，其余参数保留，并按表单规则重新序列化整个查询串（因此其余参数的百分号写法可能被规范化）；片段原样保留。
- 绝对网址：必须是
http:或https:（其他方案，如javascript:、data:、ftp:，失败，“绝对网址不是 HTTP(S)”），返回完整的href。 - 相对网址：以内部固定基址
https://yuyan-lang.org解析，只返回pathname + search + hash；解析结果的来源若不是该基址（例如//evil.example/x、\\evil.example）则失败（“相对网址不得改变来源”），无法解析时失败（“网址无效”）。 - 限额：网址、键、值各不超过 64 KiB（“网址、键或值超过 64 KiB”）。键与值可含任意 UTF-8 与控制字符，由宿主自行编码，不会破坏参数。
失败类别
违规（可捕获的豫言异常）：项数或总长度超限、输入超限、网址无效、方案不是 HTTP(S)、相对网址改变来源。本包没有业务情形分支：结果总是字符串。
一致性样例
| 调用 | 必须观察到 |
| --- | --- |
| 编码查询串 传 [("a b","1+2"),("a b","!'()~-._")] | `a+b=1%2B2&a+b=%21%27%28%29%7E-._` |
| 编码查询串 传 [("名","\u0001\n")] | %E5%90%8D=%01%0A |
| 解析表单键值 传 a=1&b=x+y%20z&a=%E4%BD%A0&c&d=%ff&=e | [["a","1"],["b","x y z"],["a","你"],["c",""],["d","\ufffd"],["","e"]]（JSON 中的 U+FFFD 可以字面或转义写出） |
| 解析表单键值 传 ?a=1 | [["a","1"]] |
| 设置网址查询参数 传 /p?a=1&b=2&a=3#h，键 a，值 新 值 | /p?a=%E6%96%B0+%E5%80%BC&b=2#h |
| 设置网址查询参数 传 https://h.example/p?a=1，键 b，值 2 | https://h.example/p?a=1&b=2 |
| 设置网址查询参数 传 //evil.example/x 或 javascript:alert(1) | 违规 |
不做什么
不发起网络请求，不解析或校验主机名，不做路径规范化以外的网址改写，不支持数组式（a[]=）或嵌套的查询参数约定，不提供多值删除，也不排序参数。
补充：表单项数上限与首 BOM（独立审查后修订）
解析表单键值最多 1024 项（以URLSearchParams.size计），超过抛可捕获的「表单项数超过 1024」，免得 1 MiB 的表单产出五十多万项而拖垮癸象解析。- 文字交宿主 TextDecoder 时使用
ignoreBOM: true：文首的 U+FEFF 保留。