# 企业级 Flask 项目模板

**Repository Path**: kkacdbdk/flask_template_for_business

## Basic Information

- **Project Name**: 企业级 Flask 项目模板
- **Description**: 企业级 Flask 项目模板。涵盖生产、开发、测试三种环境。内置集成 JWT。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-10
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flask 企业级后端

一套功能完备的 Flask 后端系统，集成 MySQL 数据库、Redis 缓存、消息队列与 JWT 认证。

## 功能特性

- 🔐 **认证与授权**
  - 基于 JWT 的身份认证
  - 用户注册与登录
  - 密码重置功能
  - 账号锁定保护
  - 基于角色的访问控制

- 🗄️ **数据库**
  - MySQL 数据库 + SQLAlchemy ORM
  - 使用 Flask-Migrate 进行数据库迁移
  - 连接池与会话管理
  - 高级 CRUD 操作

- ⚡ **缓存**
  - Redis 缓存层
  - 连接池
  - 支持多种数据类型
  - 缓存过期管理

- 📨 **消息队列**
  - 集成 Celery 异步任务
  - 任务路由与重试机制
  - 后台作业处理
  - 邮件队列支持

- 🔒 **安全**
  - 使用 bcrypt/Argon2 进行密码哈希
  - 速率限制
  - CORS 保护
  - 输入验证与清洗

- 📊 **监控与日志**
  - 请求/响应日志
  - 错误追踪
  - 性能监控
  - 结构化日志

## 项目结构

```
flask_project/
├── app/
│   ├── __init__.py          # Flask 应用工厂
│   ├── models/              # 数据库模型
│   │   ├── base.py         # 基类模型
│   │   └── user.py         # 用户模型
│   ├── api/                # API 蓝图
│   │   ├── auth/           # 认证接口
│   │   └── users/          # 用户管理接口
│   ├── services/           # 业务逻辑
│   ├── utils/              # 工具类
│   └── middleware/         # 请求中间件
├── config/                 # 配置文件
├── migrations/             # 数据库迁移
├── tests/                  # 测试套件
├── scripts/                # 实用脚本
├── logs/                   # 应用日志
└── requirements.txt        # 依赖列表
```

## 安装步骤

1. **克隆仓库：**
   ```bash
   git clone <仓库地址>
   cd flask_project
   ```

2. **创建虚拟环境：**
   ```bash
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   ```

3. **安装依赖：**
   ```bash
   pip install -r requirements.txt
   ```

4. **配置环境变量：**
   ```bash
   cp .env.example .env
   # 编辑 .env 填入你的配置
   ```

5. **初始化数据库：**
   ```bash
   python scripts/setup_db.py
   ```

6. **执行数据库迁移：**
   ```bash
   flask db upgrade
   ```

## 配置说明

### 环境变量

将 `.env.example` 复制为 `.env` 并填写以下内容：

```env
# Flask 配置
FLASK_ENV=development
SECRET_KEY=你的密钥

# 数据库配置
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_DATABASE=flask_enterprise_dev
MYSQL_USERNAME=root
MYSQL_PASSWORD=你的密码

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=你的 Redis 密码

# JWT 配置
JWT_SECRET_KEY=你的 JWT 密钥
```

### 数据库初始化

1. **创建 MySQL 数据库：**
   ```sql
   CREATE DATABASE flask_enterprise_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

2. **运行迁移：**
   ```bash
   flask db init  # 仅新项目需要
   flask db migrate -m "Initial migration"
   flask db upgrade
   ```

## 启动应用

### 开发服务器

```bash
# 使用 Flask 开发服务器
python run.py

# 或使用 Flask CLI
flask run --host=0.0.0.0 --port=5000
```

### 生产部署

```bash
# 使用 Gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app

# 使用 uWSGI
uwsgi --http :5000 --module wsgi:app
```

### 后台 Worker（Celery）

```bash
# 启动 Celery worker
celery -A app.utils.message_queue worker --loglevel=info

# 启动 Celery beat 定时任务
celery -A app.utils.message_queue beat --loglevel=info
```

## API 接口

### 认证模块

- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/logout` - 用户登出
- `POST /api/auth/refresh` - 刷新令牌
- `GET /api/auth/verify` - 校验令牌
- `POST /api/auth/password/reset-request` - 申请重置密码
- `POST /api/auth/password/reset` - 重置密码

### 用户管理

- `GET /api/users/` - 获取全部用户（分页）
- `GET /api/users/<id>` - 根据 ID 获取用户
- `GET /api/users/profile` - 获取当前用户资料
- `PUT /api/users/profile` - 更新当前用户资料
- `PUT /api/users/<id>` - 根据 ID 更新用户
- `DELETE /api/users/<id>` - 根据 ID 删除用户

## 使用示例

### 用户注册

```python
import requests

# 注册新用户
response = requests.post('http://localhost:5000/api/auth/register', json={
    'username': 'johndoe',
    'email': 'john@example.com',
    'password': 'SecurePass123!',
    'first_name': 'John',
    'last_name': 'Doe'
})

tokens = response.json()['data']['tokens']
access_token = tokens['access_token']
```

### 用户登录

```python
# 登录
response = requests.post('http://localhost:5000/api/auth/login', json={
    'username_or_email': 'johndoe',
    'password': 'SecurePass123!'
})

tokens = response.json()['data']['tokens']
access_token = tokens['access_token']
```

### 带认证的请求

```python
# 发起需要认证的请求
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get('http://localhost:5000/api/users/profile', headers=headers)

user_profile = response.json()['data']
```

## 测试

```bash
# 运行全部测试
pytest

# 带覆盖率
pytest --cov=app --cov-report=html

# 运行指定测试文件
pytest tests/test_auth.py
```

## 安全注意事项

1. **环境变量**：切勿将敏感数据提交到版本库
2. **密钥**：生产环境请使用强度足够的随机密钥
3. **数据库**：生产环境请使用 SSL 连接
4. **Redis**：为 Redis 设置密码并做好网络隔离
5. **CORS**：生产环境请正确配置 CORS 域名
6. **速率限制**：根据业务需求调整速率限制
7. **日志**：禁止记录密码等敏感信息

## 性能优化

1. **数据库**：使用连接池与 SQL 优化
2. **Redis**：合理配置内存与淘汰策略
3. **缓存**：针对热点数据增加缓存
4. **异步任务**：耗时操作交予 Celery
5. **CDN**：生产环境静态资源使用 CDN

## 监控

1. **日志**：查看 `logs/` 目录
2. **健康检查**：实现健康检查端点
3. **指标**：可接入 Prometheus 指标
4. **错误追踪**：集成错误追踪服务

## 贡献指南

1. Fork 本仓库
2. 创建功能分支
3. 提交修改
4. 为新功能编写测试
5. 运行测试套件
6. 提交 Pull Request

## 许可证

MIT 许可证，详见 LICENSE 文件。

## 技术支持

如有问题，请在仓库提交 Issue 或联系开发团队。