FastAPI中重量级服务仅单次初始化的最优实现方案咨询

核心思路 #

利用Python模块导入天然单例的特性，配合FastAPI官方推荐的lifespan生命周期事件完成服务初始化，无需手动实现单例、无需挂载到app对象透传参数，完全符合Python和FastAPI开发规范。 #

具体实现步骤 #

1. 统一管理全局服务实例 #

新建独立的services.py文件，定义所有重量级服务的模块级占位变量：

# services.py
from typing import Optional
# 替换为你实际使用的重量级服务类
from third_party import OSSClient, LargeModelClient, DBPool

# 初始为None，应用启动时完成初始化
oss_client: Optional[OSSClient] = None
large_model_client: Optional[LargeModelClient] = None
db_pool: Optional[DBPool] = None

2. 在生命周期事件中完成初始化 #

在FastAPI入口文件中使用lifespan事件，启动阶段初始化所有服务，销毁阶段统一清理资源：

# main.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
import services
from third_party import OSSClient, LargeModelClient, DBPool

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 应用启动逻辑：初始化所有重量级服务
    services.oss_client = OSSClient(access_key="你的密钥", endpoint="服务地址")
    services.large_model_client = LargeModelClient(api_key="接口密钥")
    services.db_pool = DBPool(host="数据库地址", port=3306)
    yield
    # 应用关闭逻辑：统一释放资源
    await services.oss_client.close()
    await services.large_model_client.close()
    await services.db_pool.disconnect()

app = FastAPI(lifespan=lifespan)

如果你使用的是不支持lifespan的旧版本FastAPI，可以替换为startup和shutdown事件，逻辑完全一致。

3. 任意位置调用服务实例 #

不管是路由函数还是普通自定义工具函数，直接导入services.py中的实例即可使用，无需传递任何额外参数：

非路由普通函数使用示例

# 任意自定义工具文件，比如utils/file_handler.py
import services

async def upload_local_file(local_path: str, remote_path: str):
    # 直接调用全局初始化好的服务实例即可
    return await services.oss_client.upload_file(local_path, remote_path)

路由函数使用示例

如果需要适配单元测试的Mock需求，也可以封装为依赖注入函数，完全兼容FastAPI的依赖体系：

# dependencies.py
import services
from fastapi import Depends

async def get_oss_client():
    return services.oss_client

# 路由代码
from fastapi import APIRouter
from dependencies import get_oss_client
from utils.file_handler import upload_local_file

router = APIRouter()

@router.post("/upload")
async def upload_endpoint(file_path: str, oss_client = Depends(get_oss_client)):
    # 两种用法都支持：直接调用工具函数，或者使用依赖注入的实例
    await upload_local_file(file_path, "/test/object.png")
    # await oss_client.upload_file(xxx) 也可以直接用
    return {"status": "success"}

方案优势 #

• 符合官方最佳实践：lifespan是FastAPI当前推荐的生命周期管理方式，替代了旧版的startup/shutdown事件
• 无需手动实现单例：Python模块导入本身就是单例模式，所有位置导入的服务实例都是同一个初始化后的对象
• 易用性高：普通函数不需要透传request、app等多余参数，直接导入即可调用
• 可测试性强：单元测试时只需要Mockservices.py中的变量，或者替换依赖函数的返回值即可，无需修改业务代码
• 资源安全：shutdown阶段可以统一清理服务连接，避免资源泄漏
• 线程/协程安全：所有服务实例初始化后仅做只读调用，不会修改实例属性，不存在并发安全问题

内容的提问来源于stack exchange，提问作者EntGriff