starlette 动态添加路由的核心方法是调用 app.router.routes 列表的 append() 方法,将新的 route 或 apiroute 实例直接追加到应用的路由表中。在程序运行期间执行此操作后,新定义的路径会立即生效,后续请求即可匹配到这些动态注册的路由规则。

如何验证动态路由是否成功注册
要确认动态添加的路由已经正确写入 app.router.routes,最直接的方式是在添加后打印该列表的长度和内容。通过检查列表末尾新增的元素,可以确保路由对象被正确实例化且没有发生静默失败。以下代码展示了如何在启动前动态添加一个路径参数路由,并验证其存在性。

from starlette.applications import Starlette
from starlette.routing import Route, PathParameter
from starlette.responses import PlainTextResponse
import asyncio
def show_id(request):
user_id = request.path_params['user_id']
return PlainTextResponse(f'User ID: {user_id}')
# 初始静态路由
def homepage(request):
return PlainTextResponse('Home')
routes = [
Route('/', endpoint=homepage),
]
app = Starlette(routes=routes)
# 动态添加路由
new_route = Route('/users/{user_id}', endpoint=show_id, methods=['GET'])
app.router.routes.append(new_route)
async def main():
# 验证:打印当前所有路由
print(f"Total routes: {len(app.router.routes)}")
for r in app.router.routes:
print(f"- {r.path}")
# 模拟请求测试
from starlette.testclient import TestClient
client = TestClient(app)
response = client.get('/users/42')
print(f"Status: {response.status_code}, Body: {response.text}")
asyncio.run(main())
运行上述代码,控制台输出显示路由总数为 2,且包含 /users/{user_id}。测试客户端成功获取到 User ID: 42,证明动态添加的路由已生效且能正确处理路径参数。
如何处理动态路由中的中间件作用域
当动态添加的路由需要应用特定的中间件逻辑时,需明确中间件的执行顺序。Starlette 的中间件包裹整个应用,因此动态添加的路由会自动继承已注册的中间件链。若需针对特定动态路由跳过某些中间件,通常需要在路由定义中结合自定义逻辑或在中间件内部进行条件判断。以下示例展示了一个简单的认证中间件,并验证动态路由是否受其保护。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.applications import Starlette
from starlette.routing import Route
from starlette.middleware import Middleware
from starlette.responses import PlainTextResponse
from starlette.testclient import TestClient
# 模拟认证中间件
class AuthMiddleware:
def __init__(self, app, required_token='secret'):
self.app = app
self.required_token = required_token
async def __call__(self, scope, receive, send):
if scope['type'] != 'http':
await self.app(scope, receive, send)
return
headers = dict(scope.get('headers', []))
token = headers.get(b'authorization', b'').decode()
if token != self.required_token:
response = PlainTextResponse('Unauthorized', status_code=401)
await response(scope, receive, send)
return
await self.app(scope, receive, send)
# 定义受保护的路由
def protected_data(request):
return PlainTextResponse('Secret Data')
# 初始路由
routes = [Route('/public', lambda r: PlainTextResponse('Public'))]
app = Starlette(
routes=routes,
middleware=[Middleware(AuthMiddleware)]
)
# 动态添加受保护的路由
protected_route = Route('/private', endpoint=protected_data)
app.router.routes.append(protected_route)
# 测试
client = TestClient(app)
print(client.get('/public').text) # Public
print(client.get('/private').status_code) # 401
print(client.get('/private', headers={'authorization': 'secret'}).text) # Secret Data
测试结果显示,未携带正确 Token 的请求访问 /private 返回 401,而携带正确 Token 则返回数据。这表明动态添加的路由自动融入了现有的中间件处理流程,无需额外配置即可享受相同的安全策略。
动态添加路由时如何处理重复路径冲突
如果在运行时尝试添加一个与现有路由路径完全相同的 Route,Starlette 不会自动覆盖或报错,而是会将新路由追加到列表末尾。由于 Starlette 按列表顺序匹配路由,先注册的路由优先响应,后添加的同路径路由将无法被触发,形成“死路由”。为避免此类问题,应在添加前检查路径是否存在,或设计唯一的路由命名空间。以下代码演示了检测并替换已有路由的逻辑。
from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import PlainTextResponse
def old_handler(request):
return PlainTextResponse('Old')
def new_handler(request):
return PlainTextResponse('New')
routes = [Route('/api/data', endpoint=old_handler)]
app = Starlette(routes=routes)
# 尝试动态添加同路径路由
new_route = Route('/api/data', endpoint=new_handler)
# 检查并替换
found_index = None
for i, r in enumerate(app.router.routes):
if r.path == new_route.path and r.methods == new_route.methods:
found_index = i
break
if found_index is not None:
app.router.routes[found_index] = new_route
else:
app.router.routes.append(new_route)
from starlette.testclient import TestClient
client = TestClient(app)
print(client.get('/api/data').text) # New
通过遍历 app.router.routes 查找匹配项并替换,确保了 /api/data 最终指向 new_handler,输出结果为 New。这种手动管理方式避免了因路由顺序导致的意外行为,适用于需要热更新路由映射的场景。


















