跳到正文
零到全栈 · 卷 5 · 后端与 API

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 里看到同一件事。

→ 卷5-02-HTTP报文解剖.md