第 7 章 自己开窗口：设计一个像样的 API

第一册第 4 章你学会了用别人的窗口；这一章学开自己的。这不是假设题——EchoForge 迟早（或已经）要把"验证一张凭证"这样的能力开放给别人的程序调用。窗口一旦开出去，设计的好坏就写在脸上了。好设计有四根柱子。

**柱子一：名词做 URL，动词交给 HTTP。**资源是名词复数：/v1/certificates 是凭证们，/v1/certificates/:id 是其中一张。动作用第一册学过的 HTTP 动词表达：GET 查、POST 建、PATCH 改、DELETE 删。URL 里冒出动词（/getCertificate、/doVerify）不致命，但一闻就不专业——像菜单上写"进行一个鱼的吃"。

**柱子二：响应有统一的形状，失败也要设计。**成功长什么样、失败长什么样，第一天就定下来，所有端点共用。失败的标本：

{ "error": { "code": "not_found", "message": "certificate not found" } }

配上状态码的几张头牌脸：200 成了；400 你的请求有毛病；401 你是谁；403 你不许；404 没这东西；500 我这边坏了。这些数字第 9 章读日志时天天见——统一的错误形状加准确的状态码，就是把排障从猜谜变成查表。

**柱子三：钥匙进请求头，永不进 URL。**调用方的 API Key 放在请求头里（Authorization: Bearer 一串钥匙）。为什么绝不放 URL？因为 URL 会进访问日志、进浏览器历史、进各种统计——把钥匙写在 URL 里，等于把家门钥匙写在明信片上寄出去。（第一册第 9 章的纪律，在窗口的另一侧同样成立。）

**柱子四：版本号，从第一天开始。**所有路径以 /v1/ 开头。为什么第一个用户还没来就要版本？因为窗口一旦有人在用，你的每次改动都会砸在他们头上。/v1 是一份冻结的承诺：这里的行为不再变，想改，开 /v2。听出来了吗——**已发布的 API、已推送的 Git 历史、已部署的链上合约，是同一家人：进了公共世界的东西，只能追加，不能背叛。**这是这套书第三次遇到这条定律，它值得三次。

最后半根柱子：文档即产品。窗口开了没人会用，等于没开。最小文档标准：每个端点一行——方法、路径、吃什么、吐什么，配一个能直接复制的调用例子。让 AI 生成初稿，你负责校对"它说的和窗口真实行为是否一致"。

出事时想起我

调用方说"你们 API 坏了"——先要三样东西：状态码几？完整请求长什么样？打的哪个版本？有了统一形状和版本号，这三问几乎总能当场定位；反过来，如果这三问问不出所以然，说明四根柱子有一根没立好。

关键领悟

API 设计的本质是替未来的调用者减少惊讶——包括未来的自己和 AI。名词做 URL、统一响应形状、钥匙进请求头、版本从第一天开始，四根柱子立住，窗口就体面了。

试一试（安全档：纸上作业）

为"验证一张凭证"设计一个只读端点：写下方法、路径、成功响应的形状、两种失败（不存在 / 未授权）的响应和状态码。写完先让 AI 挑刺，再拿本章四根柱子自查一遍——两轮下来还站得住的设计，就可以进需求文档了。