starlette 通过 `starlette.responses.response` 基类处理 http 状态码,开发者只需在实例化时指定 `status_code` 参数即可。默认情况下,所有响应对象的状态码为 200 ok。若需返回其他状态码(如 404 not found 或 500 internal server error),应使用对应的快捷子类(如 `jsonresponse`、`htmlresponse`)并传入相应的状态码值,或者自定义继承自 `response` 的类来覆盖该属性。

如何快速返回常见的错误状态码
对于常见的 HTTP 错误,Starlette 提供了专门的响应类,它们内部预设了特定的状态码。例如,`HTTPException` 配合 `HTMX` 或标准路由通常用于抛出异常,而直接使用 `Response` 子类则更灵活。要返回 404,可以使用 `Response(status_code=404)`;要返回 403 Forbidden,可使用 `JSONResponse(status_code=403)`。这些类会自动设置正确的 `Status-Line`。

from starlette.applications import Starlette
from starlette.responses import JSONResponse, Response
from starlette.routing import Route
async def not_found(request):
return Response(content="Page not found", status_code=404)
async def forbidden_json(request):
return JSONResponse(
status_code=403,
content={"detail": "Permission denied"}
)
app = Starlette(routes=[
Route("/404", not_found),
Route("/403", forbidden_json),
])
如何在中间件中统一修改响应状态码
当需要在请求处理流程中动态改变状态码时(例如鉴权失败或缓存命中),可以在中间件或路由逻辑中直接修改 `response.status_code` 属性。Starlette 的 `Response` 对象是可变的,因此在响应发送回客户端之前,任何代码都可以更新其状态码。这允许你在不改变响应体内容的情况下,仅调整 HTTP 状态以符合协议规范。

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import Response
class StatusModifierMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request, call_next):
response = await call_next(request)
# 假设某些条件满足时,将成功响应降级为临时重定向
if request.url.path.startswith('/legacy'):
response.status_code = 307
return response
# 使用示例
# app.add_middleware(StatusModifierMiddleware)
未定义的状态码会如何处理
如果开发者传入一个未在 RFC 标准中明确定义或超出常规范围的状态码(如 999 或 600),Starlette 不会阻止它,而是将其原样写入 HTTP 响应的状态行中。这意味着底层 ASGI 服务器(如 Uvicorn 或 Gunicorn)负责最终的传输。虽然大多数浏览器和客户端可能无法正确解释这些非标准码,但从协议层面看,这是合法的。建议仅在测试或与特定遗留系统交互时使用此类自定义码,生产环境应严格遵循 HTTP/1.1 或 HTTP/2 的标准状态码定义。











