Litestar 快速入门从最小应用到类控制器与 DTO 的 ASGI 实战指南【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar本文是 Litestar 框架的官方入门指南对应仓库文档 docs/getting-started.rst面向初次接触 Litestar 的开发者。你将学会如何安装框架、用 6 行代码跑起第一个 ASGI 应用、利用litestar run命令与自动生成的 OpenAPI 文档并进一步掌握基于类控制器Controller与 DTOData Transfer Object组织 CRUD 接口的工程化写法最后理解该框架的设计哲学与功能定位。读完本文你可以独立搭建一个带数据校验、部分更新与类型化路由的 REST 服务并知道下一步该去哪里深入学习。安装 LitestarLitestar 通过 pip 即可安装最简单的安装方式是pip install litestar不过在正式开始开发前官方推荐安装litestar[standard]扩展包因为它包含了日常开发最常用的一批依赖CLIlitestar命令、UvicornASGI 服务器以及 Jinja2模板引擎pip install litestar[standard]可选 Extras 一览Litestar 将大量高级能力拆分为可选的 extra 依赖按需安装即可。下表完整列出了官方入门文档给出的全部 extrasExtras用途安装命令pydanticPydantic v2 数据校验与序列化支持pip install litestar[pydantic]attrsattrs 数据类支持pip install litestar[attrs]brotliBrotli 压缩中间件见 docs/usage/middleware/builtin-middleware.rstpip install litestar[brotli]zstdZstd 压缩中间件见 docs/usage/middleware/builtin-middleware.rstpip install litestar[zstd]cryptography基于 Cookie 的会话中间件pip install litestar[cryptography]jwtJWT 认证与授权见 docs/usage/security/jwt.rstpip install litestar[jwt]redisRedis 存储后端 RedisStore见 docs/usage/stores.rstpip install litestar[redis]prometheusPrometheus 指标采集见 docs/usage/metrics/prometheus.rstpip install litestar[prometheus]opentelemetryOpenTelemetry 链路追踪见 docs/usage/metrics/opentelemetry.rstpip install litestar[opentelemetry]sqlalchemySQLAlchemy ORM 集成基于 Advanced-Alchemy见 docs/usage/databases/sqlalchemy/index.rstpip install litestar[sqlalchemy]jinjaJinja2 模板渲染见 docs/usage/templating.rstpip install litestar[jinja]makoMako 模板渲染见 docs/usage/templating.rstpip install litestar[mako]polyfactory利用 Polyfactory 生成更高质量的 OpenAPI 示例见 docs/usage/openapi/schema_generation.rstpip install litestar[polyfactory]htmxHTMX 插件见 docs/usage/htmx.rstpip install litestar[htmx]yamlOpenAPI YAML 格式渲染见 docs/usage/openapi/ui_plugins.rstpip install litestar[yaml]standard标准安装包含 CLI、Uvicorn 与 Jinja2 模板pip install litestar[standard]full安装全部 extraspip install litestar[full]关于 extras 有两点需要留意官方不推荐使用full一次性安装所有 extras因为会引入大量不必要的依赖拖慢安装并增加安全面。上述 extras 均定义在项目根目录的 pyproject.toml 的[project.optional-dependencies]段中是安装信息的权威来源。从该文件还可以看到仓库实际还维护了minijinja、valkey、piccolo、annotated-types、testing等文档未一一列出的 extras。同时requires-python 3.11表明当前版本要求 Python 3.11 及以上核心运行依赖为anyio、msgspec、multidict、multipart、sniffio等轻量库。最小示例六行代码跑起你的第一个应用安装好litestar[standard]后它已包含 Uvicorn创建一个名为app.py的文件写入以下内容from litestar import Litestar, get get(/) async def index() - str: return Hello, world! get(/books/{book_id:int}) async def get_book(book_id: int) - dict[str, int]: return {book_id: book_id} app Litestar([index, get_book])这段代码做了三件事用get(/)注册了一个根路径处理函数index返回字符串用get(/books/{book_id:int})注册了带类型化路径参数的处理函数get_book——花括号中的int是一个类型转换声明Litestar 会把 URL 中的/books/1自动解析成整数1并注入到book_id参数实例化Litestar应用并把两个处理函数以列表形式传入route_handlers参数完成路由注册。仓库中 docs/examples/todo_app/hello_world.py 提供了与此等价的最小示例可作为参考对照。启动应用启动方式有两种官方推荐使用 Litestar 自带的 CLIlitestar run # 也可以直接使用 Uvicorn uvicorn app:app --reload两条命令效果等价。uvicorn app:app --reload的含义是加载app.py中的app对象并开启热重载文件变更自动重启。如果你使用litestar runCLI 会自动发现应用对象。从 litestar/cli/main.py 的源码可以看到其发现规则自动扫描当前目录下app.py、asgi.py、application.py或app/__init__.py等约定路径对于应用工厂优先寻找名为create_app的函数或返回类型标注为Litestar的函数也可以通过--app选项显式指定如litestar --appmy_app.main:app或通过环境变量LITESTAR_APP指定。CLI 还支持--app-dir参数把指定目录加入PYTHONPATH用于模块发现。验证结果启动成功后在浏览器中访问http://localhost:8000/应返回文本Hello, world!http://localhost:8000/books/1应返回 JSON{book_id: 1}这里可以看到一个鲜明的框架特性返回值类型即序列化约定。index返回str响应就是纯文本get_book返回dict[str, int]响应就是 JSON。你不需要手动构造 Response 对象Litestar 会根据返回类型注解自动完成媒体类型与序列化处理。零成本的交互式 API 文档更贴心的是Litestar 会基于你的路由与类型注解自动生成 OpenAPI 文档默认挂载在/schema路径下支持三种界面界面URLReDochttp://localhost:8000/schemaSwagger UIhttp://localhost:8000/schema/swaggerStoplight Elementshttp://localhost:8000/schema/elements由于get_book的路径参数声明为int你会在文档中直接看到该参数的类型、是否必填等元信息——这一切都无需额外配置。深入路由类型化路径参数与请求参数注入最小示例中的{book_id:int}只是 Litestar 参数能力的冰山一角。框架支持四种请求参数来源分别对应两种声明形式详见 docs/usage/routing/parameters.rst参数类型短标记形式Annotated形式query查询参数FromQuery[T]Annotated[T, QueryParameter()]path路径参数FromPath[T]Annotated[T, PathParameter()]header请求头FromHeader[T]Annotated[T, HeaderParameter()]cookieFromCookie[T]Annotated[T, CookieParameter()]例如下面这个处理器同时使用了四种参数from litestar import get from litestar.params import FromCookie, FromHeader, FromPath, FromQuery get(/{user_id:int}) async def handler( user_id: FromPath[int], limit: FromQuery[int], token: FromHeader[str], session: FromCookie[str], ) - None: ...FromQuery[T]本质上就是Annotated[T, QueryParameter()]的类型别名当需要额外配置如QueryParameter(gt0, le100)的取值约束时使用Annotated形式即可。这些参数会从函数签名中被解析并生成内部数据模型用于校验和 OpenAPI schema 生成。路径参数始终是必填的因为它本身就是 URL 的一部分。扩展示例数据模型、DTO 与类控制器当应用从一两个函数增长为完整业务模块时Litestar 推荐采用数据模型 类控制器的组织方式。下面的示例完整演示了这一模式也是官方入门文档的核心章节。第一步定义数据模型既可以使用基于 Pydantic 的模型也包括 ormar、beanie、SQLModel 等任何基于 Pydantic 的库from pydantic import BaseModel, UUID4 class User(BaseModel): first_name: str last_name: str id: UUID4也可以使用标准库dataclasses、typing.TypedDict或msgspec.Struct。例如用标准库 dataclass 定义并配合 Litestar 的DataclassDTO生成一个“部分更新”用的 DTOfrom uuid import UUID from dataclasses import dataclass from litestar.dto import DTOConfig, DataclassDTO dataclass class User: first_name: str last_name: str id: UUID class PartialUserDTO(DataclassDTO[User]): config DTOConfig(exclude{id}, partialTrue)这里DTOConfig(exclude{id}, partialTrue)的含义是exclude{id}从 DTO 中排除id字段不允许客户端通过请求体修改主键partialTrue允许传输部分数据即所有字段都可选——这正是 PATCH 语义所需要的。从源码 litestar/dto/config.py 可以看到DTOConfig的完整配置项exclude与include互斥同时指定会抛出ImproperlyConfiguredException字段名支持address.street这样的点分嵌套路径此外还有rename_fields、rename_strategyupper/lower/camel/pascal或自定义函数、max_nested_depth嵌套深度上限默认 1、underscore_fields_private下划线开头的字段视为私有并排除默认开启、forbid_unknown_fields拒绝未知字段等。DTO 相关能力由 litestar/dto/init.py 统一导出。第二步定义控制器Controller控制器是把一组相关路由组织在一起、并复用公共配置的类式组件。完整的 CRUD 控制器如下from typing import List from litestar import Controller, get, post, put, patch, delete from litestar.dto import DTOData from pydantic import UUID4 from my_app.models import User, PartialUserDTO class UserController(Controller): path /users post() async def create_user(self, data: User) - User: ... get() async def list_users(self) - List[User]: ... patch(path/{user_id:uuid}, dtoPartialUserDTO) async def partial_update_user( self, user_id: UUID4, data: DTOData[User] ) - User: ... put(path/{user_id:uuid}) async def update_user(self, user_id: UUID4, data: User) - User: ... get(path/{user_id:uuid}) async def get_user(self, user_id: UUID4) - User: ... delete(path/{user_id:uuid}) async def delete_user(self, user_id: UUID4) - None: ...要点说明类属性path /users是控制器统一的路由前缀所有方法级路径如/{user_id:uuid}都会拼接到该前缀之下最终形成/users、/users/{user_id}等完整路径路径参数{user_id:uuid}使用了uuid转换器Litestar 会自动校验并解析为UUID4类型patch(..., dtoPartialUserDTO)把控制器中该处理器的入站数据交给PartialUserDTO处理配合DTOData[User]参数类型实现部分字段更新客户端只发送想修改的字段即可从源码 litestar/controller.py 可以确认Controller还支持在类级别声明guards守卫、middleware中间件、dependencies依赖注入、dto/return_dto、tags、cache_control等众多配置并会在注册时校验“同一路径 同一 HTTP 方法”的唯一性冲突会抛出ImproperlyConfiguredException所有 HTTP 方法装饰器get/post/put/patch/delete均从 litestar/handlers/http_handlers/init.py 导出。第三步装配应用并运行在应用的入口文件中导入控制器并传入Litestar实例from litestar import Litestar from my_app.controllers.user import UserController app Litestar(route_handlers[UserController])然后使用任意 ASGI 服务器启动uvicorn my_app.main:app --reload此时你的应用就具备了完整的/usersREST 资源POST /users创建、GET /users列表、GET /users/{id}详情、PUT /users/{id}全量更新、PATCH /users/{id}部分更新、DELETE /users/{id}删除并且请求体校验、路径参数解析、OpenAPI 文档都是自动生成的。设计哲学Litestar 的定位与理念官方入门文档用一段专门的章节阐述了 Litestar 的设计哲学理解这些原则有助于你更好地使用框架社区驱动而非单作者项目Litestar 由一个核心维护者团队领导并有活跃的贡献者社区支持项目保持非常积极的开发节奏。从 NestJS 汲取灵感Litestar 的类控制器设计受到当代 TypeScript 框架 NestJS 的启发——NestJS 把“约定”与“模式”置于框架核心Litestar 在 Python 生态中践行了类似的理念。函数式与 OOP 兼得框架在保留函数式端点如最小示例中的get用法的同时将基于类的控制器置于核心位置充分利用 Python 强大的面向对象能力来组织代码。明确不是微框架与 FastAPI、Starlette 或 Flask 等框架不同Litestar 开箱即用地内置了现代 Web 应用常见的大量功能——ORM 集成、客户端/服务端会话、缓存、OpenTelemetry 集成等。它也不打算成为“下一个 Django”例如永远不会内置自己的 ORM但其边界绝不“微”。与同类框架的功能对比入门文档附带了一张框架功能对比表原始数据见 docs/_static/tables/framework-comparison.csv列出 Litestar 与 FastAPI、Starlette、Sanic、Quart 的特性差异。以下为整理后的对照“-”表示原生不支持标注“Extension”表示需通过扩展实现特性LitestarFastAPIStarletteSanicQuartOpenAPI支持支持---自动 API 文档Swagger、ReDoc、Stoplight ElementsSwagger、ReDoc---数据校验支持支持---依赖注入支持支持-支持-类式路由支持Extension支持支持支持ORM 集成SQLAlchemy、Tortoise、Piccolo---Extension模板渲染Jinja、MakoJinjaJinjaJinjaJinjaMessagePack支持----CORS支持支持支持支持ExtensionCSRF支持----限流支持--Extension-JWT支持----会话支持仅客户端仅客户端-仅客户端认证JWT / 会话----缓存支持----可以看到Litestar 在 OpenAPI 多界面文档、MessagePack、CSRF、JWT、会话、缓存等方向上提供了开箱即用的能力。需要说明的是该表仅为官方文档自身的横向整理具体能力是否适合你的场景应以实际版本与需求为准。官方示例应用与下一步学习入门文档还推荐了三个官方维护的示例应用适合作为不同阶段的参考litestar-pg-redis-docker在 Litestar 基础上演示应用模块化组织、SQLAlchemy 2.0 ORM、Redis 缓存连接等模式的完整项目litestar-fullstack生产就绪的全栈示例包含 SQLAlchemy 2.0、ReactJS、Vite 前端构建、SAQ 任务队列、Jinja 模板等最佳实践配置litestar-hello-world最精简的应用骨架适合做测试与概念验证POC。如果想要更系统、循序渐进的练习官方推荐从 TODO 应用教程开始在 docs/tutorials/todo-app/index.rst 中你将亲手实现“获取列表、新增条目、标记完成”三个功能从而掌握 Litestar 的大部分基础构件。仓库中 docs/examples/todo_app/update.py 等示例文件展示了 dataclass 模型、路径参数FromPath与put装饰器的组合用法可作为对照阅读。至此你已经完成了 Litestar 从安装、最小应用、类控制器与 DTO到设计理念的完整入门闭环。接下来可以继续阅读 docs/usage/index.rst 探索依赖注入、中间件、安全、缓存、模板等进阶主题或直接打开自动生成的/schema文档审视自己第一个应用的 API 面貌。【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考