FastAPI会话工厂模式：优化数据库连接管理

1. 为什么需要会话工厂模式

在FastAPI项目中处理用户会话时，直接使用原始session对象会遇到几个典型问题。首先是会话初始化代码重复，每个路由都需要编写相同的session创建和关闭逻辑。其次是事务管理困难，当多个操作需要原子性执行时，缺乏统一的事务边界控制。最后是异常处理分散，每个路由都需要单独处理数据库异常。

会话工厂模式通过封装会话生命周期管理，提供了一种更优雅的解决方案。它本质上是一个生成和管理数据库会话的上下文管理器，主要解决以下问题：

• 资源泄漏风险：确保会话在使用后正确关闭，避免连接未释放
• 事务一致性：提供统一的事务提交/回滚控制点
• 代码复用：集中处理会话配置和异常处理逻辑
• 测试便利：可以轻松替换为测试用的会话实现

在FastAPI中实现会话工厂时，通常会结合SQLAlchemy的sessionmaker。下面是一个典型的问题场景：假设有一个用户注册接口，需要同时写入users表和profiles表。没有会话工厂时，代码可能长这样：

python复制@app.post("/register")
async def register(user_data: UserCreate):
    session = SessionLocal()
    try:
        user = User(**user_data.dict())
        session.add(user)
        session.flush()  # 需要先flush获取user.id
        
        profile = Profile(user_id=user.id)
        session.add(profile)
        session.commit()
    except Exception as e:
        session.rollback()
        raise HTTPException(status_code=400, detail=str(e))
    finally:
        session.close()

这种写法在每个路由中重复了会话管理代码，且事务边界不清晰。通过会话工厂重构后，代码可以简化为：

python复制@app.post("/register")
async def register(user_data: UserCreate, db: Session = Depends(get_db)):
    user = User(**user_data.dict())
    db.add(user)
    db.flush()
    
    profile = Profile(user_id=user.id)
    db.add(profile)
    # 不需要手动commit/rollback/close

2. FastAPI会话工厂的核心实现

2.1 基础会话工厂实现

一个完整的FastAPI会话工厂通常包含以下组件：

1. 数据库连接配置：通过环境变量或配置类管理连接字符串
2. 引擎创建：使用create_engine配置连接池等参数
3. 会话工厂函数：生成可复用的sessionmaker实例
4. 依赖项注入：创建FastAPI的Depends可调用对象

具体实现代码如下：

python复制from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "postgresql://user:password@localhost/dbname"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    pool_size=20,
    max_overflow=0,
    pool_pre_ping=True
)

SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine
)

Base = declarative_base()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

关键配置参数说明：

• pool_size：连接池保持的常驻连接数
• max_overflow：允许超出pool_size的临时连接数
• pool_pre_ping：每次从连接池取连接时检查有效性
• autocommit=False：禁用自动提交，使用显式事务
• autoflush=False：禁用自动flush，避免意外查询触发flush

2.2 集成到FastAPI应用

将会话工厂集成到FastAPI需要以下步骤：

1. 在应用启动时创建数据库表（可选）：

python复制@app.on_event("startup")
def startup():
    Base.metadata.create_all(bind=engine)

2. 将会话工厂作为依赖项注入路由：

python复制from fastapi import Depends

@app.get("/users/{user_id}")
async def read_user(user_id: int, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

3. 在路由中直接使用db会话，无需关心生命周期管理

2.3 事务管理增强

基础实现已经处理了会话关闭，但对于复杂业务场景，可能需要更精细的事务控制。以下是几种增强方案：

方案1：自动提交装饰器

python复制from contextlib import contextmanager

@contextmanager
def transaction(db: Session):
    try:
        yield db
        db.commit()
    except Exception:
        db.rollback()
        raise

@app.post("/users")
async def create_user(user: UserCreate, db: Session = Depends(get_db)):
    with transaction(db):
        db_user = User(**user.dict())
        db.add(db_user)

方案2：中间件统一管理

python复制@app.middleware("http")
async def db_session_middleware(request: Request, call_next):
    response = Response("Internal server error", status_code=500)
    try:
        request.state.db = SessionLocal()
        response = await call_next(request)
        request.state.db.commit()
    except Exception as e:
        request.state.db.rollback()
        raise
    finally:
        request.state.db.close()
    return response

3. 生产环境最佳实践

3.1 连接池优化配置

生产环境中，数据库连接池配置对性能影响很大。推荐配置：

python复制engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    pool_size=20,  # 常规并发量下的合理值
    max_overflow=10,  # 突发流量缓冲
    pool_recycle=3600,  # 1小时回收连接
    pool_pre_ping=True,  # 检查连接有效性
    pool_timeout=30,  # 获取连接超时时间
    connect_args={
        "connect_timeout": 5,  # 连接超时
        "keepalives": 1,  # TCP keepalive
        "keepalives_idle": 30,  # 空闲keepalive间隔
    }
)

3.2 多数据库支持

大型项目可能需要连接多个数据库。可以通过路由会话实现：

python复制from sqlalchemy.orm import Session

class RoutingSession(Session):
    def get_bind(self, mapper=None, clause=None):
        if mapper and issubclass(mapper.class_, LogRecord):
            return log_engine
        return main_engine

SessionLocal = sessionmaker(class_=RoutingSession)

3.3 异步会话支持

FastAPI天生支持异步，配合SQLAlchemy 2.0+的异步支持：

python复制from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession

async_engine = create_async_engine(
    "postgresql+asyncpg://user:password@localhost/dbname",
    pool_size=20,
    max_overflow=10,
)

AsyncSessionLocal = sessionmaker(
    async_engine,
    class_=AsyncSession,
    expire_on_commit=False
)

async def get_async_db():
    async with AsyncSessionLocal() as db:
        yield db

3.4 测试环境隔离

测试时需要隔离数据库访问，可以通过可替换的会话工厂实现：

python复制def get_test_db():
    test_engine = create_engine("sqlite:///:memory:")
    TestingSessionLocal = sessionmaker(bind=test_engine)
    db = TestingSessionLocal()
    try:
        yield db
    finally:
        db.close()

app.dependency_overrides[get_db] = get_test_db

4. 常见问题与调试技巧

4.1 会话状态管理

常见问题：对象状态不一致导致意外行为。解决方案：

python复制# 强制刷新对象状态
db.refresh(user)

# 分离对象避免意外修改
db.expunge(user)

# 检查对象状态
from sqlalchemy import inspect
insp = inspect(user)
print(insp.transient)  # 新对象未保存
print(insp.pending)    # 已add但未flush
print(insp.persistent) # 已存入数据库
print(insp.detached)   # 会话关闭后的状态

4.2 性能优化技巧

1. 批量操作：使用bulk_insert_mappings提高插入性能

python复制db.bulk_insert_mappings(User, [dict(name=f"user{i}") for i in range(1000)])

2. 只读查询优化：

python复制# 使用yield_per分批获取
for user in db.query(User).yield_per(100):
    process(user)

# 禁用变更跟踪
with db.no_autoflush:
    # 查询操作不会触发flush
    users = db.query(User).all()

3. 连接泄漏检测：

python复制# 在测试中检查会话是否关闭
@pytest.fixture
def db_session():
    session = SessionLocal()
    yield session
    session.close()
    assert session.in_transaction() is False

4.3 分布式事务处理

在微服务架构下，需要考虑分布式事务：

python复制from sqlalchemy import two_phase

engine = create_engine(
    "postgresql://...",
    connect_args={"twophase": True}
)

# 使用两阶段提交
try:
    db.execute(text("PREPARE TRANSACTION 'txn1'"))
    # 调用其他服务
    db.execute(text("COMMIT PREPARED 'txn1'"))
except:
    db.execute(text("ROLLBACK PREPARED 'txn1'"))
    raise

4.4 监控与日志

添加SQL日志和性能监控：

python复制import logging

logging.basicConfig()
logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)

# 慢查询日志
from sqlalchemy import event

@event.listens_for(engine, "before_cursor_execute")
def before_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    conn.info.setdefault('query_start_time', []).append(time.time())

@event.listens_for(engine, "after_cursor_execute")
def after_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    total = time.time() - conn.info['query_start_time'].pop(-1)
    if total > 0.5:  # 500ms视为慢查询
        logger.warning(f"Slow query: {statement} took {total:.3f}s")

在实际项目中，我通常会将会话工厂进一步封装，添加以下增强功能：

• 请求级别的缓存机制，避免重复查询
• 自动重试失败的事务
• 查询超时控制
• 读写分离支持

这些扩展可以根据项目需求逐步引入，避免过早优化。最重要的是保持会话管理的一致性和可靠性，这是FastAPI后端稳定性的基础保障。