API 是什么
本合集目录
本章目录
单册说明:本文件是卷 5 的第 1 章,可独立阅读。前置:卷 4(服务端取数、
lib/notes.js数据层)。本章不讲后端代码,只讲一件比代码更难改的事:接口的契约怎么定。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 5 · 后端与 API(第 1 / 8 章) |
| 前置章节 | 4.7 数据获取、缓存与环境变量 |
| 本章产出 | 一份写在纸上的「读到」接口契约 + 一次用 curl 手工调通的请求 |
| 对应代码 | 无后端代码;本章只有命令(见 5.1.7) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 拿到一个状态码,能说出"是谁的问题、该谁去改";能解释为什么 POST 不能盲目重试 |
5.1.1 一句话结论:接口是契约,不是函数
先看一段真实对话。前端同学说"接口好了",后端同学说"早好了,你自己传错了"。两边都没说谎,因为他们对"好"的定义不一样:一个说"能返回数据",一个说"字段名对得上"。
再看真实报错。前端写下 const notes = await res.json(); notes.map(...),控制台出现:
Uncaught TypeError: notes.map is not a function
因为后端返回的是 {"items": [...], "total": 3},而前端以为顶层就是数组。接口能跑、数据也对,只是形状不是约定的那个。
所以这一章的核心判断是:
函数是"我调用你,你给我结果";接口是"我们各自照一份文件办事,谁都不看谁的内部"。
函数改签名,调用方立刻编译报错;接口改字段,调用方在运行时才悄悄拿到 undefined。这就是为什么接口必须有一份写下来、能对照、能验收的契约。
5.1.2 原理与方法
契约有三方,不止两方
| 角色 | 关心什么 | 违约的后果 |
|---|---|---|
| 调用方(前端、脚本、别人的系统) | 我按文档发的请求,你保证这么回 | 拿到 undefined、页面空白、批量任务全失败 |
| 实现方(你的后端) | 我按文档收请求,多余的我不认 | 多传字段被静默丢弃,或直接 422 |
中间人(文档、/docs、curl 脚本) |
两边说的话是否一致 | 一旦过期,两边都"照文档做"却对不上 |
第三方最典型。本书只有你自己一个调用方,所以你可以"边改边对齐";但只要有一天有个脚本在半夜跑你的接口,契约就变成了不能单方面修改的东西。这也是本卷后面反复强调"字段名全书统一"的原因。
请求四要素,响应四要素
一次 HTTP 交互,两边各有四样东西。背下来,5.2 章就是把它们拆开看。
| 位置 | 请求 | 响应 |
|---|---|---|
| 第一行 | 方法 + 路径 + 协议版本:POST /api/notes HTTP/1.1 |
协议版本 + 状态码 + 原因短语:HTTP/1.1 201 Created |
| 头部 | Content-Type: application/json、Authorization: ... |
Content-Type、Location、Set-Cookie |
| 空行 | 必须有,用来分隔头和体 | 同左 |
| 主体 | JSON、表单、文件(GET 通常没有) | JSON、HTML、二进制 |
四要素里最容易被忽略的是头部:新手只盯着"发了什么、回了什么",而 90% 的联调故障写在头里——类型不对(5.2)、来源不对(5.7)、凭据没带(卷 6)。
REST 的资源命名:/notes 而不是 /getNotes
REST 不是协议,是一种把"操作"翻译成"资源"的习惯。判断标准只有一条:路径里放名词,动作交给方法。
| 想法 | 别这么写 | 应该这么写 |
|---|---|---|
| 取列表 | GET /getNotes |
GET /api/notes |
| 取一条 | GET /noteById?id=3 |
GET /api/notes/3 |
| 新增 | POST /createNote |
POST /api/notes |
| 改一条 | POST /updateNote |
PATCH /api/notes/3 |
| 删一条 | GET /deleteNote?id=3 |
DELETE /api/notes/3 |
| 按标签筛 | GET /getNotesByTag?tag=js |
GET /api/notes?tag=js |
三条附带规则:
- 用复数。
/notes是集合,/notes/3是集合里的一个,读起来自洽。 - 层级表达归属。将来有了标签关系,
/api/notes/3/tags比/api/noteTags?noteId=3更清楚。 - 筛选、分页、排序都放查询串,不要造新路径。
?tag=js&page=2是同一个资源的不同视图。
本书的接口前缀统一是 /api。为什么不带 /v1?因为你只有一个客户端,而且它跟你一起发布。版本号是给"你控制不了的调用方"准备的;等你真的开放给别人用,再引入 /api/v1 并把旧路径保留一段时间。提前加版本号不是严谨,是给自己增加维护面。
状态码:分工比具体数字重要
新手记 40 个状态码,老手只记四条分工:
| 段 | 含义 | 谁该去改 | 典型 |
|---|---|---|---|
| 2xx | 成功了,别重试 | 谁都不用改 | 200 有内容、201 新建了、204 成功但没内容 |
| 3xx | 东西不在这儿,去别处 | 调用方跟着跳 | 301/308 永久搬家、304 你手上的缓存还能用 |
| 4xx | 你的请求有问题 | 调用方改请求 | 400 语法错、401 没登录、403 登录了但没权限、404 没这个资源、409 状态冲突、422 字段不合法、429 太快了 |
| 5xx | 我的服务器有问题 | 实现方改代码/配置 | 500 崩了、502 网关连不上后端、503 暂时不可用、504 后端超时 |
这张表最大的用处是分责。用户截图给你"打不开",你只看状态码就能分派:
| 你看到的 | 一句话判断 | 先查哪里 |
|---|---|---|
422 |
前端发的字段名或类型不对 | 浏览器 Network 里的请求体,对照 5.1.4 的契约 |
404 |
路径写错,或这条记录真没了 | 请求 URL 的前缀,/api 有没有漏 |
500 |
后端代码抛异常了 | 后端日志(5.6 会教你怎么让日志能查) |
502 |
请求没到后端 | 后端进程活着吗(卷 7 的 systemd) |
⚠️ 一个高频误用:把业务失败塞进 500。比如"标题重复"返回 500,前端就只能显示"服务器错误",用户不知道该怎么办。判断口诀:这句话能不能让用户做点什么?能,就是 4xx。
幂等与重试:为什么 DELETE 能重试,POST 不能
"幂等"是数学词,落到接口上就一句话:同样的请求发 N 次,服务器的结果和发 1 次一样。
| 方法 | 幂等 | 连发两次的后果 | 能自动重试吗 |
|---|---|---|---|
GET |
是 | 读两次,什么都不变 | 能,随便重试 |
PUT |
是 | 整体覆盖成同一份,结果相同 | 能 |
PATCH |
不一定 | 若实现成"追加",会重复 | 看实现,谨慎 |
DELETE |
是 | 第一次删掉,第二次 404 | 能,但要把 404 当"已经是目标状态" |
POST |
否 | 两条一模一样的摘录 | 不能,除非有幂等键 |
DELETE 的细节值得说清:第二次返回 404,算不算失败?从"最终状态"看,你要的是"这条记录不存在",已经达成了。所以重试 DELETE 的正确写法是把 404 当成功(或者用 204 兜底)。
POST 为什么不能重试,看现场就懂:
用户在电梯里点"保存",网络卡了 3 秒,前端超时自动重试一次。电梯出来,两条一模一样的摘录。 更糟的是付款、下单、发邮件——重试一次就是两笔。
三条正路:
| 做法 | 怎么做 | 代价 |
|---|---|---|
| 前端禁用按钮 + 只发一次 | 提交中禁用,失败让用户自己点 | 最省事,用户多点一次 |
| 幂等键 | 请求头带 Idempotency-Key: <uuid>,服务端记住 24 小时 |
服务端要存键,实现成本中等 |
| 服务端去重 | 同用户 + 同标题 + 同正文,5 分钟内视为同一条 | 会误杀"真的想存两遍"的场景 |
本书的「读到」用第一条:表单提交期间按钮禁用。这是最诚实的选择——在没能力做幂等键之前,不要假装可以安全重试。
错误结构要统一:让前端只写一次解析
真实项目里长这样:
| 场景 | 有的接口返回 | 前端要写 |
|---|---|---|
| 校验失败 | {"detail": [{"loc": ["body","title"], "msg": "..."}]} |
解析数组、拼字段名 |
| 业务失败 | {"message": "标题重复"} |
读 message |
| 崩了 | 一整页 HTML 的 500 错误页 | 只能显示"未知错误" |
三种形状,前端要写三套解析,还要处理"HTML 不是 JSON"的 SyntaxError。所以本书从第 5 章起就固定一个形状:
{
"error": {
"code": "validation_error",
"message": "请求数据未通过校验",
"fields": [{"field": "title", "message": "String should have at least 1 character"}]
}
}
| 字段 | 给谁看 | 规则 |
|---|---|---|
code |
程序 | 稳定的英文短横线串,永远不要翻译、不要改;前端靠它做分支 |
message |
人 | 一句话,可以改,可以被翻译 |
fields |
表单 | 只在字段级错误时出现,field 用请求里的原始名 |
request_id |
排障 | 只在 500 出现,用户报错时念给你听(5.6 实现) |
code 与 message 分开是硬要求:程序不读人话。 你哪天把"摘录不存在"改成"这条记录找不到了",前端的分支不应该崩。
动手之前:把契约写下来
本书的契约(全书不再变,卷 6 换数据库也不变):
| 方法 | 路径 | 成功 | 失败 |
|---|---|---|---|
GET |
/api/notes |
200 + 数组 |
— |
POST |
/api/notes |
201 + 单条 |
422 |
GET |
/api/notes/{id} |
200 + 单条 |
404 |
PATCH |
/api/notes/{id} |
200 + 单条 |
404 / 422 |
DELETE |
/api/notes/{id} |
204 无体 |
404 |
单条对象的字段:id(整数)、title、content、source_url(可为 null)、created_at(ISO 8601 字符串)。注意是 source_url 不是 sourceUrl——卷 4 的 JSON 文件用的是驼峰,这一卷开始统一改成下划线,与数据库列名一致。这个改动会在 5.8 让你踩一次坑,先记住。
5.1.3 动手:用手写 curl 调一次,再把响应读一遍
curl 是"手工发 HTTP 请求"的工具,Windows 10 以后自带。先要一个公开的只读资源,example.com 是专门留给示例的域名,稳定、不涉隐私。
curl -i https://example.com
形如:
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
...
<!doctype html><html><head><title>Example Domain</title>...
逐段读:
| 你看到的 | 属于四要素的哪一项 | 说明 |
|---|---|---|
HTTP/1.1 200 OK |
状态行 | 协议版本、状态码、原因短语;原因短语只是给人看的,程序只认数字 |
Content-Type: text/html; charset=utf-8 |
头 | 告诉客户端"这是 HTML,按 UTF-8 解码" |
Transfer-Encoding: chunked |
头 | 这个响应没有 Content-Length,长度边发边算(5.2 详讲) |
| 空行之后 | 体 | 真正的内容 |
再做三次对照实验,每一次都只改一个变量:
# 1. 换成不存在的路径,看 4xx 是谁的问题
curl -i https://example.com/definitely-missing
# 2. 告诉服务器"我想要 JSON",看它理不理你
curl -i -H "Accept: application/json" https://example.com
# 3. 只取头,不下载体(排查时最常用)
curl -I https://example.com
第 2 条的结果很值得注意:它还是返回 HTML。因为 Accept 是"偏好",不是"命令",服务器有权忽略。这解释了一个常见困惑——"我明明写了要 JSON"不等于"我就会拿到 JSON"。真正决定返回什么的是服务端的实现,Accept 只是协商。
第 1 条你会拿到 404。请记住这个手感:只要能看到三位数状态码,请求就已经到达服务器了,问题不在网络(卷 0 第 3 章那张六段图)。
最后,把这次的观察写成一句话,填进你自己的契约笔记:
GET /api/notes成功时返回200,体是 JSON 数组,Content-Type必须是application/json;数组里每条有 5 个字段。
5.1.4 三个坑
坑一:用 GET 做写操作
症状:某天发现数据莫名少了几条,日志里全是 GET /api/notes/delete?id=7,来源是某个"网页预览"服务或浏览器预取。
成因:浏览器、爬虫、聊天软件的链接预览、安全扫描器都会主动 GET 链接。它们假设 GET 是安全的——这是整个互联网的前提。你一旦让 GET 有副作用,就等于把删除按钮交给了所有路过的机器人。
修法:写操作只用 POST / PATCH / DELETE。已经写成 GET 的,立刻改,并在 Nginx 或应用层拒绝对写路径的 GET(卷 7 会配)。
坑二:业务失败返回 500
症状:用户重复提交同一标题,页面显示"服务器内部错误,请稍后重试",然后他真的就一直重试。
成因:代码里 raise Exception("标题重复"),被框架兜成 500。500 的语义是"我坏了",用户和监控都会当成故障——你的告警系统半夜会把你叫醒,而其实只是有人手抖。
修法:业务规则不满足,返回 409(状态冲突)或 422(字段不合法),错误体里写清"哪个字段、为什么"。判断口诀:用户看完这句话能改点什么 → 4xx;只能等 → 5xx。
坑三:字段名前后端各叫一套
症状:列表页每条都显示"无标题",新增却能成功。打开 Network 看响应:[{"id":1,"title":"闭包",...}],而前端读的是 note.name。
成因:契约里没写字段名,或者写了但没人对照。JSON 不像编译型语言会报错,读不存在的字段只得到 undefined,undefined 渲染成空字符串,页面"看起来只是没数据"。
修法:三步。① 契约里把字段名写成表格(本章 5.1.2 末尾那张);② 后端用响应模型裁剪字段(5.5 的 response_model),多出来的字段根本发不出去;③ 前端在数据层做一次映射,只在一个文件里出现字段名(5.8 的 lib/api.js)。
本章验收
- 能默写「读到」五个端点的方法、路径、成功状态码
- 能说出 401 与 403、404 与 422 的分界,并各举一个「读到」里的例子
- 能解释 DELETE 重试为什么安全、POST 重试为什么会多一条
- 用
curl -i拿到过一次完整响应,并逐行指出四要素 - 契约里的单条字段名(含
source_url的下划线写法)能默写出来
自测
Q1:前端说"接口 500 了",你打开后端日志发现是 KeyError: 'sourceUrl'。这算谁的问题?
看答案
算实现方(后端)的问题,但要分两层看。表层是后端代码读了一个不存在的键——请求里传的是 `source_url`,代码却按 `sourceUrl` 取。深层是契约没落地:如果后端用 Pydantic 模型接收,缺字段会在入口就变成 422 并指明字段名,而不是在业务逻辑里抛 KeyError 变成 500。修法是"把校验前移到入口",而不是在出错的这行加个 `get()` 兜底——兜底只会把错误藏起来,让前端继续发错字段。Q2:为什么 PUT 幂等,而 PATCH 不一定?
看答案
PUT 的语义是"用我给的这份完整表示替换掉原资源",同一份内容替换两次,结果完全一样。PATCH 的语义是"按我给的这组指令修改",指令本身可能带增量含义,比如 `{"view_count": "+1"}` 或者"在数组末尾追加一项",执行两次结果就不同。所以 PATCH 是否幂等取决于你把它实现成"设值"还是"改值"。本书的 PATCH 只做设值(字段覆盖),因此可以安全重试。Q3:你要给「读到」加一个"按标签筛选",路径该怎么设计?为什么不是 /api/getNotesByTag?
看答案
设计成 `GET /api/notes?tag=js`。理由有三条:① 筛选是同一个集合的不同视图,不是新资源,造新路径会让路径数量随筛选项组合爆炸;② 查询串天然支持组合与分页(`?tag=js&page=2`),而路径参数会逼你定义优先级;③ 缓存和日志都按"路径 + 查询串"工作,`/api/notes` 的命中率统计才有意义。带动词的路径还会诱导你为每个动词各写一套错误处理,最后无法统一。下一步
契约有了,但你现在只会"看结果",不会"看过程"。下一章把一次请求拆成一行一行的文本,让你在 curl -v 和浏览器 F12 里看到同一件事。