starlette 使用中间件修改响应头,核心做法是定义一个接受 app 参数的类或函数,在内部调用 await app(scope, receive, send) 后拦截发送逻辑。通过自定义 send 协程,捕获类型为 http.response.start 的消息并在其中修改 headers 列表,即可向客户端添加或覆盖 http 响应头。

如何编写基础中间件类来注入 Header
要实现这一功能,需要创建一个继承自 ASGIMiddleware 的类,并重写 __call__ 方法。在该方法中,我们定义一个闭包 receive 和 send,其中 send 负责处理来自下游应用的 ASGI 消息。当收到 http.response.start 事件时,解析现有的头部信息,插入新的键值对,然后重新序列化并传递给原始的 send 回调。这种方法确保了所有经过该中间件的响应都会包含指定的头部字段。

Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import Response
from starlette.types import Scope, Receive, Send
class CustomHeaderMiddleware(BaseHTTPMiddleware):
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] != "http":
await self.app(scope, receive, send)
return
async def custom_send(message):
if message["type"] == "http.response.start":
# 获取现有 headers 并转换为字典以便操作
existing_headers = dict(message.get("headers", []))
# 添加自定义 Header
existing_headers[b"x-custom-header"] = b"modified-by-starlette"
# 重新构建 headers 列表
new_headers = [
(key.encode() if isinstance(key, str) else key,
value.encode() if isinstance(value, str) else value)
for key, value in existing_headers.items()
]
message["headers"] = new_headers
await send(message)
await self.app(scope, receive, custom_send)
# 使用示例
from starlette.applications import Starlette
from starlette.routing import Route
async def homepage(request):
return Response(content="Hello World")
app = Starlette(
routes=[Route("/", homepage)],
middleware=[CustomHeaderMiddleware()]
)如何处理并发请求中的 Header 隔离问题
在处理高并发场景时,必须确保每个请求的头部修改是独立的,避免不同请求之间的状态污染。上述实现通过在 __call__ 作用域内创建局部的 custom_send 函数,并利用每次调用时重新解析 message["headers"] 的方式,天然实现了请求间的隔离。每个 ASGI 消息都是独立的字典对象,修改其中一个不会影响其他并发请求的消息流。这种设计模式符合 ASGI 规范中对无状态中间件的要求,保证了在多 worker 或多线程环境下的安全性。

# 验证并发隔离的代码片段
import asyncio
from starlette.testclient import TestClient
client = TestClient(app)
def test_concurrent_headers():
# 模拟多个请求,确保每个请求都获得正确的 header
results = []
for _ in range(5):
response = client.get("/")
# 检查是否包含我们添加的 header
assert b"x-custom-header" in response.headers
results.append(response.status_code)
# 所有请求应成功返回 200
assert all(r == 200 for r in results)
test_concurrent_headers()如果下游应用已经设置了同名 Header 会怎样
当下游应用(如路由处理函数)已经设置了与中间件相同的 Header 名称时,最终结果取决于实现的合并策略。在上述代码中,由于我们将 headers 转换为字典再转回列表,后写入的值会覆盖先写入的值。因为中间件是在下游应用执行之后、发送之前介入的,所以中间件设置的 x-custom-header 将覆盖下游应用设置的同名 Header。如果需要保留下游应用的值或进行追加,则需要更复杂的逻辑来判断 Key 是否存在。对于大多数监控或追踪场景,强制覆盖是预期行为;但对于某些多值 Header,可能需要使用列表追加而非字典替换。

















