Starlette 1.0.0：删除和修复

Starlette 1.0.0：稳定版发布的关键变更

Starlette 在近八年的开发后，终于迎来了首个稳定版本 1.0.0。此次发布重点移除了已弃用的 API，修复了 WebSocket、表单和静态文件处理中的 bug。该框架仍是 FastAPI 的基础，并在 Python MCP SDK 中用于 AI 应用。

新功能

1.0.0 版本在 SessionMiddleware 中添加了会话访问和变更跟踪功能。这允许中间件记录会话数据的读取和修改，而无需额外的手动干预。

1.0.0rc1 版本引入了 WebSocket 的泛型状态。连接状态现在具有类型提示，便于在异步处理程序中使用 TypedDict 或 Pydantic 模型。

Bug 修复

此次发布修复了几个关键问题：

• StreamingResponse 和 FileResponse 中的 WebSocket 失败处理：响应现在正确关闭连接，不会发生泄漏。
• FormParser 使用 bytearray 进行字段累积，解析大表单时减少内存使用。
• MultiPartParser.parse() 将 parser.finalize() 移入 try/except，避免不完整 multipart 数据导致异常。

rc1 的额外修复：

• 416 响应的 Content-Range 头部包含 bytes 单位。
• StaticFiles 处理路径中零字节时不会崩溃。
• 范围解析使用排序合并以提高准确性。
• 响应中的多个范围使用 Content-Type 而非 Content-Range。
• Multipart byterange 边界应用 CRLF 终止符。
• FileResponse 在范围请求时不修改头部。
• CORS 响应在带凭据时返回明确的 origin。
• Jinja2Templates 默认启用 autoescape。

移除已弃用元素

Starlette 1.0.0 通过移除已弃用的函数清理了 API。老版本项目需要进行迁移。

以下是完整移除列表：

• Starlette 和 Router 中的 on_startup 和 on_shutdown 参数。用 lifespan 替代。
• on_event() 装饰器。使用 lifespan。
• add_event_handler() 方法。使用 lifespan。
• Router 中的 startup() 和 shutdown() 方法。
• @app.route() 装饰器。在 routes 中使用 Route。
• @app.websocket_route() 装饰器。在 routes 中使用 WebSocketRoute。
• @app.exception_handler() 装饰器。使用 exception_handlers。
• @app.middleware() 装饰器。使用 middleware。
• starlette.routing 中的 iscoroutinefunction_or_partial() 函数。
• Jinja2Templates 中的 **env_options 参数。通过 env 传递已准备好的 jinja2.Environment。
• 已弃用的 TemplateResponse(name, context) 签名。现在需要 request：TemplateResponse(request, name, ...)。
• FileResponse 中的已弃用 method 参数。

行为变更

Jinja2Templates 现在要求在导入时安装 jinja2，而不仅仅是在实例化时。这加速了 CI/CD 中的依赖诊断。

迁移到 1.0.0

• 将所有 on_startup/on_shutdown 替换为 lifespan 上下文：

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: Starlette):
    # startup
    yield
    # shutdown

app = Starlette(lifespan=lifespan, routes=[...])

• 将路由移到 routes 列表中：

routes = [
    Route("/", endpoint=home),
    WebSocketRoute("/ws", endpoint=ws_endpoint),
]

• 类似地更新 exception_handlers 和 middleware。

• 对于 Jinja2Templates，提前准备 env：

import jinja2
env = jinja2.Environment(autoescape=True)
templates = Jinja2Templates(env=env)

升级后测试范围请求和 multipart 表单。

关键要点

• API 稳定性：移除所有已弃用元素，使代码更简洁且更可预测。
• WebSocket 和流式传输：修复了失败处理，已准备好用于生产环境。
• 表单和文件：优化了内存使用和 multipart/范围解析。
• Lifespan 替代：统一生命周期钩子，与 ASGI 3.0+ 兼容。
• Jinja2：严格的依赖要求，默认启用 autoescape。

— Editorial Team