starlette 实现 api 版本控制的核心做法是自定义路由匹配逻辑,通过解析 url 路径中的版本号前缀(如 /v1/)或 http 请求头(如 accept-version),将请求动态分发到对应的处理函数。具体而言,可以继承 starlette.routing.route 或 apirouter 并重写 match 方法,在匹配阶段提取版本信息并注入到 scope 中,从而让后续中间件或视图函数能感知当前请求的 api 版本。

如何基于 URL 路径前缀区分 API 版本
基于 URL 路径前缀是最直观的版本控制方式,例如访问 /api/v1/users 和 /api/v2/users 分别调用不同版本的逻辑。实现时,可以在 Starlette 的路由表中注册带有正则表达式或路径参数的路由,并在路由匹配成功后,通过中间件或装饰器提取路径中的版本片段,将其存入 request.scope['api_version']。这样,业务逻辑层只需读取该字段即可决定执行哪套代码分支。

from starlette.applications import Starlette
from starlette.routing import Route, Match
from starlette.responses import JSONResponse
import re
class VersionedRoute(Route):
def __init__(self, path, endpoint, name=None, methods=None):
# 假设路径格式为 /api/v{version}/...
# 这里简化处理,实际项目中建议使用更复杂的正则
super().__init__(path, endpoint, name, methods)
self.version_pattern = re.compile(r'/api/v(\d+)/')
def match(self, scope):
# 调用父类匹配获取基础结果
match, child_scope = super().match(scope)
if match == Match.FULL:
# 从原始 path 中提取版本号
version_match = self.version_pattern.search(scope['path'])
if version_match:
child_scope['api_version'] = int(version_match.group(1))
return match, child_scope
async def get_users(request):
version = request.scope.get('api_version', 1)
data = {'users': ['Alice'], 'version': version}
return JSONResponse(data)
app = Starlette(routes=[
VersionedRoute('/api/v{version}/users', get_users),
])
上述代码定义了一个 VersionedRoute,它继承了 Starlette 的 Route 类。在 match 方法中,首先尝试匹配标准路由,如果匹配成功,则进一步从 scope['path'] 中利用正则表达式提取版本号,并将其写入 child_scope。这样,当请求 /api/v1/users 时,get_users 函数可以通过 request.scope['api_version'] 获取到版本号为 1。这种方式简单直接,适合版本迭代较少且结构清晰的场景。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
如何通过中间件统一处理版本路由分发
除了修改路由类,使用中间件也是一种常见的版本控制策略。中间件可以在请求到达具体路由之前,对请求进行预处理。我们可以创建一个中间件,检查请求路径是否包含版本标识,如果有,则根据版本信息重新构造内部路由或直接调用对应的处理函数。这种方法的优势在于可以将版本逻辑与业务逻辑解耦,便于统一管理。

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import JSONResponse
from starlette.requests import Request
class VersionMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
path = request.url.path
# 简单判断路径是否以 /api/v[0-9]+ 开头
import re
match = re.match(r'/api/v(\d+)', path)
if match:
version = int(match.group(1))
request.scope['api_version'] = version
# 可以在这里根据 version 做不同的处理
# 例如:重写 path 去掉版本号部分,以便匹配内部无版本路由
new_path = re.sub(r'/api/v\d+', '/api', path)
request.scope['path'] = new_path
request.scope['raw_path'] = new_path.encode('utf-8')
response = await call_next(request)
return response
# 在应用中使用
app.add_middleware(VersionMiddleware)
这段代码展示了一个名为 VersionMiddleware 的中间件。它在 dispatch 方法中拦截请求,使用正则表达式匹配路径中的版本号。如果匹配成功,它将版本号存入 request.scope,并将路径中的版本号部分移除,替换为统一的 /api 前缀。这样,后续的路由匹配就可以忽略版本号,只关注资源路径。这种方式的灵活性更高,可以轻松支持基于查询参数或 Header 的版本控制,只需修改匹配逻辑即可。
当请求路径中不包含版本号时会发生什么
如果请求路径中不包含版本号,例如直接访问 /api/users,在上述两种实现中会有不同的表现。在 VersionedRoute 方案中,由于正则表达式未匹配到版本号,api_version 不会被写入 scope,此时 get_users 函数中 request.scope.get('api_version', 1) 会返回默认值 1。而在 VersionMiddleware 方案中,由于正则匹配失败,中间件不会修改 scope 或 path,请求将继续按原路径匹配。如果存在对应的无版本路由,则会正常响应;否则可能返回 404 错误。因此,明确默认版本行为至关重要。

















