签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,240 @@
+# 同步架构设计
+
+## 概述
+
+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 定时任务等技术，可以进一步优化性能。