Litestar框架中的HTTP响应处理详解

最新推荐文章于 2025-06-06 09:11:31 发布

邢娣蝶

最新推荐文章于 2025-06-06 09:11:31 发布

阅读量279

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01064/article/details/148465851

Litestar框架中的HTTP响应处理详解

litestar Production-ready, Light, Flexible and Extensible ASGI API framework | Effortlessly Build Performant APIs 项目地址: https://gitcode.com/gh_mirrors/li/litestar

响应基础概念

在Litestar框架中，处理HTTP响应有多种灵活的方式。最基本的模式非常简单：只需从路由处理函数返回一个值，框架会自动处理后续的响应构建过程。

from pydantic import BaseModel
from litestar import get

class Resource(BaseModel):
    id: int
    name: str

@get("/resources")
def retrieve_resource() -> Resource:
    return Resource(id=1, name="my resource")

在这个例子中，路由处理函数返回了一个Pydantic模型实例。Litestar会使用这个值构建响应对象，默认情况下会设置状态码为200，Content-Type头为application/json，并将Resource实例序列化为JSON作为响应体。

媒体类型处理

默认与自定义媒体类型

默认情况下，Litestar使用JSON作为响应格式，但你也可以指定其他媒体类型：

from litestar import MediaType, get

@get("/resources", media_type=MediaType.TEXT)
def retrieve_resource() -> str:
    return "The rumbling rabbit ran around the rock"

Litestar支持以下几种标准媒体类型：

JSON (application/json)
MessagePack (application/x-msgpack)
纯文本 (text/plain)
HTML (text/html)

你也可以使用任何IANA注册的媒体类型字符串，但需要注意可能需要自定义序列化逻辑。

各媒体类型详解

JSON响应

作为默认格式，JSON支持序列化多种Python类型：

标准库的dataclass
Pydantic模型和dataclass
UUID对象
日期时间对象
msgspec.Struct
包含上述类型的容器（字典、列表等）

MessagePack响应

MessagePack是一种高效的二进制序列化格式：

from litestar import get, MediaType

@get(path="/health-check", media_type=MediaType.MESSAGEPACK)
def health_check() -> dict[str, str]:
    return {"hello": "world"}

纯文本响应

from litestar import get, MediaType

@get(path="/health-check", media_type=MediaType.TEXT)
def health_check() -> str:
    return "healthy"

HTML响应

from litestar import get, MediaType

@get(path="/page", media_type=MediaType.HTML)
def health_check() -> str:
    return """
    <html>
        <body>
            <div>
                <span>Hello World!</span>
            </div>
        </body>
    </html>
    """

对于复杂HTML响应，建议使用模板引擎而非硬编码字符串。

内容协商

当处理程序可以返回多种媒体类型时，可以使用内容协商让客户端选择：

from litestar import get, MediaType, Request

@get("/resources")
def retrieve_resource(request: Request) -> str | dict:
    if request.accept == MediaType.TEXT:
        return "text response"
    return {"json": "response"}

状态码控制

可以通过status_code参数设置响应状态码：

from litestar import get
from litestar.status_codes import HTTP_202_ACCEPTED

@get("/resources", status_code=HTTP_202_ACCEPTED)
def retrieve_resource() -> dict:
    return {"id": 1, "name": "my resource"}

默认状态码规则：

POST: 201 (Created)
DELETE: 204 (No Content)
GET/PATCH/PUT: 200 (Ok)

注意：某些状态码不允许响应体，如204、304等。

高级响应处理

直接返回响应对象

除了返回数据让框架构建响应，你也可以直接返回响应对象：

from litestar import get, Response

@get("/")
def handler() -> Response[str]:
    return Response(content="hello world", media_type="text/plain")

返回ASGI应用

Litestar支持直接返回ASGI应用：

from litestar import get
from litestar.types import ASGIApp, Receive, Scope, Send

@get("/")
def handler() -> ASGIApp:
    async def my_asgi_app(scope: Scope, receive: Receive, send: Send) -> None:
        await send({
            "type": "http.response.start",
            "status": 200,
            "headers": [(b"content-type", b"text/plain")],
        })
        await send({
            "type": "http.response.body",
            "body": b"Hello, world!",
        })
    return my_asgi_app

响应头管理

静态头设置

可以在应用各层级设置响应头：

from litestar import get, ResponseHeader

@get(
    "/",
    response_headers={
        "my-header": ResponseHeader(value="header-value", description="A custom header")
    }
)
def handler() -> str:
    return "hello world"

动态头设置

有两种主要方式动态设置响应头：

通过返回响应对象直接设置
使用请求后钩子(after_request hook)

from litestar import get, Response
from litestar.datastructures import ResponseHeader

@get(
    "/random",
    response_headers={
        "Random-Header": ResponseHeader(
            description="a random number header",
            documentation_only=True
        )
    }
)
def handler() -> Response[str]:
    import random
    return Response(
        content=str(random.random()),
        headers={"Random-Header": str(random.randint(1, 100))}
    )

特殊响应头实现

缓存控制头

Litestar提供了专门的CacheControlHeader实现：

from litestar import get
from litestar.datastructures.headers import CacheControlHeader

@get(
    "/cached",
    cache_control=CacheControlHeader(max_age=3600, public=True)
)
def cached_handler() -> str:
    return "This response will be cached for 1 hour"

ETag头

from litestar import get
from litestar.datastructures.headers import ETag

@get("/etag")
def etag_handler() -> tuple[str, ETag]:
    return "content", ETag(value="unique-value")

响应Cookie设置

可以在应用各层级设置Cookie：

from litestar import get
from litestar.datastructures import Cookie

@get(
    "/",
    response_cookies=[
        Cookie(key="session-id", value="abc123", max_age=3600)
    ]
)
def handler() -> str:
    return "hello world"

Cookie设置遵循层级覆盖原则，低层级的定义会覆盖高层级的同名Cookie。