starlette 通过 request 对象的 headers 属性解析自定义 header,该属性是一个 headers 实例,支持字典式访问。开发者可以直接使用 request.headers.get('x-custom-header') 获取值,或使用 request.headers['x-custom-header'] 获取首个值并处理缺失异常。由于 http 头不区分大小写且可能重复,推荐使用 getlist() 获取所有同名头的列表。

如何安全地获取单个自定义 Header 值
在 Starlette 中,最安全的做法是使用 get() 方法配合默认值,避免 KeyError。因为 HTTP 规范允许 Header 名称大小写混合(如 x-custom 或 X-Custom),Headers 对象内部已做了规范化处理,开发者无需手动转换大小写即可直接匹配。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
import uvicorn
def get_custom_header(request):
# 使用 get 方法,第二个参数为默认值
value = request.headers.get('x-api-key', 'default_key')
return JSONResponse({"header_value": value})
app = Starlette(routes=[Route('/', get_custom_header)])
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
如何处理重复的自定义 Header
当客户端发送多个同名的自定义 Header 时(例如 X-Tags: A 和 X-Tags: B),get() 仅返回第一个值。若需获取所有值,必须调用 getlist() 方法,它返回一个 Python 列表。这在处理标签、多值认证或批量配置等场景时非常关键。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
import uvicorn
def get_all_custom_headers(request):
# 使用 getlist 获取所有同名 Header 的值
tags = request.headers.getlist('x-tags')
return JSONResponse({"tags": tags})
app = Starlette(routes=[Route('/', get_all_custom_headers)])
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
自定义 Header 在 Request 对象中的存储结构是什么
Starlette 的 Request 对象在初始化时会将原始 HTTP 头封装进 Headers 类实例。该实例底层基于 httpx.Headers,采用不可变映射结构,键名统一转为小写存储,但访问时保持原样匹配。这种设计确保了线程安全和快速查找,同时符合 HTTP/1.1 和 HTTP/2 的头部处理规范。开发者不应直接修改 request.headers,而应通过响应对象设置新头。










