外观
15 - 一个 Python 接口如何处理请求:HTTP、WSGI/ASGI 与应用边界
摘要
查询函数能运行,不代表它已经成为可靠的 HTTP 服务。本文从日志查询接口出发,沿请求解析、参数校验和响应发送解释 WSGI 与 ASGI 的职责,再用本地 HTTP 请求和内存事件实验看清协议边界。
版本范围:WSGI 依据 PEP 3333,ASGI 使用应用接口 3.0 与 HTTP 子规范 2.5。主示例使用标准库本地WSGI与内存ASGI协议驱动;补充示例通过真实FastAPI/uvicorn处理HTTP并验证lifespan。均只监听loopback,准确依赖版本与各轮执行范围见工程实践与验收手册。
1. 场景:函数返回字典,浏览器为何没有得到 JSON
教学场景里,你已经写好 query_logs(limit),返回统计字典。把它挂到 HTTP 入口后,出现三个问题:客户端收到服务器错误,数量参数仍是文本,访问量略增时请求开始排队。一个业务函数的正确性,只覆盖了请求链上的一段。
先把同一份结果沿请求链走一遍:业务函数给出字典,序列化产生文本,编码产生字节,应用接口描述状态和响应体,服务器再处理网络发送。每层只保证自己的输出能交给下一层;字典正确不代表原始WSGI会替你转JSON,send完成也不代表客户端已经接收。本篇用这条交接链解释参数错误、响应错误和等待,随后让本地HTTP与内存事件各自验证它们覆盖的边界。
先用标准库wsgiref完成一次真实本地HTTP交换,再用receive/send直接观察ASGI事件,最后将同一limit规则迁移到FastAPI/uvicorn。变量一直是这条查询:输入怎么表示、业务何时可以开始、结果以什么类型交出、资源何时结束。框架替你封装其中一些步骤,实验则帮助你核对封装有没有改变契约。
2. HTTP 与 Python 应用接口不是同一协议
HTTP(Hypertext Transfer Protocol,超文本传输协议)描述客户端与服务器交换请求和响应的规则。以本篇 HTTP/1.1 教学请求为例,请求含方法 GET、路径、查询字符串及头。响应包含状态码、头与消息体。真实 HTTP 版本的传输与复用机制不同,应用不能根据这个例子推断所有版本使用相同连接处理。
WSGI(Web Server Gateway Interface,Web 服务器网关接口)与 ASGI(Asynchronous Server Gateway Interface,异步服务器网关接口)是 Python 服务器与应用之间的调用约定。它们不替代客户端看到的 HTTP,而是服务器解析网络协议后,怎样将信息交给 Python 应用,以及怎样取得应用输出。
server(应用服务器)负责监听、连接处理、协议解析和调度应用等;framework(框架)常负责路由、模型、依赖注入和错误处理。reverse proxy(反向代理)可能在更前面处理连接、路由或 TLS。组件可以组合或同进程,但分析责任时应该保留逻辑边界。
图表将在阅读到此处时加载…
这张链条没有规定一定使用进程、线程或协程调度。WSGI 服务器可以采用多进程或线程,ASGI 服务器通常通过事件循环调度异步应用。接口协议与服务器并发实现有联系,但不能简单等同为“WSGI 只能一个请求、ASGI 自动无限并发”。
3. WSGI 的一次调用如何构成响应
WSGI 应用接收 environ 和 start_response。environ 提供请求信息及输入流,例如 REQUEST_METHOD、PATH_INFO、QUERY_STRING 和 wsgi.input。它不是直接暴露原始 HTTP 请求的普通文本,也不是所有字段都已经变成业务需要的类型。
start_response 接收状态字符串和响应头列表。状态形如 "200 OK",头的名称与值按规范使用字符串。应用返回一个可迭代对象,它产出的消息体块必须是 bytes。返回 Python 字典、字符串或包含字符串的列表,都不满足消息体协议。PEP 3333明确规定应用可迭代结果与字节输出的边界。
因此 JSON 字典要先序列化为文本,再按编码变成字节。Content-Length 应是字节长度,不是中文字符串的字符数。两者混淆时,消息边界可能错误;若响应按未知长度流式发送,应让服务器按其协议能力处理,而不是编造长度。
start_response 的名字也容易误解。它设置响应状态与头,并不意味着所有数据已经送达客户端。返回的可迭代对象被服务器消费时才产生或发送消息体;中途错误可能发生在响应已经开始之后,无法随意改成全新的错误状态。处理流式响应时,异常与清理应覆盖整个消费生命周期。
如果返回对象带 close,服务器按 WSGI 约定负责调用它完成清理,包含请求提前结束的情况。应用仍需正确实现该清理,并避免在生成器闭包中无意长期保留数据库连接。第 11 篇的暂停与所有权模型,在响应流里直接适用。
4. ASGI 用 scope 与事件表达请求生命周期
ASGI 应用是异步可调用对象,接收 scope、receive、send。scope(作用域信息)描述连接或请求的上下文,本篇 HTTP scope 包含方法、路径和查询字符串;receive 获取入站事件,send 发送出站事件。这比同步返回一个可迭代响应更容易表达长连接与异步收发。
HTTP 应用先接收一个或多个 http.request 事件。事件含 body 字节与 more_body,后者为真表示后续还有内容。应用不能只读第一块就假设完整请求体,也不能无上限拼接所有块。客户端断开可由 http.disconnect 表示,具体观察时间取决于服务器与应用执行路径。
响应先发送 http.response.start,携带状态和字节形式的头,再发送一个或多个 http.response.body。最终消息体事件的 more_body 为假,表示该响应体结束。await send 提供异步等待机会,但不意味着客户端已经读完数据,也不是数据库事务的提交确认。
如果应用已完成发送,客户端却仍报告超时,需要继续追应用接口之外的传输与协议证据。分层网络排障方法提供这条后续路径:区分应用处理、连接和协议层的观察,不能把一次send返回当成端到端成功。
ASGI HTTP scope 的 query_string 是原始字节,而 path 是已解码的路径信息;原始路径可通过相应字段提供。不能把所有 scope 字段统一按同一种编码处理。ASGI HTTP 子规范逐项定义了字段类型、默认值和事件顺序。
本节的最小 ASGI 函数只处理 HTTP 类型,不实现 WebSocket 与 lifespan;后面的真实框架示例再验证启动和关闭。真实 ASGI 服务器可能使用 lifespan 管理应用启动和关闭,应用必须按所选协议支持情况处理。拿一个只接受 HTTP 的最小函数放到任意服务器,不能宣称已覆盖完整生命周期。
5. 完整最小实验:真实 WSGI 请求与内存 ASGI 响应
保存为 examples/15_http.py,执行:
powershell
python docs/python/examples/15_http.py完整代码如下,日志数据固定为教学摘要:
python
"""独立示例:本地 WSGI HTTP 请求与内存 ASGI 协议驱动。"""
import asyncio
import json
from collections import deque
from threading import Thread
from urllib.parse import parse_qs
from urllib.request import urlopen
from wsgiref.simple_server import make_server, WSGIRequestHandler
def response(query):
raw = parse_qs(query, keep_blank_values=True).get("limit", ["10"])
if len(raw) != 1:
return 400, {"error": "invalid limit"}
if len(raw[0]) > 3:
return 400, {"error": "limit out of range"}
if not raw[0].isascii() or not raw[0].isdecimal():
return 400, {"error": "invalid limit"}
if not 1 <= int(raw[0]) <= 100:
return 400, {"error": "limit out of range"}
return 200, {"limit": int(raw[0]), "errors": 2}
def wsgi_app(environ, start_response):
status, payload = response(environ.get("QUERY_STRING", ""))
body = json.dumps(payload, sort_keys=True).encode("utf-8")
phrase = "OK" if status == 200 else "Bad Request"
start_response(f"{status} {phrase}", [("Content-Type", "application/json"),
("Content-Length", str(len(body)))])
return [body] # WSGI 输出必须是 bytes,而非 str。
async def asgi_app(scope, receive, send):
if scope["type"] != "http":
raise ValueError("this example handles HTTP only")
try:
while True:
event = await receive()
if event["type"] == "http.disconnect":
return
if event["type"] == "http.request" and not event.get("more_body", False):
break
status, payload = response(scope["query_string"].decode("ascii"))
body = json.dumps(payload, sort_keys=True).encode("utf-8")
await send({"type": "http.response.start", "status": status,
"headers": [(b"content-type", b"application/json")]})
await send({"type": "http.response.body", "body": body, "more_body": False})
finally:
scope.setdefault("state", {})["closed"] = True
async def exercise_asgi():
messages = []
incoming = deque([
{"type": "http.request", "body": b"first", "more_body": True},
{"type": "http.request", "body": b"last", "more_body": False},
])
async def receive():
return incoming.popleft()
async def send(message):
messages.append(message)
scope = {"type": "http", "asgi": {"version": "3.0", "spec_version": "2.5"},
"http_version": "1.1", "method": "GET", "scheme": "http",
"path": "/", "raw_path": b"/", "query_string": b"limit=0",
"root_path": "", "headers": [], "server": ("127.0.0.1", 80),
"client": ("127.0.0.1", 12345)}
await asgi_app(scope, receive, send)
assert messages[0]["status"] == 400
assert messages[-1]["more_body"] is False
assert not incoming
assert scope["state"]["closed"]
print("ASGI:", messages[0]["status"], messages[-1]["body"].decode())
messages.clear()
incoming.append({"type": "http.disconnect"})
scope["state"]["closed"] = False
await asgi_app(scope, receive, send)
assert not messages and scope["state"]["closed"]
incoming.append({"type": "http.request", "body": b"", "more_body": False})
async def failed_send(message):
raise RuntimeError("injected send failure")
scope["state"]["closed"] = False
try:
await asgi_app(scope, receive, failed_send)
except RuntimeError as error:
assert str(error) == "injected send failure"
else:
raise AssertionError("send failure swallowed")
assert scope["state"]["closed"]
print("ASGI disconnect/send failure cleanup: passed")
class QuietHandler(WSGIRequestHandler):
def setup(self):
super().setup()
self.connection.settimeout(3) # 已接收连接的读写也必须有界。
def log_message(self, format, *args):
pass # 示例不打印时间等非确定性日志。
if __name__ == "__main__":
with make_server("127.0.0.1", 0, wsgi_app, handler_class=QuietHandler) as server:
server.timeout = 3 # 客户端未发出请求时,handle_request 也会退出。
worker = Thread(target=server.handle_request)
worker.start()
try:
with urlopen(f"http://127.0.0.1:{server.server_port}/?limit=3", timeout=3) as result:
body = result.read().decode("utf-8")
assert result.status == 200
print("WSGI:", result.status, body)
finally:
worker.join(timeout=7)
if worker.is_alive():
raise RuntimeError("demo server did not stop")
asyncio.run(exercise_asgi())运行前先追踪 limit=3 与 limit=0:前者经过文本校验变成整数3,字典编码为bytes后交给WSGI,预期状态200、JSON为{"errors": 2, "limit": 3};后者通过ASGI请求结束事件进入范围校验,得到400与范围错误。ASGI第一块more_body为真时还不能开始响应,最后一块为假才跨过消费边界。端口由系统分配;WSGI正常路径只有一次HTTP交换,不把端口或日志顺序当作固定结果。
这份 ASGI 实验验证应用生成的消息顺序与载荷,不验证真实服务器对 HTTP、背压或断开的实现。WSGI 部分则经过了本地套接字与 HTTP 客户端,证据范围更广,但不覆盖 TLS、代理、生产负载和完整服务器故障。实验为等待请求及已接收连接的读写分别设置超时;join(timeout) 仅限制等待线程的时间,不会终止线程,所以还要确认它已经退出。这些小规模保护不等于生产服务器的总截止时间或完整慢客户端防护。
6. 反例与正例:消息体类型与重复参数
现在保持业务字典不变,只改交接类型。return [json.dumps(payload)]交出str,原始WSGI要求bytes,因此错误发生在应用到服务器的边界,不是查询算法。return payload更早偏离契约:迭代字典得到键,无法成为预期JSON。正例明确序列化、编码并按字节计算长度;框架自动序列化是额外实现,必须按它的接口验证,不能反推原始WSGI也有同样行为。
参数反例是 int(parse_qs(query)["limit"][0]),既没有缺省与空值策略,也默默选择重复参数的第一项。攻击者或误用客户端发送 limit=1&limit=100 时,前端、代理和应用若选择方式不同,会产生不一致。正例拒绝重复数量参数,限制字符、长度与范围。
parse_qs 默认对空值的处理也需要明确,所以示例使用 keep_blank_values=True,确保 limit= 被当成非法空输入,而不是悄悄消失后使用默认值。本文只关注 limit;真实服务还应限制查询字段总数和 URL 长度,不让解析阶段成为无界资源消耗。
错误输入对应 400,内部异常通常对应服务端错误,但对外响应不应直接携带堆栈、SQL 或凭据。结构化日志应保存请求标识、异常类别和处理阶段,客户端获得稳定错误码或简洁说明。参数校验错误与数据库不可用不能全部返回同一“查询失败”。
7. 为什么 async 不自动提高接口性能
ASGI 允许应用在等待 I/O 时让出执行机会,前提是等待通过可协作的异步接口进行。异步函数中调用同步数据库客户端或 time.sleep,仍会阻塞事件循环所在执行路径;把函数声明换成 async def 没有改变调用的实际性质。
WSGI 的同步应用可以通过服务器的线程或进程并发处理等待,成本和容量限制与 ASGI 不同。ASGI 不等于所有业务更快,WSGI 也不等于无法承受并发。要观察到达速率、服务时间、队列、连接池和 CPU,再按瓶颈选择模型。
请求体、响应体和任务也要有界。异步能容纳更多等待任务,但每个任务保存上下文、缓冲与连接状态,无限接受请求仍会耗尽资源。server timeout(服务器超时)、业务总截止时间和下游调用超时属于不同边界,需要协调而不能任意叠加。
把交接链用于写接口,会多出一个重要分叉:数据库已经提交,网络发送却失败。此时断开只改变响应路径,不能倒转提交;尚未结束的下游调用也可能继续持有资源。数据库事务沿同一失败时机区分回滚与幂等,Task取消则追踪等待者退出后底层工作是否结束。分别核对这两步,才能决定可否重试。
8. 部署与线上排查的责任边界
wsgiref.simple_server 是用于展示规范和本地测试的参考实现,不应拿本篇单请求实验作为正式服务配置。标准库 wsgiref 文档介绍它提供的参考工具;生产部署要选择适合的服务器并验证并发、超时、关闭、日志和协议能力。
启动成功也不代表链条正确。健康检查能返回,只证明某条路径有响应;业务数据库不可用或查询排队时,健康接口可能仍正常。应区分进程存活、服务准备好和核心依赖状态,避免用同一个检查承担所有判定。
代理头是另一易踩点。原始客户端 IP、协议与 Host 可能由前置代理传递,但应用只能信任来自已知代理链的约定,不能直接接受任意客户端提供的转发头。相关行为由服务器与框架配置决定,本文不编造默认信任策略。
排障时给请求链每个等待段建立证据。客户端连接耗时、服务器接收时点、应用开始执行、连接池等待和响应发送是不同时间。只有总延迟无法区分排队与业务计算,看到异常堆栈也不保证知道最初卡在哪一段。
8.1 用同一请求建立阶段时间线
可以为每次请求记录接收、应用开始、业务完成与响应完成等时点,并说明每个时点由哪个组件提供。应用内部只能直接观察自己开始执行之后的部分;如果请求已经在服务器队列中等了很久,业务计时仍可能很短。反向代理的请求耗时也不一定与应用耗时使用同样起止点。
关联依靠请求标识与实例身份,而不只是相近的时间。多实例日志里同时出现几个慢请求,若混成一条链,会错误解释等待来源。跨机器时间戳还要考虑时钟偏差;本地时长通常采用适合测量间隔的时钟,而不是用可被调整的墙钟相减。记录字段应足以解释口径,避免给一个模糊的 cost 包含多个含义。
对慢请求先区分尚未进入应用、进入应用后等待下游、应用计算繁忙和响应发送缓慢。若业务阶段很短但服务器总时间很长,队列、慢客户端或协议处理都是候选;若大量请求同时停在数据库获取连接,则要沿连接持有者继续查。每一步都用新的观测缩小范围,不能因为框架用了 async 就排除阻塞。
8.2 请求体消费也是资源协议
本篇 GET 请求不使用消息体,但示例 ASGI 函数仍消费请求事件直到结束。真实接口需要限制累计字节数、单块处理成本和等待时间;客户端持续发送极慢的数据时,应用不应无限保留缓冲。WSGI 中也要按服务器提供的信息和流接口读取,不要没有边界地 read() 所有内容。
如果应用提前拒绝输入,服务器怎样处理尚未消费的请求体与连接复用,属于服务器实现及协议约定,需要核验。应用不能随意读取后续请求字节,也不能假设关闭一个业务生成器就关闭整个客户端连接。HTTP/1.1 复用、HTTP/2 流和代理缓冲让这些边界更加不同。
ASGI 的多个请求体事件不是多个独立业务请求,而是同一请求内容的分块。more_body 表示还会继续,不是“现在应该提交部分数据”。流式导入可以设计分块处理,但整体成功语义要另外定义:全部成功、部分成功或可恢复进度分别需要不同结果协议与存储边界。
8.3 响应成功与业务成功的四种状态
业务尚未执行、业务执行失败、业务已提交但响应未送达、客户端已收到成功,是不同状态。日志若只记录“返回二百”,仍不能证明网络接收;客户端若只记录“超时”,也不能证明服务器回滚。对修改操作必须保留操作标识和可查询结果,才能在状态不确定时安全恢复。
对于只读查询,重试一般不产生相同的写副作用,但仍可能放大负载、读取新快照或重复消耗限额。大批客户端在超时后同时重试,会把已经排队的服务压得更慢。总截止时间、并发上限与退避策略应贯穿整个请求链,不应由每层各自无限等待。
8.4 从最小应用走向框架时保留哪些实验
接入框架后保留同一组参数输入:缺失、空值、零、一百零一、重复参数和合法前导零。比较框架解析后的值与本篇协议,若框架默认转换不同,显式配置或调整契约。然后验证错误响应、中文编码与响应体类型,避免只测试成功路径。
再加入真实服务器的关闭实验:停止接收新请求、正在执行的请求是否有时间完成、超时任务怎样取消、共享连接何时关闭。这不是本篇内存 ASGI 驱动已验证的能力,需要相应集成环境。最小实验提供理解入口,工程验收则沿相同边界增加证据,二者不能混为一谈。
指标也要包含失败路径。只给成功请求记录延迟,会让超时和异常从分布中消失;将取消任务统一记为快速完成,也会掩盖真实等待。按结果类别记录数量与时长,再结合并发中任务数和队列长度,才能解释服务是否稳定。教学实验没有负载统计,因此本文不据此给出任何吞吐提升倍数或服务器容量。
9. 进阶与面试
WSGI 和 HTTP 有什么不同? HTTP 面向网络交换,WSGI 是服务器与 Python 应用之间的同步调用协议。应用返回字节可迭代对象,由服务器完成网络响应处理。
ASGI 为什么适合异步和长连接? 它通过 scope 与异步收发事件表达生命周期,让应用在等待时协作调度。能力还取决于服务器、框架和所用下游接口。
一个 await send 表示客户端收到响应了吗? 不表示。它只完成对应服务器接口的发送阶段;网络送达、客户端读取和业务事务确认是不同事件。
后续接入框架时,用本篇同一 limit 规则验证真实参数解析和错误响应,再检查框架如何生成 WSGI 或 ASGI 输出。这样选择工具的依据是协议与行为,而不是只背框架名称。
从分块与断开事件走到真实框架生命周期
内存协议驱动依次发送两块 http.request,第一块 more_body=True、最后一块为假,断言两块事件都被消费后才发出响应。另两条路径分别发送 http.disconnect、让 send 主动抛异常。断开时不发响应,发送异常向外传播,但 finally 保存的 state.closed 都为真。这里 closed 是教学清理标记,不是假装关闭了真实数据库资源;真实应用应把对应资源退出放进相同责任边界。
HTTP-only应用没有实现lifespan,不能冒充完整ASGI框架。15_fastapi_server.py通过真实FastAPI与uvicorn启动本地临时端口,使用urllib发送有效limit、非法limit和重复参数,验证200/400。lifespan(应用启动与关闭协议)用asynccontextmanager记录startup/shutdown,服务器停止后断言顺序完整。应用生命周期资源适合在这里初始化并最终释放,请求级资源仍要按请求关闭,不能混成全局Session。
powershell
python -m pip install fastapi==0.162.0 uvicorn==0.54.0
python docs/python/examples/15_fastapi_server.py已在CPython3.13.7、FastAPI0.162.0、uvicorn0.54.0实跑通过,依赖Starlette1.10.0、Pydantic2.14.1/core2.50.1。真实请求依次返回200、400、400,lifespan记录startup后shutdown。脚本不是生产部署配置。它有启动等待和关闭join上限,并把后台线程异常传回主线程,避免“测试请求失败但服务器还留着”的假成功。重复参数显式拒绝,不能依赖不同框架恰好选择第一个或最后一个值。
独立能力任务:重现两块请求、断开、send失败三个协议分支,逐一验收响应数量和清理标记;再运行真实框架,验收HTTP状态与lifespan退出。慢客户端与后台任务涉及不同资源边界,接着读数据库连接池和有界任务队列,不要把请求结束当成所有工作结束。
完整真实框架示例:
python
"""真实 FastAPI/uvicorn HTTP 与 lifespan,依赖版本见环境锁文件。"""
from contextlib import asynccontextmanager
import json
import socket
import threading
import time
from urllib.error import HTTPError
from urllib.request import urlopen
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import uvicorn
def main():
events = []
errors = []
@asynccontextmanager
async def lifespan(app):
events.append("startup")
try:
yield
finally:
events.append("shutdown")
app = FastAPI(lifespan=lifespan)
@app.get("/counts")
async def counts(request: Request):
values = request.query_params.getlist("limit") or ["10"]
raw = values[0]
if (len(values) != 1 or not raw.isascii() or not raw.isdecimal()
or len(raw) > 3 or not 1 <= int(raw) <= 100):
return JSONResponse({"error": "invalid limit"}, status_code=400)
return {"limit": int(raw), "errors": 2}
listener = socket.socket()
listener.bind(("127.0.0.1", 0))
port = listener.getsockname()[1]
server = uvicorn.Server(uvicorn.Config(app, log_config=None, access_log=False,
lifespan="on", timeout_graceful_shutdown=2))
def serve():
try:
server.run(sockets=[listener])
except BaseException as error:
errors.append(error)
worker = threading.Thread(target=serve)
worker.start()
try:
deadline = time.monotonic() + 5
while not server.started and worker.is_alive() and time.monotonic() < deadline:
time.sleep(0.01)
assert server.started, errors
assert events == ["startup"]
for query, expected in [("limit=3", 200), ("limit=0", 400),
("limit=2&limit=3", 400)]:
try:
result = urlopen(f"http://127.0.0.1:{port}/counts?{query}", timeout=2)
except HTTPError as error:
result = error
with result:
assert result.code == expected
print("HTTP:", result.code, json.loads(result.read()))
finally:
server.should_exit = True
worker.join(timeout=5)
listener.close()
assert not worker.is_alive(), "server did not stop"
assert not errors, errors
assert events == ["startup", "shutdown"]
print("lifespan:", events)
if __name__ == "__main__":
main()10. 结尾
Python HTTP 接口把网络协议、应用调用与业务规则连接起来,可靠性取决于每一层的类型、生命周期和容量边界。
- WSGI 返回字节可迭代对象,ASGI 按事件顺序异步收发,两者都不替代 HTTP。
- 参数校验、编码、消息长度和错误响应必须明确,框架自动处理需要按版本核验。
- 并发能力来自完整服务器与下游模型,超时、断开和事务分别管理。