# 同步架构设计

## 概述

Flask 是一个基于 WSGI 的同步 Web 框架，采用同步编程模型。本文档介绍项目的同步架构设计及其优势。

:::tip 为什么选择同步架构？
1. **成熟稳定**：Flask 的同步模型经过长期验证，稳定可靠
2. **易于理解**：同步编程模型更直观，易于调试和维护
3. **工具完善**：Flask 生态完善，各种扩展和工具支持良好
4. **部署简单**：WSGI 标准，支持多种部署方式
:::

## 同步模型特性

| 特性 | 说明 |
|:-----|:-----|
| 编程模型 | 同步 `def` |
| 并发处理 | 多线程/多进程（由 WSGI 服务器管理） |
| I/O 等待 | 阻塞当前线程，其他线程不受影响 |
| 学习曲线 | 平缓，标准 Python 编程 |
| 调试难度 | 简单，标准 pdb 调试 |
| 生态支持 | 完善，Flask 扩展生态丰富 |

## Flask 同步模型

### 请求处理流程

```
客户端请求
    ↓
WSGI 服务器（Gunicorn）
    ↓
Flask 应用
    ↓
中间件链（before_request）
    ↓
路由分发（Blueprint）
    ↓
视图函数（Router）
    ↓
Service 层
    ↓
Repository 层
    ↓
SQLAlchemy ORM
    ↓
数据库
    ↓
返回响应
```

### 多线程/多进程

Flask 通过 WSGI 服务器（如 Gunicorn）实现并发处理：

```bash
# 使用 Gunicorn 启动，4 个工作进程，每个进程 4 个线程
gunicorn -w 4 -t 4 app:app
```

| 参数 | 说明 |
|:-----|:-----|
| `-w 4` | 4 个工作进程 |
| `-t 4` | 每个进程 4 个线程 |
| `app:app` | Flask 应用实例 |

## 同步代码示例

### Service 层

```python
# src/modules/system/position/service.py
from src.common.base_service import BaseService
from src.core.exceptions import BizError
from src.modules.system.position.schema import PositionForm, PositionStatusForm
from src.modules.system.position.repository import PositionRepository
from src.modules.system.user.repository import UserRepository


class PositionService(BaseService):
    """
    岗位服务类

    所有方法均为同步 classmethod，通过 Repository 访问数据库。
    """
    repository = PositionRepository
    form = PositionForm
    status_form = PositionStatusForm
    model_name = "岗位"

    @classmethod
    def before_delete(cls, ids):
        """删除前校验：检查用户引用"""
        for pid in ids:
            if UserRepository.count_by({'position_id': pid}) > 0:
                raise BizError(f"岗位ID {pid} 已被用户引用，无法删除")
```

### Repository 层

```python
# src/modules/system/position/repository.py
from src.common.base_repository import BaseRepository
from src.common.constants.common import PAGE_SIZE
from src.modules.system.position.models import Position


class PositionRepository(BaseRepository):
    """岗位数据仓储"""
    model = Position

    @classmethod
    def page(cls, params: dict):
        """分页查询：同步调用基类 find_page"""
        return cls.find_page(
            page=int(params.get('pageNo', 1)),
            page_size=int(params.get('pageSize', PAGE_SIZE)),
            filters={'status': params.get('status')},
            like_filters={'name': params.get('name')},
            order_by='sort',
        )

    @classmethod
    def list_enabled(cls, params=None):
        """查询启用的岗位列表"""
        params = params or {}
        return cls.find_list(
            filters={'status': 1},
            like_filters={'name': params.get('name')},
            order_by='sort',
        )
```

## 同步架构优势

### 1. 代码简洁

同步代码更直观，易于理解和维护：

```python
# 同步代码（本项目）
from src.modules.system.position.service import get_position_page

def page():
    """同步调用 service"""
    return R.ok(data=get_position_page(request.args))
```

### 2. 调试简单

同步代码的调试更简单，标准 Python 调试工具直接可用：

```python
# 同步调试：直接使用 pdb
import pdb; pdb.set_trace()
```

### 3. 生态完善

Flask 生态完善，各种扩展支持良好：

| 扩展 | 用途 |
|:-----|:-----|
| Flask-SQLAlchemy | ORM 集成 |
| Flask-Migrate | 数据库迁移 |
| Flask-CORS | 跨域资源共享 |
| Flask-WTF | 表单校验（WTForms 集成） |
| redis-py | Redis 同步客户端 |
| APScheduler | 定时任务调度 |

### 4. 部署简单

WSGI 标准，支持多种部署方式：

```bash
# Gunicorn（推荐）
gunicorn -w 4 -t 4 app:app

# uWSGI
uwsgi --http 0.0.0.0:8021 --wsgi-file app.py --callable app

# Flask 内置服务器（仅开发）
python app.py
```

## 性能优化

### 1. 连接池

SQLAlchemy 使用连接池管理数据库连接：

```python
from sqlalchemy import create_engine

engine = create_engine(
    DB_URL,
    pool_size=10,       # 连接池大小
    max_overflow=20,    # 最大溢出连接数
    pool_recycle=3600,  # 连接回收时间（秒）
)
```

### 2. 缓存

使用 Redis 缓存热点数据：

```python
def get_position_list(self):
    """获取岗位列表（带缓存）"""
    cache_key = "position:list"
    cached = redis.get(cache_key)
    if cached:
        return json.loads(cached)

    # 查询数据库
    positions = cls.repository.find_list(filters={'status': 1})
    result = [p.to_dict() for p in positions]

    # 写入缓存
    redis.set(cache_key, json.dumps(result), ex=3600)
    return result
```

### 3. 定时任务

项目使用 APScheduler 实现定时任务调度，任务定义存储在数据库中：

```python
# src/core/scheduler.py
from apscheduler.schedulers.background import BackgroundScheduler

scheduler = BackgroundScheduler()
```

定时任务在独立线程中执行，不阻塞主请求处理流程。支持 Cron、Interval、Date 三种触发器，通过 Redis 实现多实例互斥，避免重复执行。

## 总结

项目采用 Flask 同步架构，具有成熟稳定、易于理解、工具完善、部署简单等优势。对于后台管理系统这类以 CRUD 为主的场景，同步模型完全够用，代码更简洁，调试更方便。通过连接池、Redis 缓存、APScheduler 定时任务等技术，可以进一步优化性能。