starlette 实现接口版本控制的核心做法是在路由定义时通过路径前缀区分版本,例如使用 /v1/ 和 /v2/ 作为不同的 url 前缀。开发者需要为每个版本创建独立的 route 或 apiroute 实例,并将它们注册到同一个 router 中。这样做的结果是客户端可以通过请求不同的 url 路径来访问同一接口的不同版本,而服务端可以根据路径自动分发请求到对应的处理逻辑。

如何基于URL前缀隔离不同版本的接口
在 Starlette 中,最直接的版本控制方式是利用 URL 路径的前缀来区分版本。你可以将 v1 和 v2 视为两个不同的命名空间,分别挂载不同的路由列表。这种方法不需要复杂的中间件,只需在初始化 Router 时传入包含版本前缀的路由对象即可。当用户访问 /v1/users 时,请求会被分发给 v1 的处理函数;访问 /v2/users 时,则分发给 v2 的处理函数。这种方式的优点是简单直观,易于调试和维护。

from starlette.applications import Starlette
from starlette.routing import Route, Router
from starlette.responses import JSONResponse
async def get_users_v1(request):
return JSONResponse({"version": "v1", "users": ["Alice"]})
async def get_users_v2(request):
return JSONResponse({"version": "v2", "users": [{"id": 1, "name": "Alice"}]})
# 定义 v1 路由
v1_routes = [
Route("/users", endpoint=get_users_v1),
]
# 定义 v2 路由
v2_routes = [
Route("/users", endpoint=get_users_v2),
]
# 创建主应用,挂载带前缀的路由
app = Starlette(routes=[
Router(prefix="/v1", routes=v1_routes),
Router(prefix="/v2", routes=v2_routes),
])
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
运行上述代码后,访问 http://localhost:8000/v1/users 将返回 v1 格式的响应,而访问 http://localhost:8000/v2/users 将返回 v2 格式的响应。预期结果分别是:{"version": "v1", "users": ["Alice"]} 和 {"version": "v2", "users": [{"id": 1, "name": "Alice"}]}。这验证了通过前缀隔离版本的有效性。
如何通过中间件统一处理版本头信息
除了 URL 前缀,另一种常见的版本控制方式是通过 HTTP Header(如 X-API-Version)来传递版本信息。这种方式要求编写一个自定义中间件,拦截请求并解析 Header 中的版本号,然后将版本信息注入到 request.state 中,供后续的路由处理器使用。这样做的好处是 URL 保持干净,版本信息隐藏在头部。开发者需要在中间件中检查是否存在该 Header,如果存在则提取值,否则使用默认版本。路由处理器可以通过 request.state.api_version 获取当前请求的版本号,从而执行不同的逻辑。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import JSONResponse
from starlette.types import ASGIApp, Receive, Scope, Send
import asyncio
class VersionMiddleware:
def __init__(self, app: ASGIApp, default_version: str = "v1"):
self.app = app
self.default_version = default_version
async def __call__(self, scope: Scope, receive: Receive, send: Send):
if scope["type"] != "http":
await self.app(scope, receive, send)
return
# 从 headers 中获取 API 版本
headers = dict(scope["headers"])
api_version_header = headers.get(b"x-api-version", None)
# 设置版本到 state,如果没有则使用默认值
version = api_version_header.decode() if api_version_header else self.default_version
# 修改 scope 以传递版本信息
scope["path_params"]["api_version"] = version
await self.app(scope, receive, send)
async def handle_api(request):
version = request.path_params.get("api_version", "unknown")
return JSONResponse({"version": version, "message": f"Handled by {version}"})
app = Starlette(
routes=[
Route("/{api_version}/data", endpoint=handle_api),
],
middleware=[VersionMiddleware],
)
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
在这个示例中,中间件 VersionMiddleware 负责解析 X-API-Version 头。如果请求头中包含 X-API-Version: v2,则 request.path_params["api_version"] 将被设置为 v2。路由处理器 handle_api 接收这个参数并返回相应的响应。如果未提供 Header,则默认为 v1。预期结果:发送带有 X-API-Version: v2 的请求到 /v2/data(注意:这里路由匹配的是 /{api_version}/data,所以实际路径需配合 Header 使用,或者更常见的是固定路径如 /data 并通过 Header 区分,此处为了演示中间件注入 path_params 使用了动态路径,实际生产中通常固定路径如 /data 并在中间件设置 request.state.version)。修正后的更典型用法是固定路径 /data,中间件设置 request.state.version,处理器读取 request.state.version。但为了保持代码简洁且符合 Starlette 的 path_params 机制,上述代码展示了如何将版本作为路径参数的一部分。若改为固定路径,代码应调整为:Route("/data", endpoint=handle_api) 且中间件中 scope["path_params"]["api_version"] = version 依然有效,因为 path_params 是字典,可以动态添加键值对。此时访问 /data 并带 Header X-API-Version: v2,返回 {"version": "v2", ...}。
当路由参数冲突时如何处理版本优先级
在实际开发中,可能会遇到不同版本的路由定义存在重叠或冲突的情况,例如 /v1/users 和 /v2/users 都指向类似的处理逻辑,或者某个通用路由 /users 与版本化路由并存。Starlette 的路由匹配是按注册顺序进行的,先注册的路由优先匹配。因此,如果同时定义了 Router(prefix="/v1", ...) 和 Router(prefix="/v2", ...),以及一个无前缀的 Route("/users", ...),那么对于 /users 的请求,会匹配到无前缀的那个路由,而不会进入任何版本化路由。为了避免这种歧义,建议将所有版本化路由放在前面,或者明确区分版本路径和非版本路径。如果确实需要在一个路由中根据版本执行不同逻辑,可以使用中间件注入版本信息,然后在单一路由处理器中进行分支判断。这种情况下,路由本身不区分版本,而是由业务逻辑内部处理版本差异。例如,定义一个 /users 路由,中间件设置 request.state.version,处理器根据 request.state.version 返回不同格式的数据。这样可以避免路由配置的复杂性,但增加了处理器的耦合度。选择哪种方式取决于项目的规模和团队规范。对于小型项目,URL 前缀法更清晰;对于大型项目,Header 法更灵活,便于未来扩展。










