Litestar 2.x 版本演进全解析从 2.0 大重构到 2.7 的稳定化之路【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar本文聚焦 Litestar 官方 2.x 系列变更日志docs/release-notes/2.x-changelog.rst系统梳理 2.0 到 2.7 的版本演进脉络从 Pydantic 去依赖化、响应体系重构、DTO 代码生成到静态文件简化、Postgres 通道后端与 Python 3.12 支持。读完本文你将完整掌握 Litestar 2.x 的破坏性变更清单、关键迁移路径与核心新增 API 的实战用法为升级到 3.x当前仓库主线见 pyproject.toml 中version 3.0.0b0做好准备。一、2.x 版本总览一条从重构到稳定的演进曲线Litestar 2.x 系列共发布了约 30 个版本时间跨度从 2023 年 5 月的2.0.0alpha1到 2024 年 3 月的2.7.1。从变更日志docs/release-notes/2.x-changelog.rst的版本节奏可以看出清晰的三个阶段阶段版本区间主题代表性能力预发布重构期2.0.0alpha1 ~ 2.0.0rc1大规模破坏性重构移除 Pydantic 硬依赖、DTO 体系重建、ASGIResponse引入2.0 正式版2.0.02023-08-19收敛回归、修复大量 2.0 回归修复稳定功能期2.1.0 ~ 2.7.1新功能与生态扩展MiniJinja、RapiDoc、DTO 代码生成、Postgres 通道、Python 3.12二、2.0 时代从 Starlite 到 Litestar 的破坏性大重构2.0 是 Litestar前身 Starlite历史上最重要的一次重构。整个 2.x 变更日志记录了大量:breaking:变更理解它们是升级任何旧版本应用的基础。2.1 响应体系重构Response容器合并与ASGIResponse诞生2.0 系列最核心的架构变化是响应体系的重建移除响应容器Response ContainersFile、Redirect、Template、Stream等包装类被移除其功能与Response类合并。现在它们作为Response的子类保留在litestar.response模块中并且继承了Response的全部能力——例如添加 headers 和 cookies 的方法对应源码 litestar/response/ 下的file.py、redirect.py、streaming.py等。引入ASGIResponseResponse类如今只是包装与上下文对象不再负责数据发送。真正的 I/O 由底层不可变对象ASGIResponse位于 litestar/response/base.py执行。从源码结构可以推断ASGIResponse及其子类可以被当作任何 ASGI 应用创建和返回但它们是低层接口缺少高层响应类型的便捷方法。Response.get_serializer迁移该实例方法被移除替换为模块级函数litestar.serialization.get_serializer见 litestar/serialization/。原因是响应体现在直到 handler 返回之后、转换为ASGIResponse时才编码handler 层解析的type_encoders仍有合并机会独立函数让中间件与序列化器的交互大幅简化。2.2 Pydantic 降级为可选依赖双版本同存2.0 的另一个标志性变化是Pydantic 不再是硬依赖2.0.0beta3起 Pydantic 不再被 Litestar 内部依赖但仍以同样能力被支持多个配置模型从 Pydantic 模型替换为 dataclass如AppConfig、CORSConfig、LoggingConfig、OpenAPIConfig等官方标注除非你依赖它们是 Pydantic 模型否则基本无感2.3.0更进一步通过集成 Pydantic 的向后兼容层实现Pydantic 1 与 2 在同一应用中共存from litestar import get from pydantic.v1 import BaseModel as BaseModelV1 from pydantic import BaseModel class V1Foo(BaseModelV1): bar: str class V2Foo(BaseModel): bar: str get(/1) def foo_v1(data: V1Foo) - V1Foo: return data get(/2) def foo_v2(data: V2Foo) - V2Foo: return data2.3 生命周期钩子与状态 API 的收拢2.0 系列对应用生命周期做了一轮收拢移除before_startup/after_startup/before_shutdown/after_shutdown统一为on_startup和on_shutdown且它们的可选首参从 state 改为Litestar应用实例AfterExceptionHookHandler与BeforeMessageSendHookHandler移除state参数改用scope[app].state访问Litestar(initial_state...)改为Litestar(stateState({...}))新增lifespan参数接受异步上下文管理器包装应用生命周期2.4.0又新增server_lifespan钩子只在多 worker 场景下区别于每次 startup 调用的lifespan——它整个服务器生命周期只调用一次。三、DTO数据传输对象体系2.x 最重要的能力增长点DTO 是 2.x 变更日志中占比最大的主题从 2.0 重建到 2.7 持续完善对应源码见 litestar/dto/含config.py、msgspec_dto.py、dataclass_dto.py、_codegen_backend.py。3.1 DTOConfig 配置能力的逐步补全DTOConfiglitestar/dto/config.py在 2.x 中逐步演进出以下核心配置exclude与includeinclude在 2.0.0beta3 加入作为exclude的对偶两者互斥同时指定会抛配置错误rename_fields早期叫field_mapping2.0.0alpha5 简化 DTOConfig 时更名且移除了重映射字段类型的能力partialTrue让所有字段可选未设置值在提取时被过滤用于简化 PATCH 请求处理但注意 2.6.2 的说明——partialTrue下长度约束无法传递字段被设为T | UNSETunderscore_fields_privateTrue默认将下划线前缀字段视为私有排除2.0.0beta1 引入。嵌套场景也在持续修复2.4.0 修复了嵌套 DTO 重命名会把所有同名字段一起改名的 bug并支持rename_fields{bars.0.id: bar_id}这种点号路径重命名2.0.0alpha6 加入了对嵌套字段的a.b点号排除语法。3.2 Msgspec 与 Pydantic DTO 工厂2.0.0beta1加入了MsgspecDTO与PydanticDTO工厂2.6.2 修复了msgspec.Meta约束如min_length3未在传输模型中生效的问题from typing import Annotated import msgspec from litestar import post, Litestar from litestar.dto import MsgspecDTO class Request(msgspec.Struct): foo: Annotated[str, msgspec.Meta(min_length3)] post(/example/, dtoMsgspecDTO[Request]) async def example(data: Request) - Request: return data3.3 DTOData 与任意泛型包装DTOData2.0.0alpha7 引入用于接收已校验但未结构化的 DTO 数据解决客户端数据不足以实例化完整模型的场景create_instance()支持foo__barbaz双下划线嵌套传值任意泛型包装handler 返回类型不被 DTO 直接支持时只要返回值类型是泛型、且某个泛型参数能被 DTO 管理并映射到实例属性DTO 操作就会作用于该属性并返回原实例见 2.0.0beta1 的Wrapped[User, int]示例。3.4 实验性 DTO 代码生成后端2.2.0 引入了实验性的DTO codegen 后端litestar/dto/_codegen_backend.py通过预生成优化 Python 代码加速传输过程官方在变更日志中给出测试数据视操作与数据类型不同新后端快 2.5~5 倍。启用方式from litestar import Litestar from litestar.config.app import ExperimentalFeatures app Litestar(experimental_features[ExperimentalFeatures.DTO_CODEGEN])该特性标志在 litestar/config/app.py 中定义为ExperimentalFeatures.DTO_CODEGEN。四、静态文件服务从专用 ASGI 应用到普通路由2.6.0对静态文件处理做了根本性简化静态文件服务不再是一个特化的 ASGI 应用而是用普通路由 handler 实现。推荐用法从StaticFilesConfig迁移为create_static_files_router# 旧方式 app Litestar( static_files_config[StaticFilesConfig(path/static, directories[some_dir])] ) # 新方式 from litestar.static_files import create_static_files_router app Litestar( route_handlers[ create_static_files_router(path/static, directories[some_dir]) ] )这一改变带来的收益包括绕开路由逻辑对静态文件应用的特殊处理、移除应用上的static_files_config属性、以及不再需要url_for_static_asset方法改用route_reverse。从当前源码 litestar/static_files.py 可以看到create_static_files_router的实际签名其参数比 2.6.0 最初版本更丰富包括path/directories挂载路径与源目录必填file_system可传BaseFileSystem、fsspec文件系统实例或字符串从FileSystemRegistry查找缺省用默认文件系统send_as_attachment是否作为附件下载html_modeHTML 模式下从/提供index.html找不到文件时提供404.htmlcache_control设置Cache-Control头2.6.2 修复过该参数未传到生成 handler 的问题allow_symlinks_outside_directory是否允许符号链接指向目录外默认False安全考量。此外2.6.0 还新增了resolve_symlinks标志默认True保持向后兼容。静态文件相关 bugfix 贯穿 2.x2.6.1 修复 Windows 路径解析、2.5.4 前修复 gzip/brotli 压缩文件缺少content-encoding头、2.0.0 修复与 route handler 同路径时的 404、以及 root path/无法服务静态文件的问题2.0.0alpha1。五、OpenAPI 与 JSON Schema持续数版的格式修复战役OpenAPI schema 生成是 2.x 中修复密度最高的领域之一涉及格式正确性、命名稳定性和类型覆盖。5.1 examples 的 OpenAPI 3.1 与 JSON Schema 格式之争2.7.1 专门修复了一个容易混淆的规范问题JSON Schema 对象里的examples必须用数组格式而不是 OpenAPI 的 example 对象格式。错误OpenAPI example 格式不能在 Schema 中使用 examples: { some-id: { description: Lorem ipsum, value: the real beef } } 正确JSON Schema 格式 examples: [the real beef]技术上的改变是把Schema.examples从list[Example]改为list[Any]OpenAPI 对象Parameter、Body仍用list[Example]而 JSON schema 内部生成/转换为list[Any]。背景是 OpenAPI 3.0 只允许 schema 对象中的单数example字段3.1 才支持完整的 JSON Schema 2020-12 与examples数组。5.2 从格式到命名与确定性的系统性修复example 生成确定性2.7.0 让create_examplesTrue时的随机种子可配置2.7.0 还让Components.schemas按规范化名称字母序确定性插入2.0.0 修复了随机播种配置错误导致的 example 非确定性回归名称冲突2.4.4 回退了 2.4.0 引入的 schema key 计算变化——无冲突时恢复原名只有重名对象才用扩展 key此前直接抛异常2.0.0alpha7 为 DTO 生成的名称附加 8 字节随机串防止类名冲突类型覆盖2.4.0 补上 Pydantic URL 类型AnyUrl的序列化与 schema 支持2.4.1 修复递归模型的RecursionError2.4.3 修复Literal | None联合2.3.0 支持泛型响应类型注解如Response[ResponseStruct[str]]与变长元组tuple[str, ...]2.2.0 让dict[str, int]正确渲染为additionalProperties多 handler 与参数2.4.4 修复同路径不同方法注册导致 operation ID 冲突的回归2.4.2 修复不同位置header/cookie同名字段的误判、camelCase 传播错误并支持 pydantic computed fields。5.3 OpenAPI 展示层与 CLI2.3.0 加入 RapiDoc 可视化支持2.7.1 将 Rapidoc 与 Stoplight Elements 的spec-url/apiDescriptionUrl修正为站点根目录的绝对路径2.2.0 增加/schema/openapi.yml路径2.3.0 修复litestar schema openapi --output schema.json导出非 JSON 可序列化类型时的编码错误改用 Litestar 自己的 JSON 编码器2.5.0 为litestar route命令新增--schema包含 OpenAPI schema/docs 路由与--exclude按模式排除路由选项。六、SSE、WebSockets、Channels实时能力建设6.1 Server-Sent Events 正式支持2.0.0rc1引入ServerSentEvent源码见 litestar/response/sse.pyfrom litestar.response import ServerSentEvent async def my_generator() - AsyncGenerator[bytes, None]: count 0 while count 10: await sleep(0.01) count 1 yield str(count) get(path/count) def sse_handler() - ServerSentEvent: return ServerSentEvent(my_generator())随后的修复值得一提2.5.0 修复了event_type在第一条消息后回退为默认值的问题——现在ServerSentEvent(gen(), event_typemy_event)会对所有消息持续发送该事件类型litestar/response/sse.py 中event: {event_type}编码逻辑可见2.7.0 修复了 SSE 事件无 data 时 JS 客户端收不到事件的问题默认补上空字符串。6.2 Channels 模块与 Postgres 后端2.0.0alpha6 新增 Channels 模块litestar/channels/2.5.0 补齐 Postgres 支持新增两个后端AsyncPgChannelsBackendlitestar/channels/backends/asyncpg.py基于 asyncpg 驱动PsycoPgChannelsBackendlitestar/channels/backends/psycopg.py基于 psycopg3 异步驱动。同版本还修复了取消订阅后短暂仍能收到消息的问题受影响内存、Redis PubSub、asyncpg不受影响Redis stream、psycopg2.3.0 修复了arbitrary_channels_allowed模式下无订阅轮询导致的高 CPU 空转2.4.0 修复了通道 WebSocket handler 关闭连接时的RuntimeError: Unexpected ASGI message websocket.close。6.3 WebSockets 能力增强2.0.0alpha6 加入iter_data/iter_json迭代接收、MessagePack 支持send_msgpack/receive_msgpack/iter_msgpack2.0.0alpha5 为WebSocketListener加入dto/return_dto参数2.0.0alpha7 的 listener 钩子支持依赖注入socket参数不再强制2.0.0alpha6 新增connection_accept_handler与connection_lifespan上下文管理器2.7.0 让websocket_class可在各层暴露配置并修复WebsocketListenerRouteHandler未传递type_decoders的问题。七、CLI、会话、缓存、日志工程化细节的密集打磨7.1 CLI 的普及与 SSL 支持2.2.0 起CLI 默认启用litestar[cli]extra 保留但无实际效果2.0.0alpha1 增加--wc/--web-concurrency与WEB_CONCURRENCY环境变量2.0.0alpha6 增加根命令--app-dir2.0.0beta1 增加--reload-dir2.6.0 增加reload-exclude/reload-include2.3.0 为litestar run增加--ssl-certfile/--ssl-keyfile与--create-devcert用cryptography生成自签名开发证书两文件都存在则直接用、都不存在则生成、只存在一个则报歧义异常2.3.1 修复了未提供 SSL 文件时配合--reload/--web-concurrency导致 uvicornFileNotFoundError的问题2.0.0beta1 新增pdb_on_exception参数与LITESTAR_PDB1环境变量、CLI--pdb标志2.0.0alpha7 引入sync_to_thread相关警告可用LITESTAR_WARN_IMPLICIT_SYNC_TO_THREAD0和LITESTAR_WARN_SYNC_TO_THREAD_WITH_ASYNC0关闭。7.2 会话中间件2.7.0 对服务端会话做了一次重要改进litestar/middleware/session/session id 在 route handler 之前生成首次访问时 handler scope 内即可获得 idBaseSessionBackend新增抽象方法get_session_idlitestar/middleware/session/base.py服务端会话返回真实 idserver_side.py客户端会话返回Noneclient_side.pyrequest.set_session(...)对服务端会话返回 id、对客户端会话返回None会话认证中间件改为通过配置的 backend 引用 Session 中间件而非硬编码。其他修复2.6.1 修复短 cookie 4 KB不再附加-{i}分块后缀2.1.0 让认证中间件exclude_http_methods默认值为OPTIONS2.0.0 修复 JWT 与 SessionAuth 默认认证OPTIONS/HEAD的回归。7.3 响应缓存2.2.0 将缓存从响应层移到ASGI 层对sendcallable 发送的每条消息进行缓存与重放保证压缩中间件先于缓存执行缓存命中时跳过压缩同时规避了 pickle 格式的慢速与存储膨胀2.3.0 新增ResponseCacheConfig.cache_response_filter谓词用于判别哪些响应可被缓存2.0.0alpha3 加入CACHE_FOREVER哨兵值与default_expirationNone支持无限期缓存2.3.0 修复同路由不同 HTTP 方法导致缓存互相覆盖的 bug。7.4 日志与错误处理2.6.0 新增LoggingConfig.configure_root_logger默认True设为False可避免修改 root logger2.7.1 为 Python 3.12 修复queue_listenerhandler3.12 改变了dictConfig()配置QueueHandler/QueueListener的方式并引入LoggingQueueListener2.6.1 修复 structlog 下请求体畸形导致 500 的问题解析出错时回退使用原始 body2.4.0 修复 structlog 未安装时请求体按 UTF-8 假设解码导致乱码改用backslashreplace2.0.0alpha1 加入log_exceptionsalways/debug/never、traceback_line_limit、exception_logging_handler三项日志配置同版本修复LoggingMiddleware混淆函数原地修改字典导致向客户端发送混淆数据的问题。7.5 异常与校验2.7.0 让ValidationException只显示 path 而非完整 URL避免泄露内部 IP2.0.0beta2 起 500 响应默认 detail 固定为Internal Server Error并从 500 响应移除异常细节2.0.0beta2 的校验错误响应 key 升级为完整字段路径并新增source键标明 body/cookie/header/query 来源2.2.0 的缺失参数错误信息加入来源如Missing required header parameter foo2.4.4 修复空 payload 带默认值时的误报2.5.0 修复异常响应中自定义类型序列化type_encoders需从所有层解析。八、SQLAlchemy 与 Advanced Alchemy仓库模式的持续演进2.x 中 SQLAlchemy 集成经历了从内置contrib.sqlalchemy到外部advanced_alchemy库的切换2.1.0 将内部 SQLAlchemy 仓库实现切换为外部advanced_alchemy并支持lambda_stmt、list_and_count中直接传复杂where表达式如ST_DWithin(...)2.0.0rc1 为仓库方法增加id_attribute参数、新增upsert_many、过滤器OnBeforeAfter/NotInCollectionFilter/NotInSearchFilter、delete_many的chunk_size分块2.0.0beta3 加入auto_commit/auto_expunge/auto_refresh三个会话参数源码对应 litestar/repository/ 相关实现数据库支持持续扩展2.0.0beta1 增加 Oracleoracledb、DuckDB、Google Spanner2.0.0alpha5 增加 MySQL/MariaDBasyncmy与psycopgasyncio2.0.0beta3 支持同步仓库SQLAlchemySyncRepository2.6.1 将仓库异常从已废弃的ConflictError改为IntegrityError2.1.0 修复 advanced-alchemy 0.6.0 中touch_updated_timestamp的导入兼容。九、值得开发者留意的其他特性与修复模板引擎2.1.0 支持 MiniJinja 引擎与自定义 Jinja2Environment/ MakoTemplateLookup2.4.0 的Template新增template_string参数支持直接渲染字符串模板2.0.0beta1 让 Mako 默认开启表达式自动转义与 Jinja 配置对齐路由2.7.0 支持Router实例重复挂载注册时 deepcopy与 controller/handler 行为对齐2.4.0 暴露request_class、websocket_class、type_decoders到各层依赖注入2.0.0alpha7 起依赖可直接传入dependencies字典而无需Provide包装litestar/di.py 对应实现2.6.0 新增DIPlugin支持为无法从__init__提取签名的外部类型生成签名Pydantic 与 Msgspec 插件默认注册2.4.1 对缓存生成器依赖改为启动期配置错误而非运行期 5002.5.0 提升线程同步执行性能asyncio 用run_in_executor、trio 用to_thread.run_sync类型系统2.0.0beta1 公开ParsedType作为公共 API并修复is_subclass_of对联合类型的判断Annotated全面支持2.0.0alpha4 起多部分表单与文件上传2.5.0 修复声明多文件却上传单文件被误判校验失败的问题2.4.0 修复空字符串在 multipart 解码中的校验错误依赖打包2.5.2 将exceptiongroup后移包依赖从 Python 3.10 调整为 3.112.2.0 修复MissingDependencyException在包名与 extra 名不一致如litestar[jinja]vsjinja2时提示错误的包名。十、升级清单从 2.x 迁移的实用建议综合整个 2.x 变更日志中的破坏性变更升级到 3.x 前建议按以下清单排查响应 API检查是否依赖Response.get_serializer()改用serialization.get_serializer、encoded_headers已废弃改用MutableScopeHeaders生命周期钩子before_/after_startup/shutdown已移除统一on_startup/on_shutdown参数为应用实例after_exception/before_send钩子不再接收state参数DTO确认field_mapping已改为rename_fieldsdto.exceptions模块已移除DTOData与partialTrue是 PATCH 场景的推荐方案静态文件优先使用create_static_files_router注意 symlink 安全默认值配置对象cache_config改名response_cache_config缓存后端统一走StoreRegistry见 litestar/stores/会话BaseSessionBackend需实现get_session_id若自定义后端PydanticLitestar 不再强制 Pydantic若使用 Pydantic DTO/插件请显式安装相应依赖。通过 docs/release-notes/2.x-changelog.rst 的完整版本记录配合 docs/release-notes/changelog.rst 与 docs/release-notes/whats-new-3.rst 中的 3.x 演进说明可以构建出从 2.x 到 3.x 的完整迁移地图。【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Litestar 2.x 版本演进全解析：从 2.0 大重构到 2.7 的稳定化之路
Litestar 2.x 版本演进全解析从 2.0 大重构到 2.7 的稳定化之路【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar本文聚焦 Litestar 官方 2.x 系列变更日志docs/release-notes/2.x-changelog.rst系统梳理 2.0 到 2.7 的版本演进脉络从 Pydantic 去依赖化、响应体系重构、DTO 代码生成到静态文件简化、Postgres 通道后端与 Python 3.12 支持。读完本文你将完整掌握 Litestar 2.x 的破坏性变更清单、关键迁移路径与核心新增 API 的实战用法为升级到 3.x当前仓库主线见 pyproject.toml 中version 3.0.0b0做好准备。一、2.x 版本总览一条从重构到稳定的演进曲线Litestar 2.x 系列共发布了约 30 个版本时间跨度从 2023 年 5 月的2.0.0alpha1到 2024 年 3 月的2.7.1。从变更日志docs/release-notes/2.x-changelog.rst的版本节奏可以看出清晰的三个阶段阶段版本区间主题代表性能力预发布重构期2.0.0alpha1 ~ 2.0.0rc1大规模破坏性重构移除 Pydantic 硬依赖、DTO 体系重建、ASGIResponse引入2.0 正式版2.0.02023-08-19收敛回归、修复大量 2.0 回归修复稳定功能期2.1.0 ~ 2.7.1新功能与生态扩展MiniJinja、RapiDoc、DTO 代码生成、Postgres 通道、Python 3.12二、2.0 时代从 Starlite 到 Litestar 的破坏性大重构2.0 是 Litestar前身 Starlite历史上最重要的一次重构。整个 2.x 变更日志记录了大量:breaking:变更理解它们是升级任何旧版本应用的基础。2.1 响应体系重构Response容器合并与ASGIResponse诞生2.0 系列最核心的架构变化是响应体系的重建移除响应容器Response ContainersFile、Redirect、Template、Stream等包装类被移除其功能与Response类合并。现在它们作为Response的子类保留在litestar.response模块中并且继承了Response的全部能力——例如添加 headers 和 cookies 的方法对应源码 litestar/response/ 下的file.py、redirect.py、streaming.py等。引入ASGIResponseResponse类如今只是包装与上下文对象不再负责数据发送。真正的 I/O 由底层不可变对象ASGIResponse位于 litestar/response/base.py执行。从源码结构可以推断ASGIResponse及其子类可以被当作任何 ASGI 应用创建和返回但它们是低层接口缺少高层响应类型的便捷方法。Response.get_serializer迁移该实例方法被移除替换为模块级函数litestar.serialization.get_serializer见 litestar/serialization/。原因是响应体现在直到 handler 返回之后、转换为ASGIResponse时才编码handler 层解析的type_encoders仍有合并机会独立函数让中间件与序列化器的交互大幅简化。2.2 Pydantic 降级为可选依赖双版本同存2.0 的另一个标志性变化是Pydantic 不再是硬依赖2.0.0beta3起 Pydantic 不再被 Litestar 内部依赖但仍以同样能力被支持多个配置模型从 Pydantic 模型替换为 dataclass如AppConfig、CORSConfig、LoggingConfig、OpenAPIConfig等官方标注除非你依赖它们是 Pydantic 模型否则基本无感2.3.0更进一步通过集成 Pydantic 的向后兼容层实现Pydantic 1 与 2 在同一应用中共存from litestar import get from pydantic.v1 import BaseModel as BaseModelV1 from pydantic import BaseModel class V1Foo(BaseModelV1): bar: str class V2Foo(BaseModel): bar: str get(/1) def foo_v1(data: V1Foo) - V1Foo: return data get(/2) def foo_v2(data: V2Foo) - V2Foo: return data2.3 生命周期钩子与状态 API 的收拢2.0 系列对应用生命周期做了一轮收拢移除before_startup/after_startup/before_shutdown/after_shutdown统一为on_startup和on_shutdown且它们的可选首参从 state 改为Litestar应用实例AfterExceptionHookHandler与BeforeMessageSendHookHandler移除state参数改用scope[app].state访问Litestar(initial_state...)改为Litestar(stateState({...}))新增lifespan参数接受异步上下文管理器包装应用生命周期2.4.0又新增server_lifespan钩子只在多 worker 场景下区别于每次 startup 调用的lifespan——它整个服务器生命周期只调用一次。三、DTO数据传输对象体系2.x 最重要的能力增长点DTO 是 2.x 变更日志中占比最大的主题从 2.0 重建到 2.7 持续完善对应源码见 litestar/dto/含config.py、msgspec_dto.py、dataclass_dto.py、_codegen_backend.py。3.1 DTOConfig 配置能力的逐步补全DTOConfiglitestar/dto/config.py在 2.x 中逐步演进出以下核心配置exclude与includeinclude在 2.0.0beta3 加入作为exclude的对偶两者互斥同时指定会抛配置错误rename_fields早期叫field_mapping2.0.0alpha5 简化 DTOConfig 时更名且移除了重映射字段类型的能力partialTrue让所有字段可选未设置值在提取时被过滤用于简化 PATCH 请求处理但注意 2.6.2 的说明——partialTrue下长度约束无法传递字段被设为T | UNSETunderscore_fields_privateTrue默认将下划线前缀字段视为私有排除2.0.0beta1 引入。嵌套场景也在持续修复2.4.0 修复了嵌套 DTO 重命名会把所有同名字段一起改名的 bug并支持rename_fields{bars.0.id: bar_id}这种点号路径重命名2.0.0alpha6 加入了对嵌套字段的a.b点号排除语法。3.2 Msgspec 与 Pydantic DTO 工厂2.0.0beta1加入了MsgspecDTO与PydanticDTO工厂2.6.2 修复了msgspec.Meta约束如min_length3未在传输模型中生效的问题from typing import Annotated import msgspec from litestar import post, Litestar from litestar.dto import MsgspecDTO class Request(msgspec.Struct): foo: Annotated[str, msgspec.Meta(min_length3)] post(/example/, dtoMsgspecDTO[Request]) async def example(data: Request) - Request: return data3.3 DTOData 与任意泛型包装DTOData2.0.0alpha7 引入用于接收已校验但未结构化的 DTO 数据解决客户端数据不足以实例化完整模型的场景create_instance()支持foo__barbaz双下划线嵌套传值任意泛型包装handler 返回类型不被 DTO 直接支持时只要返回值类型是泛型、且某个泛型参数能被 DTO 管理并映射到实例属性DTO 操作就会作用于该属性并返回原实例见 2.0.0beta1 的Wrapped[User, int]示例。3.4 实验性 DTO 代码生成后端2.2.0 引入了实验性的DTO codegen 后端litestar/dto/_codegen_backend.py通过预生成优化 Python 代码加速传输过程官方在变更日志中给出测试数据视操作与数据类型不同新后端快 2.5~5 倍。启用方式from litestar import Litestar from litestar.config.app import ExperimentalFeatures app Litestar(experimental_features[ExperimentalFeatures.DTO_CODEGEN])该特性标志在 litestar/config/app.py 中定义为ExperimentalFeatures.DTO_CODEGEN。四、静态文件服务从专用 ASGI 应用到普通路由2.6.0对静态文件处理做了根本性简化静态文件服务不再是一个特化的 ASGI 应用而是用普通路由 handler 实现。推荐用法从StaticFilesConfig迁移为create_static_files_router# 旧方式 app Litestar( static_files_config[StaticFilesConfig(path/static, directories[some_dir])] ) # 新方式 from litestar.static_files import create_static_files_router app Litestar( route_handlers[ create_static_files_router(path/static, directories[some_dir]) ] )这一改变带来的收益包括绕开路由逻辑对静态文件应用的特殊处理、移除应用上的static_files_config属性、以及不再需要url_for_static_asset方法改用route_reverse。从当前源码 litestar/static_files.py 可以看到create_static_files_router的实际签名其参数比 2.6.0 最初版本更丰富包括path/directories挂载路径与源目录必填file_system可传BaseFileSystem、fsspec文件系统实例或字符串从FileSystemRegistry查找缺省用默认文件系统send_as_attachment是否作为附件下载html_modeHTML 模式下从/提供index.html找不到文件时提供404.htmlcache_control设置Cache-Control头2.6.2 修复过该参数未传到生成 handler 的问题allow_symlinks_outside_directory是否允许符号链接指向目录外默认False安全考量。此外2.6.0 还新增了resolve_symlinks标志默认True保持向后兼容。静态文件相关 bugfix 贯穿 2.x2.6.1 修复 Windows 路径解析、2.5.4 前修复 gzip/brotli 压缩文件缺少content-encoding头、2.0.0 修复与 route handler 同路径时的 404、以及 root path/无法服务静态文件的问题2.0.0alpha1。五、OpenAPI 与 JSON Schema持续数版的格式修复战役OpenAPI schema 生成是 2.x 中修复密度最高的领域之一涉及格式正确性、命名稳定性和类型覆盖。5.1 examples 的 OpenAPI 3.1 与 JSON Schema 格式之争2.7.1 专门修复了一个容易混淆的规范问题JSON Schema 对象里的examples必须用数组格式而不是 OpenAPI 的 example 对象格式。错误OpenAPI example 格式不能在 Schema 中使用 examples: { some-id: { description: Lorem ipsum, value: the real beef } } 正确JSON Schema 格式 examples: [the real beef]技术上的改变是把Schema.examples从list[Example]改为list[Any]OpenAPI 对象Parameter、Body仍用list[Example]而 JSON schema 内部生成/转换为list[Any]。背景是 OpenAPI 3.0 只允许 schema 对象中的单数example字段3.1 才支持完整的 JSON Schema 2020-12 与examples数组。5.2 从格式到命名与确定性的系统性修复example 生成确定性2.7.0 让create_examplesTrue时的随机种子可配置2.7.0 还让Components.schemas按规范化名称字母序确定性插入2.0.0 修复了随机播种配置错误导致的 example 非确定性回归名称冲突2.4.4 回退了 2.4.0 引入的 schema key 计算变化——无冲突时恢复原名只有重名对象才用扩展 key此前直接抛异常2.0.0alpha7 为 DTO 生成的名称附加 8 字节随机串防止类名冲突类型覆盖2.4.0 补上 Pydantic URL 类型AnyUrl的序列化与 schema 支持2.4.1 修复递归模型的RecursionError2.4.3 修复Literal | None联合2.3.0 支持泛型响应类型注解如Response[ResponseStruct[str]]与变长元组tuple[str, ...]2.2.0 让dict[str, int]正确渲染为additionalProperties多 handler 与参数2.4.4 修复同路径不同方法注册导致 operation ID 冲突的回归2.4.2 修复不同位置header/cookie同名字段的误判、camelCase 传播错误并支持 pydantic computed fields。5.3 OpenAPI 展示层与 CLI2.3.0 加入 RapiDoc 可视化支持2.7.1 将 Rapidoc 与 Stoplight Elements 的spec-url/apiDescriptionUrl修正为站点根目录的绝对路径2.2.0 增加/schema/openapi.yml路径2.3.0 修复litestar schema openapi --output schema.json导出非 JSON 可序列化类型时的编码错误改用 Litestar 自己的 JSON 编码器2.5.0 为litestar route命令新增--schema包含 OpenAPI schema/docs 路由与--exclude按模式排除路由选项。六、SSE、WebSockets、Channels实时能力建设6.1 Server-Sent Events 正式支持2.0.0rc1引入ServerSentEvent源码见 litestar/response/sse.pyfrom litestar.response import ServerSentEvent async def my_generator() - AsyncGenerator[bytes, None]: count 0 while count 10: await sleep(0.01) count 1 yield str(count) get(path/count) def sse_handler() - ServerSentEvent: return ServerSentEvent(my_generator())随后的修复值得一提2.5.0 修复了event_type在第一条消息后回退为默认值的问题——现在ServerSentEvent(gen(), event_typemy_event)会对所有消息持续发送该事件类型litestar/response/sse.py 中event: {event_type}编码逻辑可见2.7.0 修复了 SSE 事件无 data 时 JS 客户端收不到事件的问题默认补上空字符串。6.2 Channels 模块与 Postgres 后端2.0.0alpha6 新增 Channels 模块litestar/channels/2.5.0 补齐 Postgres 支持新增两个后端AsyncPgChannelsBackendlitestar/channels/backends/asyncpg.py基于 asyncpg 驱动PsycoPgChannelsBackendlitestar/channels/backends/psycopg.py基于 psycopg3 异步驱动。同版本还修复了取消订阅后短暂仍能收到消息的问题受影响内存、Redis PubSub、asyncpg不受影响Redis stream、psycopg2.3.0 修复了arbitrary_channels_allowed模式下无订阅轮询导致的高 CPU 空转2.4.0 修复了通道 WebSocket handler 关闭连接时的RuntimeError: Unexpected ASGI message websocket.close。6.3 WebSockets 能力增强2.0.0alpha6 加入iter_data/iter_json迭代接收、MessagePack 支持send_msgpack/receive_msgpack/iter_msgpack2.0.0alpha5 为WebSocketListener加入dto/return_dto参数2.0.0alpha7 的 listener 钩子支持依赖注入socket参数不再强制2.0.0alpha6 新增connection_accept_handler与connection_lifespan上下文管理器2.7.0 让websocket_class可在各层暴露配置并修复WebsocketListenerRouteHandler未传递type_decoders的问题。七、CLI、会话、缓存、日志工程化细节的密集打磨7.1 CLI 的普及与 SSL 支持2.2.0 起CLI 默认启用litestar[cli]extra 保留但无实际效果2.0.0alpha1 增加--wc/--web-concurrency与WEB_CONCURRENCY环境变量2.0.0alpha6 增加根命令--app-dir2.0.0beta1 增加--reload-dir2.6.0 增加reload-exclude/reload-include2.3.0 为litestar run增加--ssl-certfile/--ssl-keyfile与--create-devcert用cryptography生成自签名开发证书两文件都存在则直接用、都不存在则生成、只存在一个则报歧义异常2.3.1 修复了未提供 SSL 文件时配合--reload/--web-concurrency导致 uvicornFileNotFoundError的问题2.0.0beta1 新增pdb_on_exception参数与LITESTAR_PDB1环境变量、CLI--pdb标志2.0.0alpha7 引入sync_to_thread相关警告可用LITESTAR_WARN_IMPLICIT_SYNC_TO_THREAD0和LITESTAR_WARN_SYNC_TO_THREAD_WITH_ASYNC0关闭。7.2 会话中间件2.7.0 对服务端会话做了一次重要改进litestar/middleware/session/session id 在 route handler 之前生成首次访问时 handler scope 内即可获得 idBaseSessionBackend新增抽象方法get_session_idlitestar/middleware/session/base.py服务端会话返回真实 idserver_side.py客户端会话返回Noneclient_side.pyrequest.set_session(...)对服务端会话返回 id、对客户端会话返回None会话认证中间件改为通过配置的 backend 引用 Session 中间件而非硬编码。其他修复2.6.1 修复短 cookie 4 KB不再附加-{i}分块后缀2.1.0 让认证中间件exclude_http_methods默认值为OPTIONS2.0.0 修复 JWT 与 SessionAuth 默认认证OPTIONS/HEAD的回归。7.3 响应缓存2.2.0 将缓存从响应层移到ASGI 层对sendcallable 发送的每条消息进行缓存与重放保证压缩中间件先于缓存执行缓存命中时跳过压缩同时规避了 pickle 格式的慢速与存储膨胀2.3.0 新增ResponseCacheConfig.cache_response_filter谓词用于判别哪些响应可被缓存2.0.0alpha3 加入CACHE_FOREVER哨兵值与default_expirationNone支持无限期缓存2.3.0 修复同路由不同 HTTP 方法导致缓存互相覆盖的 bug。7.4 日志与错误处理2.6.0 新增LoggingConfig.configure_root_logger默认True设为False可避免修改 root logger2.7.1 为 Python 3.12 修复queue_listenerhandler3.12 改变了dictConfig()配置QueueHandler/QueueListener的方式并引入LoggingQueueListener2.6.1 修复 structlog 下请求体畸形导致 500 的问题解析出错时回退使用原始 body2.4.0 修复 structlog 未安装时请求体按 UTF-8 假设解码导致乱码改用backslashreplace2.0.0alpha1 加入log_exceptionsalways/debug/never、traceback_line_limit、exception_logging_handler三项日志配置同版本修复LoggingMiddleware混淆函数原地修改字典导致向客户端发送混淆数据的问题。7.5 异常与校验2.7.0 让ValidationException只显示 path 而非完整 URL避免泄露内部 IP2.0.0beta2 起 500 响应默认 detail 固定为Internal Server Error并从 500 响应移除异常细节2.0.0beta2 的校验错误响应 key 升级为完整字段路径并新增source键标明 body/cookie/header/query 来源2.2.0 的缺失参数错误信息加入来源如Missing required header parameter foo2.4.4 修复空 payload 带默认值时的误报2.5.0 修复异常响应中自定义类型序列化type_encoders需从所有层解析。八、SQLAlchemy 与 Advanced Alchemy仓库模式的持续演进2.x 中 SQLAlchemy 集成经历了从内置contrib.sqlalchemy到外部advanced_alchemy库的切换2.1.0 将内部 SQLAlchemy 仓库实现切换为外部advanced_alchemy并支持lambda_stmt、list_and_count中直接传复杂where表达式如ST_DWithin(...)2.0.0rc1 为仓库方法增加id_attribute参数、新增upsert_many、过滤器OnBeforeAfter/NotInCollectionFilter/NotInSearchFilter、delete_many的chunk_size分块2.0.0beta3 加入auto_commit/auto_expunge/auto_refresh三个会话参数源码对应 litestar/repository/ 相关实现数据库支持持续扩展2.0.0beta1 增加 Oracleoracledb、DuckDB、Google Spanner2.0.0alpha5 增加 MySQL/MariaDBasyncmy与psycopgasyncio2.0.0beta3 支持同步仓库SQLAlchemySyncRepository2.6.1 将仓库异常从已废弃的ConflictError改为IntegrityError2.1.0 修复 advanced-alchemy 0.6.0 中touch_updated_timestamp的导入兼容。九、值得开发者留意的其他特性与修复模板引擎2.1.0 支持 MiniJinja 引擎与自定义 Jinja2Environment/ MakoTemplateLookup2.4.0 的Template新增template_string参数支持直接渲染字符串模板2.0.0beta1 让 Mako 默认开启表达式自动转义与 Jinja 配置对齐路由2.7.0 支持Router实例重复挂载注册时 deepcopy与 controller/handler 行为对齐2.4.0 暴露request_class、websocket_class、type_decoders到各层依赖注入2.0.0alpha7 起依赖可直接传入dependencies字典而无需Provide包装litestar/di.py 对应实现2.6.0 新增DIPlugin支持为无法从__init__提取签名的外部类型生成签名Pydantic 与 Msgspec 插件默认注册2.4.1 对缓存生成器依赖改为启动期配置错误而非运行期 5002.5.0 提升线程同步执行性能asyncio 用run_in_executor、trio 用to_thread.run_sync类型系统2.0.0beta1 公开ParsedType作为公共 API并修复is_subclass_of对联合类型的判断Annotated全面支持2.0.0alpha4 起多部分表单与文件上传2.5.0 修复声明多文件却上传单文件被误判校验失败的问题2.4.0 修复空字符串在 multipart 解码中的校验错误依赖打包2.5.2 将exceptiongroup后移包依赖从 Python 3.10 调整为 3.112.2.0 修复MissingDependencyException在包名与 extra 名不一致如litestar[jinja]vsjinja2时提示错误的包名。十、升级清单从 2.x 迁移的实用建议综合整个 2.x 变更日志中的破坏性变更升级到 3.x 前建议按以下清单排查响应 API检查是否依赖Response.get_serializer()改用serialization.get_serializer、encoded_headers已废弃改用MutableScopeHeaders生命周期钩子before_/after_startup/shutdown已移除统一on_startup/on_shutdown参数为应用实例after_exception/before_send钩子不再接收state参数DTO确认field_mapping已改为rename_fieldsdto.exceptions模块已移除DTOData与partialTrue是 PATCH 场景的推荐方案静态文件优先使用create_static_files_router注意 symlink 安全默认值配置对象cache_config改名response_cache_config缓存后端统一走StoreRegistry见 litestar/stores/会话BaseSessionBackend需实现get_session_id若自定义后端PydanticLitestar 不再强制 Pydantic若使用 Pydantic DTO/插件请显式安装相应依赖。通过 docs/release-notes/2.x-changelog.rst 的完整版本记录配合 docs/release-notes/changelog.rst 与 docs/release-notes/whats-new-3.rst 中的 3.x 演进说明可以构建出从 2.x 到 3.x 的完整迁移地图。【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
