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

手搓一个 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 重写同样的五个端点,并把"校验"和"文档"这两件手写时最痛的事交给类型系统。

→ 卷5-05-FastAPI路由校验文档.md