手搓一个 HTTP 服务
本合集目录
本章目录
单册说明:本文件是卷 5 的第 4 章,可独立阅读。前置:5.3(虚拟环境)。本章不用任何框架,用标准库写一个能增能查的服务,目的是让你看清"框架到底替我们做了什么"。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 5 · 后端与 API(第 4 / 8 章) |
| 前置章节 | 5.3 Python 与虚拟环境 |
| 本章产出 | 一个五十多行、能跑通「读到」三个接口的服务 + 一份"框架职责清单" |
| 对应代码 | backend/scratch/server.py(临时实验文件,第 5 章删掉) |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能说出至少五件"框架替你做了、但你手写时漏了"的事 |
5.4.1 一句话结论:能跑不等于能用,中间隔着一整套工程
先看一个现象。你在本机起了这个服务,自己点了几下,一切正常。发给同事试用,他说"点保存要等好几秒,而且我点的时候别人就打不开了"。
原因不在你的业务代码,而在这行:
HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()
HTTPServer 是单线程的:一次只处理一个连接,处理完才接下一个。一个人上传大段摘录,所有人排队。这不是 bug,是这个类的设计定位——它面向"临时共享文件",不面向多用户服务。
所以这一章的目标不是"学会写服务器",而是攒出一张清单:这些东西我不会想自己再写第二遍。
5.4.2 原理与方法
一个请求进来,发生了什么
浏览器/curl
│ TCP 连接建立
▼
HTTPServer → 接受连接、交给 Handler
▼
BaseHTTPRequestHandler → 读第一行(方法 + 路径 + 版本)、读头、按 Content-Length 准备读体
▼
你的 do_GET / do_POST → 业务逻辑(路由判断、解析、校验、序列化都在这)
▼
wfile.write(...) → 你手动写状态行、头、空行、体
注意最后一步:连"响应长什么样"都要你自己拼。 框架把这四步全包了,所以你在 FastAPI 里只写一个函数。
代码里的五个 self. 是什么
BaseHTTPRequestHandler 把一次连接的状态都挂在 self 上。看懂这五个属性,这段代码就没有黑箱了:
| 属性 | 是什么 | 用错会怎样 |
|---|---|---|
self.command |
方法名,如 GET |
不读它就只能靠 do_* 方法名区分 |
self.path |
原始目标:路径 + 查询串 | 直接比较字符串,带 ? 就匹配不上(坑一) |
self.headers |
一个大小写不敏感的字典 | 用 self.headers["content-length"] 也取得到 |
self.rfile |
读请求体的文件对象 | 不带长度 read() 会一直等(坑二) |
self.wfile |
写响应的文件对象 | 写完不 flush 不会立刻发出去 |
send_response 与 send_header 只是往 wfile 里写文本,end_headers() 补上那个空行。记住"空行分隔头和体"这条规则,你就能理解为什么忘了 end_headers() 时客户端会一直等——它还在找那个空行。
框架替你做的八件事
| # | 事情 | 手写时你要做什么 | 漏了会怎样 |
|---|---|---|---|
| 1 | 路由匹配 | 自己 if path == ...,还要处理查询串、尾斜杠 |
/api/notes?tag=js 匹配不上,404 |
| 2 | 请求体解析 | 读 Content-Length、读字节、按类型解析 JSON/表单 |
读不到体,或把表单当 JSON |
| 3 | 参数提取 | 从路径里切出 id 并转 int |
int("abc") 抛异常 → 500 |
| 4 | 校验 | 手写一堆 if not title: return 422 |
漏一个字段就写进"库"里 |
| 5 | 序列化 | json.dumps(..., ensure_ascii=False) + 编码 |
中文变 \u95ed\u5305,或字节数算错 |
| 6 | 错误体 | 每个分支手写一份 | 三种形状,前端写三套解析(5.1 讲过) |
| 7 | 文档 | 手写一份 README,还要跟代码同步 | 文档永远落后于代码 |
| 8 | 并发 | 自己换 ThreadingHTTPServer 或上多进程 |
一个人慢,所有人等 |
第 8 条我实测过。同一个 2 秒的慢接口,两个请求同时发:
| 实现 | 两个并发请求的总耗时 | 说明 |
|---|---|---|
HTTPServer(本章代码) |
约 4.1 秒 | 串行,第二个等第一个做完 |
uvicorn + FastAPI(下一章) |
约 2.3 秒 | 并行,两个几乎同时开始 |
(本机 Windows,两个 curl 同时发起,各 2 秒延迟。数字随机器变,比例关系不变。)这就是"框架替你做了并发"的具体含义。
测量方法很简单,你也可以自己复现:给两个服务各加一个 sleep(2) 的端点,然后在终端里同时发两个请求并计时。
time (curl -s http://127.0.0.1:8000/slow & curl -s http://127.0.0.1:8000/slow & wait)
& 是"放到后台跑",wait 是"等两个都结束"。如果总耗时接近 2 秒,说明并行;接近 4 秒,说明串行。 这个手法以后排查"服务是不是被卡住了"也用得上。
三种请求体,解析方式完全不同
Content-Type 决定了"体里的字节怎么读成数据结构"。手写服务时,这是第二件让你想放弃的事:
| 类型 | 体长什么样 | 怎么解析 | 手写的难点 |
|---|---|---|---|
application/json |
{"title":"闭包"} |
json.loads |
还要处理空体、非法 JSON、编码 |
application/x-www-form-urlencoded |
title=%E9%97%AD%E5%8C%85&content=x |
urllib.parse.parse_qs |
中文要 URL 解码,数组要按规则展开 |
multipart/form-data |
一串 ----boundary 分段,含文件名与二进制 |
自己按 boundary 切 | 边界处理、大文件流式读、临时文件清理 |
第三种就是"上传文件"用的格式,也是自定义解析器最容易出安全漏洞的地方(路径穿越、超长文件名、内存打爆)。FastAPI 处理它只需要一个参数类型标注,因为底层有专门的库在做。
本章的代码只认 JSON,其余两种直接当非法输入。这是有意的裁剪:先把一条路走通,再看清剩下的路有多长。
返回 1MB 和返回 1GB,是两件事
send_json() 里有一句 body = json.dumps(...).encode()。这意味着整个响应先完整地待在内存里。数据小的时候没问题,数据一大就出事:
| 数据量 | 现在这段代码 | 正确做法 |
|---|---|---|
| 几十 KB | 无所谓 | —— |
| 几十 MB | 内存飙升,多个并发直接 OOM | 边读边发(流式响应) |
| 1 GB 的文件 | 直接把进程撑死 | 用 sendfile 或分块写 wfile |
浏览器下载大文件时用的就是后者:服务器一边读磁盘一边往 socket 写,内存占用恒定。框架通常提供 StreamingResponse 或静态文件中间件来做这件事,手写则要自己处理"客户端中途断开"的情况——写一半对方走了,你得停止读文件,否则白干还占资源。
这条不在本章的动手范围内,但你得知道它的存在:"能返回"和"能返回大数据"是两个能力。
为什么它绝对不能上线
| 缺陷 | 具体表现 | 上线后的后果 |
|---|---|---|
| 只支持 HTTP/1.0 | 响应第一行是 HTTP/1.0 200 OK(实测) |
每个请求新建连接,没有 keep-alive,慢 |
| 单线程 | 上面的 4.1 秒 | 一个慢请求卡住所有人 |
| 没有超时 | 客户端不发完,线程就一直等 | 几个"半开连接"就能把服务占满 |
| 没有 TLS | 只能 http:// |
密码、令牌明文过网 |
| 没有请求体上限 | Content-Length 写 10GB 就真去读 |
一个请求打爆内存 |
| 目录穿越风险 | 自己拼文件路径时容易漏 .. |
读到系统文件 |
| 日志只有一个格式 | 只有方法、路径、状态 | 出事查不到耗时、来源、请求 id |
这份清单不是为了吓你,是为了让你在下一章看到 @app.get("/api/notes") 时知道这一行背后站着八件事。
5.4.3 动手:五十多行跑通三个接口
新建 backend/scratch/server.py(scratch 是"草稿"的意思,第 5 章会删掉这个目录):
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
NOTES = [{"id": 1, "title": "闭包是函数和它的词法环境", "content": "函数记住它被定义时所在的作用域。",
"source_url": None, "created_at": "2026-11-01T08:00:00Z"}]
NEXT_ID = 2
class Handler(BaseHTTPRequestHandler):
def send_json(self, status, payload):
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
self.send_response(status)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def fail(self, status, code, message):
self.send_json(status, {"error": {"code": code, "message": message}})
def do_GET(self):
path = self.path.split("?")[0]
if path == "/api/notes":
return self.send_json(200, NOTES)
prefix = "/api/notes/"
if path.startswith(prefix) and path[len(prefix):].isdigit():
note_id = int(path[len(prefix):])
for note in NOTES:
if note["id"] == note_id:
return self.send_json(200, note)
return self.fail(404, "not_found", "摘录不存在")
return self.fail(404, "not_found", "路径不存在")
def do_POST(self):
global NEXT_ID
if self.path != "/api/notes":
return self.fail(404, "not_found", "路径不存在")
raw = self.rfile.read(int(self.headers.get("Content-Length") or 0))
try:
data = json.loads(raw or b"{}")
except json.JSONDecodeError:
return self.fail(400, "bad_json", "请求体不是合法 JSON")
if not (data.get("title") or "").strip():
return self.fail(422, "invalid", "title 不能为空")
note = {"id": NEXT_ID, "title": data["title"], "content": data.get("content") or "",
"source_url": data.get("source_url"), "created_at": "2026-11-17T09:00:00Z"}
NEXT_ID += 1
NOTES.append(note)
return self.send_json(201, note)
def log_message(self, fmt, *args):
print(f"[{self.log_date_time_string()}] {self.command} {self.path} -> {args[1]}", flush=True)
if __name__ == "__main__":
HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()
跑起来,然后发三个请求:
python scratch/server.py # 另开一个终端
curl -i http://127.0.0.1:8000/api/notes
curl -X POST http://127.0.0.1:8000/api/notes \
-H "Content-Type: application/json" \
-d '{"title":"盒模型","content":"width 只算内容区"}'
curl http://127.0.0.1:8000/api/notes/99
实测结果(本机):
HTTP/1.0 200 OK
Server: BaseHTTP/0.6 Python/3.13.14
Content-Type: application/json; charset=utf-8
Content-Length: 181
{"id": 2, "title": "盒模型", "content": "width 只算内容区", "source_url": null, "created_at": "2026-11-17T09:00:00Z"}
{"error": {"code": "not_found", "message": "摘录不存在"}}
服务端日志(同一时间戳是我连发的):
[17/Nov/2026 02:21:57] GET /api/notes -> 200
[17/Nov/2026 02:21:57] POST /api/notes -> 201
[17/Nov/2026 02:21:58] GET /api/notes/99 -> 404
[17/Nov/2026 02:21:58] GET /api/notes?tag=js -> 200
三处细节值得多看两眼:
| 观察 | 含义 |
|---|---|
HTTP/1.0 200 OK |
标准库默认 HTTP/1.0,没有持久连接 |
Content-Length: 181 |
中文的字节数,不是字符数(5.2 验证过) |
第四条带 ?tag=js 也返回 200 |
因为代码里有 self.path.split("?")[0],删掉这行就是 404 |
最后一条是本章最值钱的一行代码。它看着像废话,实际是"路由匹配"这个抽象第一次露面——框架用一个装饰器就做的事,手写时要记住"路径里可能带查询串"。 你会忘,我也忘过。
如果想临时给同事看一眼
把监听地址改成 0.0.0.0:
HTTPServer(("0.0.0.0", 8000), Handler).serve_forever()
然后查自己的局域网 IP:
ipconfig # Windows,看"IPv4 地址"
ifconfig # macOS / Linux,看 en0 或 eth0
让同事在同一个 WiFi 下访问 http://192.168.x.x:8000/api/notes。两件事会发生:
| 现象 | 原因 |
|---|---|
| Windows 弹窗问"是否允许访问网络" | 系统防火墙在拦;选"允许专用网络"才通 |
| 手机能打开,同事打不开 | 不在同一网段,或公司 WiFi 开了"客户端隔离" |
这正好是卷 0 那张"本机能连、外面连不上"对照表的反面:那次是因为绑了回环,这次是因为绑了所有网卡。 两个方向都亲手试一次,这张表就长在你身上了。
看完就改回 127.0.0.1。一个没有任何认证的接口暴露在局域网里,等于把删除按钮递给整个办公室。
5.4.4 三个坑
坑一:拿 self.path 直接比字符串
症状:列表页第一次打开正常,点"按标签筛选"就 404。日志里明明写着 GET /api/notes?tag=js -> 404。
成因:self.path 是路径 + 查询串的原始串。"/api/notes?tag=js" == "/api/notes" 为假。框架会把它拆成 path 与 query 两部分再匹配,手写时没有这层。
修法:比较前先切掉查询串(本章代码里那行 split("?")[0]);需要参数时再单独解析 parse_qs。更根本的修法是别自己写路由——这正是下一章要做的事。
坑二:读请求体时不带长度
症状:curl -X POST ... 发出去就不返回,等到超时;服务端日志里连一行都没打。
成因:写成了 raw = self.rfile.read()。不带参数的 read() 语义是"读到连接结束",而客户端在等你的响应,不会关连接——双方互等,直到某一方超时。这个 bug 在浏览器里表现为"请求一直 pending"。
修法:一定按声明长度读:self.rfile.read(int(self.headers["Content-Length"]))。同时要防御两件事:① 头可能没有,用 or 0 兜底;② 长度可能巨大(有人故意写 10GB),要在读之前设上限并拒绝。
坑三:只监听 127.0.0.1,别人永远连不上
症状:本机 curl 正常,手机连同一个 WiFi 打不开,同事也打不开;telnet 你的 IP 直接拒绝。
成因:("127.0.0.1", 8000) 只绑定回环地址,只有本机能连。这不是防火墙问题,是服务根本没在那个网卡上监听。
修法:需要被外部访问时绑 0.0.0.0(所有网卡)。但这只是"能连上",不等于"可以上线"——把一个单线程无 TLS 的服务开到公网,几分钟内就会收到扫描流量。开发期用 127.0.0.1 更安全,需要联调时再临时放开,用完改回去。
本章验收
- 服务能起,三个
curl分别拿到200/201/404 - 能指着代码说出"路由匹配、体解析、校验、序列化"各在哪几行
- 说得出至少五件框架替你做的事,以及漏掉它们的后果
- 亲手删掉
split("?")[0]那一行,看到带查询串的请求变成 404,再改回来 - 能解释"单线程"为什么会让人排队(不是慢,是等)
自测
Q1:这个服务为什么不能直接放到公网?说出三条你最有把握的理由。
看答案
① 单线程,一个慢请求阻塞所有人,等于自带一个拒绝服务入口;② 没有 TLS,所有内容明文传输;③ 没有请求体大小上限和超时,几个半开连接就能占满进程。还有两条同样致命:没有统一的错误体与日志字段,出事无法定位;自己拼的路由和文件路径容易留下穿越漏洞。注意"能跑通"和"能抗住"是两件独立的事,前者只需要正确的逻辑,后者需要一整套边界控制。Q2:为什么 curl 在 -d 之后一定要配 -H "Content-Type: application/json"?如果漏了,这个手写服务会怎样?
看答案
漏了的话 `curl` 会发 `application/x-www-form-urlencoded`,体是 `title=x&content=y` 这种形式。本章的服务不检查 `Content-Type`,直接 `json.loads`,于是抛 `JSONDecodeError`,返回 400 `bad_json`。有意思的是它"碰巧"给出了一个还算合理的错误——但换成 FastAPI 就会得到 422,因为框架会先按声明的类型解析。这个对比说明:不检查类型的代码不是"更宽容",而是"把错误延后到更难解释的地方"。Q3:把 HTTPServer 换成 ThreadingHTTPServer 就能上线了吗?
看答案
不能,它只解决了并发里的"阻塞"一项。仍然缺 TLS、超时、请求体上限、统一错误体、参数校验、接口文档;而且多线程共享同一份 `NOTES` 列表时,`NEXT_ID += 1` 这种操作会出现竞态,两个人同时保存可能拿到同一个 id。要补齐这些,等于重写一个框架——这就是下一章直接用 FastAPI 的理由:不是它"高级",是它把这些边界都做完了。下一步
手写一遍之后,再看框架的装饰器就不神秘了。下一章用 FastAPI 重写同样的五个端点,并把"校验"和"文档"这两件手写时最痛的事交给类型系统。