291 lines
5.6 KiB
Markdown
291 lines
5.6 KiB
Markdown
# 模板使用说明
|
||
|
||
## 模板特性
|
||
|
||
本模板基于aitsc项目的最佳实践，抽取了以下核心特性：
|
||
|
||
### ✅ 已实现的功能
|
||
|
||
1. **标准化项目结构**
|
||
- 清晰的目录组织（src/、config/、tests/等）
|
||
- 模块化设计，易于扩展
|
||
|
||
2. **多环境配置管理**
|
||
- 支持development/production/testing/local四种环境
|
||
- 通过环境变量自动选择配置
|
||
- 配置继承机制，减少重复
|
||
|
||
3. **依赖分类管理**
|
||
- base.txt: 核心依赖
|
||
- development.txt: 开发工具
|
||
- production.txt: 生产服务器
|
||
- test.txt: 测试框架
|
||
|
||
4. **应用工厂模式**
|
||
- 灵活的Flask应用创建方式
|
||
- 支持测试和不同环境
|
||
|
||
5. **数据库迁移支持**
|
||
- 使用Flask-Migrate管理数据库版本
|
||
- 支持多数据库（SQLite/MySQL/PostgreSQL）
|
||
|
||
6. **环境变量管理**
|
||
- 使用python-dotenv加载.env文件
|
||
- 提供env.example模板
|
||
|
||
7. **完整的测试框架**
|
||
- pytest配置
|
||
- 测试fixtures
|
||
- 示例测试用例
|
||
|
||
8. **文档结构**
|
||
- API文档模板
|
||
- 开发文档模板
|
||
- 部署文档模板
|
||
|
||
9. **代码质量工具**
|
||
- flake8配置
|
||
- pytest配置
|
||
- 支持代码格式化（Black、isort）
|
||
|
||
10. **生产环境支持**
|
||
- Gunicorn配置
|
||
- 日志系统
|
||
- 错误处理
|
||
|
||
## 使用流程
|
||
|
||
### 1. 复制模板
|
||
|
||
```bash
|
||
cp -r template my_new_project
|
||
cd my_new_project
|
||
```
|
||
|
||
### 2. 运行初始化（推荐）
|
||
|
||
```bash
|
||
python scripts/init_project.py
|
||
```
|
||
|
||
脚本会自动：
|
||
- 生成SECRET_KEY
|
||
- 创建.env文件
|
||
- 创建必要目录
|
||
- 可选：重命名应用目录
|
||
|
||
### 3. 手动配置（如果未使用脚本）
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv .venv
|
||
source .venv/bin/activate # Linux/Mac
|
||
# 或 .venv\Scripts\activate # Windows
|
||
|
||
# 安装依赖
|
||
pip install -r requirements/base.txt
|
||
pip install -r requirements/development.txt
|
||
|
||
# 配置环境变量
|
||
cp env.example .env
|
||
# 编辑.env文件，至少设置SECRET_KEY和DATABASE_URL
|
||
```
|
||
|
||
### 4. 初始化数据库
|
||
|
||
```bash
|
||
flask db init
|
||
flask db migrate -m "Initial migration"
|
||
flask db upgrade
|
||
```
|
||
|
||
### 5. 运行项目
|
||
|
||
```bash
|
||
python run_dev.py
|
||
```
|
||
|
||
## 自定义项目
|
||
|
||
### 重命名应用
|
||
|
||
1. 重命名目录: `src/your_app` -> `src/my_app`
|
||
2. 更新导入路径：
|
||
- `run_dev.py`: `from src.your_app` -> `from src.my_app`
|
||
- `run_production.py`: 同上
|
||
- `gunicorn.conf.py`: `"src.your_app:create_app()"` -> `"src.my_app:create_app()"`
|
||
- `tests/conftest.py`: 同上
|
||
- 所有测试文件中的导入
|
||
|
||
### 添加新功能
|
||
|
||
#### 添加路由
|
||
|
||
1. 在 `src/your_app/routes/` 创建新文件，例如 `api.py`:
|
||
|
||
```python
|
||
from flask import Blueprint, jsonify
|
||
|
||
api_bp = Blueprint('api', __name__, url_prefix='/api/v1')
|
||
|
||
@api_bp.route('/users')
|
||
def get_users():
|
||
return jsonify({'users': []})
|
||
```
|
||
|
||
2. 在 `src/your_app/__init__.py` 注册：
|
||
|
||
```python
|
||
from src.your_app.routes.api import api_bp
|
||
app.register_blueprint(api_bp)
|
||
```
|
||
|
||
#### 添加模型
|
||
|
||
1. 在 `src/your_app/models/` 创建新文件，例如 `user.py`:
|
||
|
||
```python
|
||
from datetime import datetime
|
||
from src.your_app import db
|
||
|
||
class User(db.Model):
|
||
__tablename__ = 'users'
|
||
|
||
id = db.Column(db.Integer, primary_key=True)
|
||
username = db.Column(db.String(80), unique=True, nullable=False)
|
||
email = db.Column(db.String(120), unique=True, nullable=False)
|
||
created_at = db.Column(db.DateTime, default=datetime.utcnow)
|
||
```
|
||
|
||
2. 在 `src/your_app/models/__init__.py` 导入：
|
||
|
||
```python
|
||
from .user import User
|
||
|
||
__all__ = ['db', 'User']
|
||
```
|
||
|
||
3. 创建迁移：
|
||
|
||
```bash
|
||
flask db migrate -m "Add User model"
|
||
flask db upgrade
|
||
```
|
||
|
||
#### 添加服务
|
||
|
||
在 `src/your_app/services/` 创建业务逻辑：
|
||
|
||
```python
|
||
from src.your_app.models import User, db
|
||
|
||
class UserService:
|
||
@staticmethod
|
||
def create_user(username, email):
|
||
user = User(username=username, email=email)
|
||
db.session.add(user)
|
||
db.session.commit()
|
||
return user
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
export FLASK_ENV=development
|
||
python run_dev.py
|
||
```
|
||
|
||
- 启用调试模式
|
||
- 使用开发数据库
|
||
- 详细错误信息
|
||
|
||
### 生产环境
|
||
|
||
```bash
|
||
export FLASK_ENV=production
|
||
gunicorn -c gunicorn.conf.py "src.your_app:create_app()"
|
||
```
|
||
|
||
- 关闭调试模式
|
||
- 使用生产数据库
|
||
- 安全配置
|
||
|
||
### 测试环境
|
||
|
||
```bash
|
||
export FLASK_ENV=testing
|
||
pytest
|
||
```
|
||
|
||
- 使用内存数据库
|
||
- 关闭CSRF保护
|
||
- 快速测试
|
||
|
||
## 常见任务
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
pip install -r requirements/test.txt
|
||
pytest
|
||
pytest --cov=src tests/ # 带覆盖率
|
||
```
|
||
|
||
### 代码检查
|
||
|
||
```bash
|
||
pip install -r requirements/development.txt
|
||
flake8 src/
|
||
pylint src/
|
||
black src/ # 格式化
|
||
isort src/ # 排序导入
|
||
```
|
||
|
||
### 数据库操作
|
||
|
||
```bash
|
||
# 创建迁移
|
||
flask db migrate -m "描述"
|
||
|
||
# 应用迁移
|
||
flask db upgrade
|
||
|
||
# 回滚迁移
|
||
flask db downgrade
|
||
|
||
# 查看迁移历史
|
||
flask db history
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **不要提交敏感信息**
|
||
- `.env` 文件已加入.gitignore
|
||
- 不要将密钥、密码等提交到代码库
|
||
|
||
2. **环境变量必需项**
|
||
- `SECRET_KEY`: Flask密钥（必需）
|
||
- `DATABASE_URL`: 数据库连接（必需）
|
||
- `FLASK_ENV`: 运行环境（可选，默认development）
|
||
|
||
3. **生产环境安全**
|
||
- 必须设置强SECRET_KEY
|
||
- 必须使用非SQLite数据库
|
||
- 必须配置CORS_ORIGINS限制
|
||
- 必须启用HTTPS
|
||
|
||
4. **数据库迁移**
|
||
- 始终使用Flask-Migrate管理数据库变更
|
||
- 不要直接修改数据库结构
|
||
- 迁移文件应该提交到代码库
|
||
|
||
## 获取帮助
|
||
|
||
- 查看 [README.md](README.md) 了解完整文档
|
||
- 查看 [QUICK_START.md](QUICK_START.md) 快速开始
|
||
- 查看 [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) 了解项目结构
|
||
- 查看 [docs/](docs/) 目录了解详细文档
|
||
|