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

导读

本合集目录
本章目录

本卷目标:把「读到」从"只有页面"变成"有脑子、能存能读"。 读完这一卷,你的前端不再是读本地 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 手工要一次数据,然后把"接口是一份契约"这件事说透——这份契约后面会被你违反至少三次,早一点知道自己违反了,比上线后才发现便宜得多。

→ 卷5-01-API是什么.md