从 Litestar 迁移到 FastAPI 实战指南
从 Litestar 迁移到 FastAPI 的完整对照手册：请求响应处理、依赖注入、中间件与生命周期、认证、msgspec 到 Pydantic 的校验迁移、错误处理与路由组织。
直接回答：Litestar 迁移到 FastAPI 的核心是七处概念映射：路由声明、依赖注入、生命周期钩子、中间件、校验库（msgspec→Pydantic）、错误处理与路由组织。两者同为 ASGI 类型注解流派，概念可映射，但状态码、序列化、依赖生命周期和认证契约都需逐项验证。
为什么有人迁
迁移前先确认目标框架是否满足所需集成、资料和团队维护要求；本文不以未经核验的下载量、客户名单或性能排名作为依据。当"招人难、资料少"成为真实瓶颈时，迁移就是理性选择。
概念速查对照
| Litestar | FastAPI |
|---|---|
@get/@post 装饰器 + Controller |
@app.get/@router.post |
Provide 依赖注入 |
Depends |
on_startup/on_shutdown |
lifespan 上下文 / 旧式钩子（FastAPI 新代码优先 lifespan） |
| 中间件（ASGI 协议层） | app.add_middleware / ASGI 中间件 |
| msgspec Struct | Pydantic BaseModel |
NotFoundException 等内置异常 |
HTTPException |
| Controller 分组路由 | APIRouter |
请求与响应处理
# Litestar
@get("/posts/{pid:int}")
async def get_post(pid: int) -> PostDTO: ...
# FastAPI
@app.get("/posts/{pid}")
async def get_post(pid: int): ...
路径参数语法从 {pid:int} 变为 {pid} + 类型注解；返回值从 DTO 变为 response_model。Query/Header/Body 在 FastAPI 里用 Query()、Header()、模型参数显式声明。
依赖注入
# Litestar
@get("/me", dependencies={"user": Provide(get_user)})
async def me(user: NamedDependency[User]) -> User: ...
# 需导入 litestar.di.Provide、NamedDependency，并定义项目 User
# FastAPI
@app.get("/me")
def me(user=Depends(get_user)): ...
FastAPI 的 Depends 支持嵌套（依赖的依赖）、yield 清理、缓存（同请求内复用结果），表达能力不输 Litestar 的 Provide，写法更贴近函数签名。
中间件与生命周期
# FastAPI 生命周期
from contextlib import asynccontextmanager
@asynccontextmanager
async def lifespan(app):
await db.connect()
try:
yield
finally:
await db.disconnect()
app = FastAPI(lifespan=lifespan)
中间件直接加 ASGI 中间件类：app.add_middleware(GZipMiddleware)——Litestar 的中间件逻辑大多可以平移。
校验：msgspec → Pydantic
# Litestar (msgspec)
class PostIn(Struct):
title: str
# FastAPI (Pydantic)
class PostIn(BaseModel):
title: str = Field(min_length=1, max_length=200)
字段约束从 msgspec 的 Meta 注解迁到 Field()；复杂校验用 Pydantic 的 field_validator。迁移时顺手审视校验规则——Pydantic 生态（EmailStr、HttpUrl 等）往往让规则更完整。
错误处理与路由组织
Litestar 的异常体系映射为 HTTPException + 自定义 @app.exception_handler；Controller 按域拆成 APIRouter，前缀与标签在 include 时统一指定。大型应用推荐按业务域目录组织 router。
迁移策略
- 并行跑：新服务挂同一网关下按路径分流，按 router 逐个迁移；
- 先 leaf 后核心：边缘端点先迁练手，核心链路最后动；
- 契约测试护航：迁移前后响应结构 diff 必须为空。
常见问题（FAQ）
Q：性能会掉多少？
A：没有统一差值。不同类型、校验规则和 payload 的成本不同，应对迁移前后同一接口测量吞吐、延迟及错误语义。Litestar 也支持多种模型类型，不是只能使用 msgspec。
Q：Litestar 的 DTO 概念在 FastAPI 怎么实现？
A：用分离的 Pydantic 模型（Create/Update/Response 各一个）+ response_model——思想一致，FastAPI 靠约定而非框架强制。
Q：必须全量迁移吗？
A：不必。两个框架都是 ASGI，可以长期共存于同一网关后；只为招聘/生态迁移时，通常可先迁移边界清晰的模块，再评估余下成本。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
