template/USAGE.md

模板使用说明

模板特性

本模板基于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. 复制模板

cp -r template my_new_project
cd my_new_project

2. 运行初始化（推荐）

python scripts/init_project.py

脚本会自动：

• 生成SECRET_KEY
• 创建.env文件
• 创建必要目录
• 可选：重命名应用目录

3. 手动配置（如果未使用脚本）

# 创建虚拟环境
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. 初始化数据库

flask db init
flask db migrate -m "Initial migration"
flask db upgrade

5. 运行项目

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:

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 注册：

from src.your_app.routes.api import api_bp
app.register_blueprint(api_bp)

添加模型

1. 在 src/your_app/models/ 创建新文件，例如 user.py:

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 导入：

from .user import User

__all__ = ['db', 'User']

3. 创建迁移：

flask db migrate -m "Add User model"
flask db upgrade

添加服务

在 src/your_app/services/ 创建业务逻辑：

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

环境配置

开发环境

export FLASK_ENV=development
python run_dev.py

• 启用调试模式
• 使用开发数据库
• 详细错误信息

生产环境

export FLASK_ENV=production
gunicorn -c gunicorn.conf.py "src.your_app:create_app()"

• 关闭调试模式
• 使用生产数据库
• 安全配置

测试环境

export FLASK_ENV=testing
pytest

• 使用内存数据库
• 关闭CSRF保护
• 快速测试

常见任务

运行测试

pip install -r requirements/test.txt
pytest
pytest --cov=src tests/  # 带覆盖率

代码检查

pip install -r requirements/development.txt
flake8 src/
pylint src/
black src/  # 格式化
isort src/  # 排序导入

数据库操作

# 创建迁移
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 了解完整文档
• 查看 QUICK_START.md 快速开始
• 查看 PROJECT_STRUCTURE.md 了解项目结构
• 查看 docs/ 目录了解详细文档