3. 技术栈选型与项目初始化
贷后预警系统对实时性、数据一致性及长期维护成本有较高要求。技术栈选型需在开发效率、运行性能与生态成熟度之间取得平衡。本节从 Web 框架、数据库及项目结构三个维度展开对比与决策。
3.1 Web 框架对比：FastAPI vs Flask vs Django
贷后预警 API 的核心场景是高频数据查询、规则引擎触发及异步任务调度。三个主流 Python 框架在异步支持、性能与复杂度上差异明显。
| 维度 | FastAPI | Flask | Django |
|---|---|---|---|
| 异步原生支持 | 原生 async/await，Starlette 底层 | 需扩展（Quart / gevent） | 3.1+ 支持异步视图，生态未完全迁移 |
| 性能（请求/秒） | ~12,000（Uvicorn） | ~3,500（Gunicorn） | ~4,200（Gunicorn） |
| 自动 API 文档 | Swagger / ReDoc 自动生成 | 需手动集成 flasgger | 需第三方包 drf-yasg |
| 数据校验 | Pydantic v2，编译级校验 | 需手动或 marshmallow | DRF Serializer，较重 |
| 依赖注入 | 内置 Depends 系统 | 无原生支持 | 无原生支持 |
| 学习曲线 | 中等（类型注解 + 异步） | 低 | 高（全栈框架） |
| 适用场景 | 高并发 API、微服务、实时预警 | 轻量原型、简单服务 | 大型全栈应用、管理后台 |
选型结论：贷后预警 API 采用 FastAPI。其原生异步能力可支撑大量并发预警查询，Pydantic 校验保障数据质量，自动文档降低前后端联调成本。Flask 在异步与性能上不足，Django 过于厚重，不适合纯 API 场景。
3.2 数据库选型：PostgreSQL vs MySQL
贷后预警系统涉及大量时间序列数据、JSON 格式的预警规则配置以及复杂关联查询。数据库选型直接影响查询性能与数据完整性。
| 维度 | PostgreSQL | MySQL 8.0+ |
|---|---|---|
| JSON 支持 | 原生 JSONB，支持索引与 GIN 索引 | JSON 类型，索引能力较弱 |
| 窗口函数 | 丰富且成熟 | 8.0+ 支持，部分函数缺失 |
| 并发控制 | MVCC 实现优秀，无读锁 | MVCC，但 RR 级别下间隙锁较多 |
| 扩展性 | 支持分区表、并行查询、FDW | 分区表较晚支持，并行查询有限 |
| 数据类型 | 数组、范围、网络、UUID 等丰富 | 基础类型为主 |
| 复制与高可用 | 流复制、逻辑复制成熟 | 主从复制、Group Replication |
| 生态工具 | pg_stat_statements、pgBadger | Performance Schema、sys |
推荐：PostgreSQL 15+。贷后预警的规则配置常以 JSONB 存储，PostgreSQL 的 GIN 索引可将 JSON 查询加速 10 倍以上；窗口函数用于计算逾期天数、滚动风险评分等场景，语法简洁且性能稳定。
3.3 项目目录结构搭建
采用分层架构 + 领域驱动的目录组织方式，兼顾代码可读性与部署便利性。以下为推荐结构：
loan_early_warning/
├── app/ # 应用主目录
│ ├── __init__.py
│ ├── main.py # FastAPI 应用入口
│ ├── core/ # 核心配置与工具
│ │ ├── config.py # 环境变量与配置管理
│ │ ├── database.py # 数据库连接与会话管理
│ │ ├── security.py # 认证与授权
│ │ └── logger.py # 日志配置
│ ├── models/ # SQLAlchemy ORM 模型
│ │ ├── __init__.py
│ │ ├── loan.py # 贷款主表
│ │ ├── customer.py # 客户信息
│ │ ├── warning_rule.py # 预警规则
│ │ └── warning_record.py # 预警记录
│ ├── schemas/ # Pydantic 请求/响应模型
│ │ ├── __init__.py
│ │ ├── loan.py
│ │ ├── warning.py
│ │ └── common.py # 通用分页、状态码
│ ├── api/ # 路由层
│ │ ├── __init__.py
│ │ ├── v1/ # API 版本控制
│ │ │ ├── __init__.py
│ │ │ ├── loans.py # 贷款相关接口
│ │ │ ├── warnings.py # 预警相关接口
│ │ │ └── dashboard.py # 仪表盘聚合接口
│ │ └── deps.py # 依赖注入（数据库会话、当前用户）
│ ├── services/ # 业务逻辑层
│ │ ├── __init__.py
│ │ ├── loan_service.py
│ │ ├── warning_engine.py # 预警规则引擎
│ │ └── risk_score.py # 风险评分计算
│ ├── tasks/ # 异步任务（Celery / BackgroundTasks）
│ │ ├── __init__.py
│ │ ├── batch_warning.py # 批量预警扫描
│ │ └── notification.py # 通知推送
│ └── utils/ # 工具函数
│ ├── __init__.py
│ ├── date_utils.py
│ └── encrypt_utils.py
├── tests/ # 测试目录
│ ├── conftest.py # 测试夹具与数据库初始化
│ ├── test_loans.py
│ ├── test_warnings.py
│ └── test_engine.py
├── migrations/ # Alembic 数据库迁移
│ ├── env.py
│ └── versions/
├── scripts/ # 运维与部署脚本
│ ├── init_db.sql
│ └── start.sh
├── .env.example # 环境变量模板
├── docker-compose.yml # 本地开发环境编排
├── Dockerfile
├── requirements.txt
└── README.md
关键设计原则：路由层（api）只做参数校验与响应组装，不包含业务逻辑；服务层（services）封装所有业务规则，可独立测试；模型层（models）与模式层（schemas）分离，避免 ORM 对象直接暴露给前端。
3.4 技术栈架构总览
下图展示贷后预警 API 的核心技术栈分层与数据流向：
3.5 初始化项目实战步骤
- 创建项目目录与虚拟环境
mkdir loan_early_warning && cd loan_early_warning python3.11 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate - 安装核心依赖
pip install fastapi uvicorn[standard] sqlalchemy asyncpg psycopg2-binary pip install alembic redis pydantic-settings python-dotenv pip install pytest httpx # 测试 - 初始化 Alembic 数据库迁移
alembic init migrations # 修改 migrations/env.py 中的数据库 URL alembic revision --autogenerate -m "init" alembic upgrade head - 创建 .env 配置文件
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/loan_db REDIS_URL=redis://localhost:6379/0 SECRET_KEY=your-secret-key-here API_V1_PREFIX=/api/v1 - 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
性能基线：初始化完成后，使用
wrk -t4 -c100 -d30s http://localhost:8000/health 测试空接口性能。FastAPI + Uvicorn 在空路由下应达到 10,000+ RPS，若低于 5,000 RPS 需检查 Uvicorn worker 数量与系统 ulimit 设置。