在 starlette 中设置响应状态码和响应头,最直接的方式是实例化 starlette.responses.response 的子类(如 jsonresponse),并在构造函数中传入 status_code 参数以及通过 headers 字典传递自定义头部。这样做会生成一个包含指定 http 状态码和完整头部信息的响应对象,直接返回给 asgi 服务器即可生效。

如何创建带自定义头的 JSON 响应
要创建一个返回 JSON 数据并附带自定义响应头的接口,可以使用 JSONResponse 类。只需在初始化时提供 status_code 为期望的状态值(例如 201 或 404),并通过 headers 参数传入一个字典,其中键值对即为需要设置的头部信息。Starlette 会自动将这些头部合并到最终的 HTTP 响应中。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
async def custom_json_response(request):
# 定义自定义响应头
headers = {
"X-Custom-Header": "MyValue",
"X-Request-ID": "12345"
}
# 创建响应,指定状态码和头部
return JSONResponse(
content={"message": "Success", "data": [1, 2, 3]},
status_code=201,
headers=headers
)
app = Starlette(routes=[Route("/api/data", custom_json_response)])
上述代码定义了路由 /api/data。当请求该路径时,应用将返回状态码 201 Created,响应体为 JSON 格式,且包含 X-Custom-Header 和 X-Request-ID 两个自定义头部。这是处理结构化数据并需要精细控制元数据的标准做法。
如何修改已有响应的头部信息
如果已经生成了一个响应对象但需要追加或修改头部,可以直接操作响应对象的 headers 属性。这是一个 Headers 对象,支持类似字典的赋值操作。你可以先创建基础响应,然后通过 response.headers["Key"] = "Value" 的方式动态添加或覆盖特定头部,最后再返回该对象。这种方式适用于需要在业务逻辑中间件或装饰器中注入额外信息的场景。

from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route
async def modify_headers(request):
# 先创建一个基础响应
response = PlainTextResponse(content="Hello World", status_code=200)
# 动态添加或修改头部
response.headers["Cache-Control"] = "no-cache"
response.headers["X-Powered-By"] = "Starlette"
# 返回修改后的响应
return response
app = Starlette(routes=[Route("/text", modify_headers)])
在 /text 路由中,程序首先创建一个普通的文本响应。随后,代码显式地向 response.headers 字典中写入了 Cache-Control 和 X-Powered-By。这种写法允许开发者在响应构建完成后,根据运行时条件灵活调整头部内容,而不必在初始构造时就确定所有细节。
使用 Response 基类设置通用状态码与头部
除了特定的子类,还可以直接使用 starlette.responses.Response 基类来设置状态码和头部。这在需要返回非标准 MIME 类型或纯文本、二进制流等场景下非常有用。通过实例化 Response 并传入 status_code 和 headers,可以完全控制 HTTP 响应的元数据部分。需要注意的是,基类通常要求提供 content 参数,且默认 Content-Type 可能为空或需手动指定。
from starlette.applications import Starlette
from starlette.responses import Response
from starlette.routing import Route
async def generic_response(request):
headers = {
"Content-Type": "application/octet-stream",
"X-Custom-Generic": "True"
}
return Response(
content=b"Binary data or raw text",
status_code=200,
headers=headers
)
app = Starlette(routes=[Route("/generic", generic_response)])
此示例展示了如何使用基类 Response。它明确设置了 Content-Type 为 application/octet-stream,并添加了 X-Custom-Generic 头部。返回的内容是字节串。这种灵活性使得开发者可以处理各种非 JSON 或非 HTML 的响应场景,同时保持对状态码和头部的精确控制。


















