starlette 优雅关闭服务需要利用 lifespan 事件机制,在应用启动时注册信号处理器,并在收到退出信号(如 sigterm)时触发清理逻辑。具体做法是创建一个自定义的 lifespan 函数,监听 "startup" 和 "shutdown" 事件,在 "shutdown" 阶段执行资源释放或等待任务完成的操作,然后将该函数传递给 starlette 实例的 lifespan 参数。

如何配置 Lifespan 以处理退出信号
通过定义一个异步生成器作为 lifespan 事件处理器,可以捕获应用的启动和关闭生命周期。在关闭阶段,可以使用 signal 模块注册回调,或者依赖 ASGI 服务器(如 Uvicorn)传递的关闭信号来触发清理代码的执行。

import asyncio
import signal
from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
import uvicorn
# 全局状态用于模拟正在进行的任务
task_status = {"running": False}
async def lifespan(app):
# 启动阶段
print("Application startup")
yield
# 关闭阶段
print("Application shutdown")
# 在这里执行清理逻辑,例如等待后台任务结束
if task_status["running"]:
await asyncio.sleep(2) # 模拟等待任务完成
print("Cleanup complete")
app = Starlette(lifespan=lifespan)
@app.route("/")
async def homepage(request):
return PlainTextResponse("Hello World")
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
上述代码展示了基本的 lifespan 结构。当服务器接收到终止信号时,ASGI 服务器会调用 lifespan 中的关闭部分。开发者可以在 yield 之后添加任何必要的清理代码,确保服务在退出前完成当前请求或后台任务。
如何在关闭期间阻止新请求并等待现有请求完成
为了实现更精细的控制,可以在关闭阶段设置一个标志位,阻止新的路由处理,同时允许已开始的请求继续执行直到完成。这通常涉及检查应用状态或在中间件中集成关闭逻辑。

Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
import asyncio
from starlette.applications import Starlette
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import JSONResponse
import uvicorn
# 用于控制是否接受新请求的标志
closing_flag = False
async def custom_lifespan(app):
global closing_flag
print("Startup")
yield
print("Shutdown initiated")
closing_flag = True
# 等待所有活跃任务完成
await asyncio.sleep(1)
print("All tasks finished")
app = Starlette(lifespan=custom_lifespan)
class ShutdownMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
global closing_flag
if closing_flag:
return JSONResponse(
status_code=503,
content={"detail": "Service is shutting down"}
)
response = await call_next(request)
return response
app.add_middleware(ShutdownMiddleware)
@app.route("/data")
async def get_data(request):
await asyncio.sleep(0.5) # 模拟耗时操作
return JSONResponse({"data": "result"})
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
在这个示例中,ShutdownMiddleware 检查 closing_flag。如果为真,它返回 503 状态码,拒绝新请求。而已经在处理的请求会继续执行,因为它们在进入中间件时标志尚未设置。这种模式确保了服务的平滑过渡,避免了数据不一致或中断用户操作。
基于信号处理的具体问题:SIGTERM 到达时如何确保后台协程安全退出
当操作系统发送 SIGTERM 信号时,Uvicorn 等服务器会触发 lifespan 的关闭流程。关键在于确保所有后台创建的 Task 或 Coroutine 能够感知到关闭意图并安全退出,而不是被强制杀死导致资源泄漏。
可以通过在 lifespan 关闭阶段收集所有活跃的后台任务,并使用 asyncio.wait_for 或类似机制等待它们完成。如果任务超时,可以选择取消它们。此外,对于长期运行的后台进程,应定期检查一个共享的“停止”事件,以便在收到关闭信号时立即响应。
import asyncio
from starlette.applications import Starlette
import uvicorn
background_tasks = []
stop_event = asyncio.Event()
async def background_worker():
try:
while not stop_event.is_set():
print("Worker running...")
await asyncio.sleep(1)
finally:
print("Worker cleaned up")
async def lifespan(app):
global stop_event
# 启动后台任务
task = asyncio.create_task(background_worker())
background_tasks.append(task)
yield
# 关闭阶段
print("Stopping background workers...")
stop_event.set() # 通知 worker 停止
# 等待所有后台任务完成
if background_tasks:
await asyncio.gather(*background_tasks, return_exceptions=True)
print("Background workers stopped")
app = Starlette(lifespan=lifespan)
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
此代码演示了如何使用 asyncio.Event 来控制后台工作流的停止。在 lifespan 的关闭部分,设置 stop_event 后,等待所有关联的任务自然结束。这种方法比直接取消任务更安全,因为它允许任务进行最后的清理工作。










