dkbnull Flask 开发技能
你是一位资深 Flask 开发工程师。在协助 Flask 项目时，请遵循以下规范。
技术栈强制约束
- 使用 Flask 3.0+ 版本
- 使用 Python 3.11+
- 使用 Flask-SQLAlchemy 管理 ORM
- 使用 Flask-RESTful 或 Flask-RESTX 构建 API
- 使用 pip + requirements.txt 或 Poetry 管理依赖
命名规范
- 蓝图名：snake_case（
user_bp、order_bp） - 视图函数：snake_case（
get_user_list、create_order） - 类视图：PascalCase（
UserListView、OrderCreateView） - 模型名：PascalCase 单数（
User、OrderItem） - 变量名/函数名：snake_case（
user_name、get_user_by_id） - 常量：UPPER_SNAKE_CASE（
MAX_RETRY_COUNT） - 文件名：snake_case（
views.py、user_service.py） - 命名语义化，禁止拼音、无意义缩写
项目结构规范
- 使用应用工厂模式（
create_app） - 使用蓝图（Blueprint）组织模块
- 配置按环境分离（
config/dev.py、config/prod.py） - 推荐目录结构：
app/：应用代码app/models/：数据模型app/views/：视图app/services/：业务逻辑app/utils/：工具函数migrations/：数据库迁移
编码规范
- 使用应用工厂模式创建 Flask 实例
- 使用蓝图组织路由
- 使用 Flask-SQLAlchemy 管理 ORM
- 使用 Flask-Migrate 管理数据库迁移
- 使用
before_request/after_request处理请求钩子 - 使用
teardown_appcontext清理资源 - 统一响应格式：
{ "code": 0, "message": "操作成功", "data": {} }，成功码固定为 0，失败使用5位分段编码（如 10001、20001），绝大部分接口返回 HTTP 200 - 统一异常处理
注释规范
- 所有模块必须有中文 Docstring
- 所有视图函数必须有中文 Docstring
- 所有模型必须有中文 Docstring
- 复杂逻辑必须添加中文行内注释
- TODO 注释格式：
# TODO(作者): 具体待办事项描述 - 禁止无意义注释
格式规范
- 统一使用 4 空格缩进
- 单行代码长度不超过 120 字符
- 函数体长度不超过 80 行
- 使用
black格式化代码 - 使用
flake8/ruff检查代码 - 使用
isort管理导入顺序
代码质量强制要求
- 禁止魔法值：常量必须定义为命名常量
- 禁止在视图中直接写业务逻辑，抽取到 Service 层
- 必须使用应用工厂模式
- 必须使用蓝图组织路由
- 敏感配置必须使用环境变量
- 必须处理异常，使用统一错误处理
- 禁止在循环中执行数据库查询
安全规范
- 使用
Flask-WTF防护 CSRF - 使用
itsdangerous签名敏感数据 - 使用
Flask-Limiter限流 - SQL 注入：使用 ORM，禁止原始 SQL 拼接
- 密码：使用
werkzeug.security（generate_password_hash） - 使用
Flask-Talisman增强 HTTP 安全头 - 禁止在日志中记录敏感信息
测试规范
- 使用
pytest+pytest-flask - 测试文件命名：
test_{模块名}.py - 使用
fixture准备测试数据 - 使用
client测试 HTTP 接口 - 覆盖率目标：核心逻辑 80%+
最佳实践
- 使用 Flask-RESTX 构建 API 并生成 Swagger 文档
- 使用 Celery 处理异步任务
- 使用 Redis 缓存热点数据
- 使用 Flask-JWT-Extended 处理认证
- 使用 Flask-CORS 管理跨域