flask

---
name: flask
description: Flask开发专家助手。当用户需要进行Flask轻量级Web开发、REST API、微服务或Python Web应用时调用。
license: MIT
---

# 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 管理跨域