导读
本合集目录
本章目录
本卷目标:把「读到」从"只有页面"变成"有脑子、能存能读"。 读完这一卷,你的前端不再是读本地 JSON 文件,而是向一个自己写的接口要数据;你能用
curl手工调通每一个端点,能看懂 422 和 500 的区别,能在浏览器拦住请求时说出原因。数据仍然存在一个 JSON 文件里——这是本卷刻意的临时方案,卷 6 才换成 SQLite。
本文件是卷 5 的导航页。 正式内容在 8 个分册里,每册可单独打开阅读。
一、本卷信息
| 项 | 内容 |
|---|---|
| 卷号 / 卷名 | 卷 5 · 后端与 API(接口卷) |
| 章数 | 8 章 |
| 组织方式 | 一章一个文件,每章自带前置说明、正文、动手、验收 |
| 主题范围 | ① 接口即契约 ② HTTP 报文解剖 ③ Python 虚拟环境 ④ 手搓 HTTP 服务 ⑤ FastAPI 路由/校验/文档 ⑥ 错误处理与日志 ⑦ CORS 与预检 ⑧ 前后端联调收口 |
| 不涉及 | SQLite 与 SQL、用户与会话、越权防护(卷 6);Nginx、systemd、HTTPS(卷 7);测试与性能(卷 8) |
| 目标读者 | ① 按顺序读到这里的零基础读者 ② 会写页面但一调接口就卡住的人 ③ 会 Python 语法、没写过一个真正 API 的人 |
| 前置条件 | 卷 4 读完:会用 Next.js App Router,知道服务端组件与客户端组件的区别,lib/notes.js 数据层已就位 |
| 产出物 | 一个能跑的 FastAPI 服务(5 个端点 + 统一错误体 + 访问日志 + CORS)· 前端 data 层改为真接口 · 一份联调分诊表 |
| 随书代码 | backend/(第 3–7 章逐步长大:app/main.py、app/models.py、app/store.py、app/errors.py)· 前端只改 lib/api.js 与三个页面 |
| 验收口径 | 不看"读完了没有",只看能不能用 curl 复现一个 201、一个 422、一个 500,并各自说清是谁的问题 |
二、八章目录
| 章 | 文件 | 这一章给你什么 | 产出 |
|---|---|---|---|
| 1 | 卷5-01-API是什么.md | 契约、四要素、REST 命名、状态码分工、幂等与重试 | 一份写在纸上的接口契约 + 一次手工调通的请求 |
| 2 | 卷5-02-HTTP报文解剖.md | 请求行/头/体,响应行/头/体,八个关键头 | 一份逐行标注过的真实报文 |
| 3 | 卷5-03-Python与虚拟环境.md | venv 原理、pip、requirements、"装不上"的三类原因 | 一个隔离的 .venv + requirements.txt |
| 4 | 卷5-04-手搓一个HTTP服务.md | 五十多行标准库服务,看清框架替你做了什么 | 一个能跑但绝不能上线的服务 |
| 5 | 卷5-05-FastAPI路由校验文档.md | 类型即校验、Pydantic v2、自动文档、Depends | /api/notes 的 5 个端点 + /docs |
| 6 | 卷5-06-错误处理与日志.md | 异常分层、统一错误体、request_id、日志字段 | 一套错误体 + 一条可追溯的日志 |
| 7 | 卷5-07-CORS与预检.md | 同源三要素、简单请求与预检、凭据、开发代理 | 先复现报错,再修好 |
| 8 | 卷5-08-联调收口.md | baseURL 环境变量、分诊表、契约对齐、上线前检查 | 前端列表从真接口取数,新增能持久化 |
章与章是强顺序的:5.1 的契约是后面七章一直在对照的那张纸;5.2 不看懂报文,5.7 的预检你只能靠猜;5.3 的环境没弄好,5.5 的第一步就会卡在 ModuleNotFoundError;5.6 的错误体不做统一,5.8 的分诊表就没有"抓手"。
三、阅读约定
| 记号 | 含义 |
|---|---|
代码字体 |
命令、字段名、报错原文;可直接复制 |
| 粗体 | 关键判断,值得单独记下来 |
| ⚠️ | 高频翻车点,跳过会浪费你两小时 |
| 表格 | 凡是要对比、要决策的东西都在表里 |
| 「三个坑」 | 每条都是"症状 → 成因 → 修法",按这个顺序读 |
| 形如 | 标注在输出块前,表示结构真实、具体数字会随环境变化 |
本卷后端代码是 Python 3.11+ 与 FastAPI,模型一律 Pydantic v2 写法(model_dump(),不是 dict())。你在网上会看到大量 class Config 和 .dict() 的旧示例,它们在新版本里会警告甚至报错——遇到就换成正文里的写法。
⚠️ 本卷的数据存储是临时的。 所有摘录存在 backend/data/notes.json 里,进程重启不丢,但并发写会互相覆盖、没有索引、没有事务。第 6 章开头会用一整节说明"为什么这个方案到多用户就必须换掉",然后卷 6 换成 SQLite。先跑通,再换对——这是本卷刻意的顺序。
四、本卷与前后各卷的关系
卷4 框架 组件 / 路由 / 服务端取数 —— 数据是本地 JSON
└ 卷5 后端(本卷) HTTP / FastAPI / 联调 —— 数据在服务里,但只有一份、没有用户
└ 卷6 数据与状态 SQLite / 会话 / 多用户 —— 每个人只看自己的
└ 卷7 上线运维 域名 / HTTPS / systemd / Nginx —— 真正属于互联网
这一卷有一个容易被误解的地方:前后端分离不是为了"显得专业",是因为它们的变化速度不一样。 界面一天改三次,数据规则一周改一次;混在一起时,改标题颜色要重启整个服务。分开之后,你才能在这一卷里"后端不动,前端换三版"。
五、现在开始
先读第 1 章。它一行代码都不写后端,只让你用 curl 手工要一次数据,然后把"接口是一份契约"这件事说透——这份契约后面会被你违反至少三次,早一点知道自己违反了,比上线后才发现便宜得多。