Litestar框架请求处理全解析：从基础到高级用法-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00313/article/details/148465846

Litestar框架请求处理全解析：从基础到高级用法

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

请求体基础处理

在Litestar框架中，处理HTTP请求体非常简单直观。框架提供了一个特殊的data参数，可以直接在路由处理函数中使用它来获取请求体内容。

from litestar import post

@post("/")
async def handler(data: dict) -> dict:
    return {"received": data}

这种设计使得请求体处理变得异常简洁，开发者无需编写繁琐的解析代码。Litestar支持多种数据类型作为请求体：

Python标准库类型（如dict、list等）
类型字典（TypedDict）
数据类（dataclass）
通过插件支持的类型（如Msgspec Struct、Pydantic模型、Attrs类等）

from dataclasses import dataclass
from litestar import post

@dataclass
class User:
    name: str
    age: int

@post("/")
async def handler(data: User) -> User:
    return data

请求体验证与OpenAPI文档定制

Litestar提供了Body类来实现对请求体的精细控制，包括验证规则和OpenAPI文档定制：

from litestar import post
from litestar.params import Body

@post("/")
async def create_user(
    data: User = Body(
        title="User Creation",
        description="Create a new user account",
        min_length=1,
        max_length=100,
    )
) -> User:
    return data

这种设计不仅增强了API的健壮性，还能自动生成详细的API文档，极大提高了开发效率。

内容类型处理

默认JSON处理

默认情况下，Litestar会将请求体解析为JSON格式。这在大多数RESTful API场景下是最常用的处理方式。

URL编码表单数据

对于application/x-www-form-urlencoded类型的内容，需要显式指定媒体类型：

from litestar import post
from litestar.enums import RequestEncodingType
from litestar.params import Body

@post("/")
async def handle_url_encoded_form(
    data: dict = Body(media_type=RequestEncodingType.URL_ENCODED)
) -> dict:
    return data

需要注意的是，URL编码数据相比JSON能力有限，不适合处理复杂嵌套结构。

多部分表单数据

处理文件上传等场景需要使用multipart/form-data类型：

from litestar import post
from litestar.enums import RequestEncodingType
from litestar.params import Body

@post("/")
async def handle_multipart_form(
    data: dict = Body(media_type=RequestEncodingType.MULTI_PART)
) -> dict:
    return data

文件上传处理

单文件上传

Litestar为文件上传提供了UploadFile类，它封装了临时文件处理，支持异步操作：

from litestar import post
from litestar.datastructures import UploadFile

@post("/")
async def handle_file_upload(data: UploadFile) -> dict:
    content = await data.read()
    return {"filename": data.filename, "size": len(content)}

对于同步处理函数，可以直接使用文件对象的read方法：

@post("/")
def handle_file_upload_sync(data: UploadFile) -> dict:
    content = data.file.read()
    return {"filename": data.filename, "size": len(content)}

多文件上传

对于多个文件上传，可以使用Pydantic模型进行结构化处理：

from pydantic import BaseModel
from litestar import post
from litestar.datastructures import UploadFile

class FileUploadModel(BaseModel):
    avatar: UploadFile
    resume: UploadFile

@post("/")
async def handle_multiple_files(data: FileUploadModel) -> dict:
    return {"avatar_size": len(await data.avatar.read())}

文件字典和列表形式

如果不需要严格验证，可以直接使用字典或列表接收文件：

# 字典形式
@post("/")
async def handle_files_dict(data: dict[str, UploadFile]) -> dict:
    return {name: file.filename for name, file in data.items()}

# 列表形式
@post("/")
async def handle_files_list(data: list[UploadFile]) -> dict:
    return {"count": len(data)}

MessagePack数据处理

Litestar支持MessagePack这种高效的二进制序列化格式：

from litestar import post
from litestar.enums import RequestEncodingType
from litestar.params import Body

@post("/")
async def handle_msgpack(data: dict = Body(media_type=RequestEncodingType.MESSAGEPACK)) -> dict:
    return data

自定义请求类

从2.7.0版本开始，Litestar支持自定义请求类，可以在应用级别进行配置：

from litestar import Litestar, Request, get
from litestar.connection import ASGIConnection

class CustomRequest(Request):
    @property
    def is_authenticated(self) -> bool:
        return "user_id" in self.session

@get("/")
async def handler(request: CustomRequest) -> dict:
    return {"is_authenticated": request.is_authenticated}

app = Litestar(route_handlers=[handler], request_class=CustomRequest)

这种设计遵循Litestar的分层架构理念，可以在不同层级（应用、路由等）设置不同的请求类，最接近路由处理程序的层具有最高优先级。

请求体大小限制

Litestar默认限制请求体大小为10MB，超过此限制会返回413错误。可以通过request_max_body_size参数调整：

from litestar import Litestar, post

# 全局设置
app = Litestar(route_handlers=[...], request_max_body_size=1024 * 1024 * 20)  # 20MB

# 针对特定路由取消限制（慎用）
@post("/large-upload", request_max_body_size=None)
async def handle_large_upload(data: bytes) -> dict:
    return {"size": len(data)}

需要注意的是，取消限制可能存在安全风险，建议仅在受控环境中使用，如配合反向代理的请求大小限制。