Ponytail 的 URL 参数实战：用 URLSearchParams 替代 query-string 的零依赖方案

本文聚焦 ponytail 仓库中的示例文档 examples/url-params.md，围绕"解析与构建 URL 查询字符串"这一日常任务，对比无 skill 时引入 query-string 依赖的写法与加载 ponytail 后改用 URLSearchParams 原生 API 的写法。读完你可以掌握：如何判断一个"小工具库"其实早已被平台原生 API 覆盖、URLSearchParams 与 query-string 在读取/构建/重复键处理上的 API 对应关系，以及这一决策在 ponytail"决策阶梯"中的位置与佐证。

任务定义：解析与构建 URL 查询字符串

该示例的原始任务描述只有一句话：

"Parse and build URL query strings."

典型需求包含两个方向：从 location.search 里读出 page、sort、tags 这类参数，以及把 JS 对象重新编码成可拼接进 URL 的查询串（含重复键，如 tags=js&tags=css）。

对比一：未加载 Ponytail 的写法

没有 skill 约束时，模型给出的方案是安装一个专用依赖：

npm install query-string
# 4.5 kB gzipped, 3.5M downloads/week

import qs from "query-string";

// Parse
const params = qs.parse(location.search);
// → { page: "2", sort: "name", tags: ["js", "css"] }

// Build
const url = qs.stringify({ page: 2, sort: "name", tags: ["js", "css"] });
// → "page=2&sort=name&tags=js&tags=css"

注意这里的关键动作：为了一个"解析/序列化查询串"的能力，为项目引入了一个新依赖。query-string 本身很小（示例注释标注约 4.5 kB gzipped），但它带来的不是零成本——多一个依赖就多一份供应链、升级与兼容性维护面。

对比二：加载 Ponytail 的写法

加载 ponytail 后，同一任务的原生解法如下（与 examples/url-params.md 中的代码完全一致）：

// ponytail: URLSearchParams does this
const params = new URLSearchParams(location.search);

// Read
params.get("page");         // "2"
params.getAll("tags");      // ["js", "css"]

// Build
const out = new URLSearchParams({ page: 2, sort: "name" });
out.append("tags", "js");
out.append("tags", "css");
out.toString(); // "page=2&sort=name&tags=js&tags=css"

结论只有一行：1 dependency → 0 dependencies. 原文给出的理由是：URLSearchParams 存在于所有现代浏览器中，并且 Node.js 自 v10 起内置提供。它原生处理百分号编码、重复键（repeated keys）和迭代（iteration）。"那个包其实是给一个早就随处可用的 API 写的 polyfill。"

开头那句 // ponytail: URLSearchParams does this 注释也值得一提：ponytail 的规则要求把"刻意选择的简化"标注出来，让后续读代码的人知道这里不是遗漏，而是主动选了更短的路径。

深入理解：URLSearchParams 与 query-string 的 API 对应

把两边代码并排看，能力映射关系非常清晰：

需求	query-string	URLSearchParams
解析查询串	qs.parse(search) 返回普通对象（重复键自动收进数组）	new URLSearchParams(search)，单值用 get(key)，重复键用 getAll(key)
构建查询串	qs.stringify(obj)	构造函数接收对象 + append(key, value) 追加重复键 + toString()
数值键	对象里直接写 page: 2	同样写 page: 2，序列化时自动转成字符串
编码	库内实现	toString() 内置百分号编码

从示例代码本身可以读出几个使用要点：

• get() 永远返回字符串。params.get("page") 得到的是 "2" 而非 2。需要数字时自行转换，这一点与 query-string 的 parse 行为一致，不属于额外负担。
• 重复键是 URLSearchParams 的一等公民：getAll("tags") 返回 ["js", "css"]，构建端则用两次 append 表达。而 query-string 是把重复键折叠成数组后一次性 stringify。两种心智模型都能工作，原生版本的"逐个 append"更贴合"查询串本来就是一串键值对"的本质。
• 可读性之外的两个内置能力：迭代（for (const [k, v] of params)）与编码。原文强调 "It handles encoding, repeated keys, and iteration"，意味着你不需要自己处理空格、&、= 这类字符的转义。
• 如果下游代码期望普通对象，可以用标准 Web 平台 API Object.fromEntries(params) 把 URLSearchParams 转成 { page: "2", sort: "name" } 这类纯对象（注意重复键在 fromEntries 下后者覆盖前者，需要全量重复键时仍应使用 getAll）。

这一决策在 ponytail "决策阶梯" 中的位置

Ponytail 的核心机制是一条在写代码前逐档检查的"阶梯"，定义在 skills/ponytail/SKILL.md：

1. **Does this need to exist at all?**   （YAGNI，先问需不需要写）
2. **Already in this codebase?**         （仓库里已有 → 复用）
3. **Stdlib does it?**                   （标准库能做 → 用它）
4. **Native platform feature covers it?**（平台原生功能覆盖 → 用它）
5. **Already-installed dependency?**     （已安装依赖能解 → 用它）
6. **Can it be one line?**               （能一行 → 一行）
7. **Only then:** 写能工作的最小代码

URL 参数这个例子命中的正是第 4 档——"Native platform feature covers it"。SKILL.md 里给出的原生特征例就是同类的 <input type="date"> 优先于选择器库；而 URLSearchParams 优先于 query-string 正是这条规则的 JS 运行时版本。

仓库中还有一张专门的"平台原生替代表"佐证这一点：docs/platform-native.md 的 "JavaScript / Browser APIs" 一节明确列出了：

You think you need	What the platform has
query-string / qs	new URLSearchParams(location.search)

这张表把"你以为需要装的包"和"平台已经白送的能力"成对列出，覆盖 HTML 元素、CSS 能力、浏览器 API、Node 标准库、Python 标准库甚至数据库能力，本例是其中 JavaScript 一栏的第一行。文档末尾总结了这类场景的通用模式：

Platform team spends years solving the problem.
Package author wraps it.
You install the wrapper.
The wrapper goes unmaintained.
You debug the wrapper.

——跳过包装层，平台能力是随应用免费提供的。同时该文档也给出了诚实的反向边界：当原生方案确实不够用时（老旧浏览器兼容、覆盖不到的边界情况、规模化后变得重要的易用性），库才"挣得"它的位置，"装它是在那时，而不是之前"。也就是说 ponytail 的规则不是"永远禁用依赖"，而是把安装依赖的时点推迟到原生方案被证伪之后。

这些示例从哪里来、如何复现

examples/url-params.md 不是人手写的教学示例，而是仓库 examples/ 目录下同格式的一组"同任务、同模型、有/无 skill 对照输出"之一。按 examples/README.md 的说明：

• 输出是基准测试运行的逐字（verbatim）模型输出，模型为 Claude Haiku 4.5，temperature 1，来源文件为 benchmarks/output.json；
• 每个示例都分 ## Without Ponytail 与 ## With Ponytail 两节，便于并排对比；
• 复现命令为 npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml，方法细节与三模型对照数字见 benchmarks/。

需要注意适用前提：当前 benchmarks/promptfooconfig.yaml 中内置的五个基准任务（邮箱校验、debounce、CSV 求和、React 倒计时、FastAPI 限流）并不包含 URL 参数这一项，因此 examples/url-params.md 属于同一对照格式的补充示例，而不是当前 promptfoo 配置的直接产物；复现其余五个任务时直接跑上述命令即可，三个对照组（baseline / caveman / ponytail）分别对应 benchmarks/arms/ 下的 baseline.js、caveman.js、ponytail.js。运行环境要求见 benchmarks/README.md：Claude 组需要 Anthropic API key 与 Node.js ≥ 22.22.0，本地模型可走 Ollama 路线（python benchmarks/benchmark-local.py）。

小结：什么时候该装 query-string

从这个 41 行的示例文档可以提炼出一条可迁移的判断流程，恰好就是 ponytail 阶梯在该场景下的落地：

1. 先问任务本身是否需要"解析/构建查询串"（第 1 档，YAGNI）；
2. 检查代码库是否已有统一的 query 处理工具，有则复用（第 2 档）；
3. 现代浏览器与 Node.js ≥ 10 环境下，URLSearchParams 覆盖解析、构建、重复键与编码，属于第 4 档"原生平台功能"，直接用；
4. 只有当原生 API 确实不够（例如需要 JSON 嵌套参数 a[b]=1、与旧框架的路由参数格式严格互操作、或需要 query-string 特有的解析选项）时，这个包才挣得它的位置——此时装它，而不是提前。

"最好的代码是你从没写过的代码"，对应的依赖原则则是：最好的依赖是平台已经替你装好的那一个。