同步架构设计

概述

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

为什么选择同步架构？

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）实现并发处理：

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

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

同步代码示例

Service 层

# 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 层

# 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. 代码简洁

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

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

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

2. 调试简单

同步代码的调试更简单，标准 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 标准，支持多种部署方式：

# 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 使用连接池管理数据库连接：

from sqlalchemy import create_engine

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

2. 缓存

使用 Redis 缓存热点数据：

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 实现定时任务调度，任务定义存储在数据库中：

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

scheduler = BackgroundScheduler()

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

总结

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