# 数据库会话

:::tip 说明
项目通过 Flask 的 `g` 对象和 `before_request` / `after_request` 钩子实现请求级数据库会话管理，写操作按业务成功与否自动 commit/rollback。核心代码位于 `src/core/database.py` 和 `src/middleware/transaction.py`。
:::

## 核心架构

数据库会话管理位于 `src/core/database.py` 和 `src/middleware/transaction.py`。

### SQLAlchemy + Flask-SQLAlchemy

项目使用 Flask-SQLAlchemy 扩展，通过 `db` 对象管理数据库会话：

```python
# src/core/database.py
from flask_sqlalchemy import SQLAlchemy

# 创建 Flask-SQLAlchemy 实例
db = SQLAlchemy()
```

在 `src/app.py` 的 `create_app()` 中初始化：

```python
def create_app():
    app = Flask(__name__)
    # 配置数据库 URI
    app.config['SQLALCHEMY_DATABASE_URI'] = DB_URL
    # 初始化 SQLAlchemy
    db.init_app(app)
    return app
```

业务代码通过 `db.session` 获取请求级会话：

```python
from src.core.database import db

# 添加记录
db.session.add(obj)
db.session.flush()  # 发送 SQL，获取自增 ID，不提交

# 查询
result = db.session.query(Model).filter(...).all()
```

### Flask g 对象

Flask 的 `g` 对象是请求级别的全局变量，每个请求都有独立的 `g` 对象：

```python
from flask import g

# 在请求开始时设置
g.user_id = 1

# 在请求处理过程中获取
user_id = g.user_id
```

## 会话中间件

`src/middleware/transaction.py` 中的中间件负责会话的创建、提交和关闭：

```python
from flask import request, g
from src.core.database import db

def register_transaction(app):
    """注册 AOP 事务管理中间件"""

    @app.before_request
    def _transaction_begin():
        """请求开始前：标记事务活跃"""
        g.transaction_active = True

    @app.after_request
    def _transaction_commit(response):
        """请求结束后：根据响应状态决定提交或回滚"""
        if request.method in ('POST', 'PUT', 'DELETE', 'PATCH'):
            if response.status_code == 200:
                try:
                    body = response.get_json()
                    if body and body.get('code') == 0:
                        # 业务成功：提交事务
                        db.session.commit()
                    else:
                        # 业务失败：回滚事务
                        db.session.rollback()
                except Exception:
                    db.session.rollback()
            else:
                # HTTP 非 200：回滚事务
                db.session.rollback()
        return response

    @app.teardown_request
    def _transaction_rollback(exception):
        """请求异常时：回滚事务"""
        if exception:
            db.session.rollback()
        # 移除会话
        db.session.remove()
```

### 业务成功判断

中间件通过响应体 JSON 的 `code` 字段判断业务是否成功：

```python
def _is_business_success(body: dict) -> bool:
    """仅当响应体为 JSON 且业务码 code == 0 视为成功"""
    if not body:
        return False
    if not isinstance(body, dict):
        return False
    return body.get('code') == 0
```

## 独立提交

`commit_independently()` 函数用于审计日志等需要无论业务成功与否都持久化的场景：

```python
from src.core.database import db

def commit_independently(obj):
    """
    使用独立session提交对象，不受请求事务影响

    日志等审计数据无论业务成功或失败都应持久化，
    因此需要绕过 AOP 事务中间件的 commit/rollback 机制。
    """
    independent_session = db.session_factory()
    try:
        independent_session.add(obj)
        independent_session.commit()
    except Exception:
        independent_session.rollback()
        raise
    finally:
        independent_session.close()
```

:::warning 使用场景
`commit_independently()` 创建独立会话，不受请求级事务影响。适用于操作日志、登录日志等审计数据的持久化。普通业务数据应使用 `db.session` 获取请求级会话，由中间件统一管理事务。
:::

## 会话生命周期

```
请求进入
 → before_request 标记事务活跃
 → 业务代码通过 db.session 获取会话
 → after_request 根据响应码 commit/rollback
 → teardown_request 异常时 rollback 并移除会话
```

## 中间件注册顺序

在 `src/app.py` 的 `create_app()` 中，按以下顺序初始化：

```python
def create_app():
    app = Flask(__name__)

    # 1. 加载配置（数据库、Redis 等）
    app.config.from_object(DatabaseConfig)

    # 2. 配置 CORS 跨域
    CORS(app, ...)

    # 3. 可信代理配置（ProxyFix）
    app.wsgi_app = ProxyFix(app.wsgi_app, ...)

    # 4. 注册操作日志中间件（须在事务拦截器之前）
    register_operation_log(app)

    # 5. 注册 AOP 事务拦截器
    register_transaction(app)

    # 6. 注册 API v1 路由
    register_v1(app)

    # 7. 初始化扩展（数据库、Redis、调度器等）
    register_extends(app)

    # 8. 注册中间件（登录校验、演示模式、异常处理）
    register_middleware(app)

    # 9. 注入依赖（权限提供方、操作日志写入器）
    _inject_dependencies(app)

    return app
```

`register_operation_log` 在 `register_transaction` 之前，确保操作日志在事务提交前记录。

## BaseDB.save() 方法

`BaseDB` 基类提供的 `save()` 方法只执行 `flush`，不执行 `commit`：

```python
from src.core.database import db
from src.common.base_model import BaseModel

class BaseDB:
    def save(self):
        """保存模型到数据库（仅 flush，不 commit）"""
        db.session.add(self)
        db.session.flush()
        return self

    def delete(self):
        """软删除模型（仅 flush，不 commit）"""
        self.is_delete = 1
        db.session.flush()
```

`flush` 的作用：
1. 将 SQL 语句发送到数据库执行
2. 获取自增 ID 等数据库生成的值
3. 但不提交事务，事务由中间件统一管理

## 注意事项

:::warning 重要提示
1. **不要手动调用 `db.session.commit()`**：事务由中间件统一管理，手动 commit 可能导致事务提前提交
2. **不要手动调用 `db.session.rollback()`**：除非在 `try-except` 块中需要手动回滚
3. **只读操作使用 GET 方法**：GET 请求不会触发事务处理
4. **写操作必须返回 R 对象**：中间件通过 `code` 字段判断是否需要提交
:::

## 总结

数据库会话管理通过 Flask 的 `g` 对象和 `before_request` / `after_request` 钩子实现请求级隔离，中间件自动根据业务响应码 commit/rollback，`commit_independently()` 提供独立事务能力用于审计数据持久化。这种设计确保了事务边界清晰，业务代码无需手动管理事务。