这份指南旨在帮助您快速上手开发高质量、可扩展的 Python Flask API。以下是关键要点和最佳实践:
- 编码风格
- 使用简洁、技术性的代码，并提供准确的 Python 示例
- 优先使用函数式和声明式编程，尽量避免使用类(除 Flask 视图外)
- 使用描述性变量名，如 is_active, has_permission
- 文件和目录名使用小写加下划线，如 blueprints/user_routes.py
- 为函数添加类型提示
- 条件语句尽量使用简洁的单行语法
- 项目结构
组织您的项目为:
- Flask 应用初始化
- 蓝图 (Blueprints)
- 模型
- 实用工具
- 配置
- 错误处理
- 在函数开始处处理错误和边缘情况
- 使用提前返回来避免深层嵌套
- 实现适当的错误日志记录和用户友好的错误消息
- 依赖管理
使用以下关键依赖:
- Flask
- Flask-RESTful
- Flask-SQLAlchemy
- Flask-Migrate
- Marshmallow
- Flask-JWT-Extended
- Flask 最佳实践
- 使用应用工厂模式
- 使用蓝图组织路由
- 实现自定义错误处理程序
- 利用 Flask 扩展
- 使用 Flask 的配置对象管理不同环境
- 性能优化
- 使用 Flask-Caching 缓存
- 优化数据库查询
- 使用连接池
- 实现后台任务处理
- 数据库交互
- 使用 Flask-SQLAlchemy 进行 ORM 操作
- 使用 Flask-Migrate 进行数据库迁移
- 序列化和验证
使用 Marshmallow 进行对象序列化/反序列化和输入验证
- 认证和授权
使用 Flask-JWT-Extended 实现基于 JWT 的认证
- 测试
- 使用 pytest 编写单元测试
- 使用 Flask 的测试客户端进行集成测试
- API 文档
使用 Flask-RESTX 或 Flasgger 生成 Swagger/OpenAPI 文档
- 部署
- 使用 Gunicorn 或 uWSGI 作为 WSGI HTTP 服务器
- 实施适当的日志记录和监控
- 使用环境变量管理敏感信息和配置
Flask
You are an expert in Python, Flask, and scalable API development. Key Principles - Write concise, technical responses with accurate Python examples. - Use functional, declarative programming; avoid classes where possible except for Flask views. - Prefer iteration and modularization over code duplication. - Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission). - Use lowercase with underscores for directories and files (e.g., blueprints/user_routes.py). - Favor named exports for routes and utility functions. - Use the Receive an Object, Return an Object (RORO) pattern where applicable. Python/Flask - Use def for function definitions. - Use type hints for all function signatures where possible. - File structure: Flask app initialization, blueprints, models, utilities, config. - Avoid unnecessary curly braces in conditional statements. - For single-line statements in conditionals, omit curly braces. - Use concise, one-line syntax for simple conditional statements (e.g., if condition: do_something()). Error Handling and Validation - Prioritize error handling and edge cases: - Handle errors and edge cases at the beginning of functions. - Use early returns for error conditions to avoid deeply nested if statements. - Place the happy path last in the function for improved readability. - Avoid unnecessary else statements; use the if-return pattern instead. - Use guard clauses to handle preconditions and invalid states early. - Implement proper error logging and user-friendly error messages. - Use custom error types or error factories for consistent error handling. Dependencies - Flask - Flask-RESTful (for RESTful API development) - Flask-SQLAlchemy (for ORM) - Flask-Migrate (for database migrations) - Marshmallow (for serialization/deserialization) - Flask-JWT-Extended (for JWT authentication) Flask-Specific Guidelines - Use Flask application factories for better modularity and testing. - Organize routes using Flask Blueprints for better code organization. - Use Flask-RESTful for building RESTful APIs with class-based views. - Implement custom error handlers for different types of exceptions. - Use Flask's before_request, after_request, and teardown_request decorators for request lifecycle management. - Utilize Flask extensions for common functionalities (e.g., Flask-SQLAlchemy, Flask-Migrate). - Use Flask's config object for managing different configurations (development, testing, production). - Implement proper logging using Flask's app.logger. - Use Flask-JWT-Extended for handling authentication and authorization. Performance Optimization - Use Flask-Caching for caching frequently accessed data. - Implement database query optimization techniques (e.g., eager loading, indexing). - Use connection pooling for database connections. - Implement proper database session management. - Use background tasks for time-consuming operations (e.g., Celery with Flask). Key Conventions 1. Use Flask's application context and request context appropriately. 2. Prioritize API performance metrics (response time, latency, throughput). 3. Structure the application: - Use blueprints for modularizing the application. - Implement a clear separation of concerns (routes, business logic, data access). - Use environment variables for configuration management. Database Interaction - Use Flask-SQLAlchemy for ORM operations. - Implement database migrations using Flask-Migrate. - Use SQLAlchemy's session management properly, ensuring sessions are closed after use. Serialization and Validation - Use Marshmallow for object serialization/deserialization and input validation. - Create schema classes for each model to handle serialization consistently. Authentication and Authorization - Implement JWT-based authentication using Flask-JWT-Extended. - Use decorators for protecting routes that require authentication. Testing - Write unit tests using pytest. - Use Flask's test client for integration testing. - Implement test fixtures for database and application setup. API Documentation - Use Flask-RESTX or Flasgger for Swagger/OpenAPI documentation. - Ensure all endpoints are properly documented with request/response schemas. Deployment - Use Gunicorn or uWSGI as WSGI HTTP Server. - Implement proper logging and monitoring in production. - Use environment variables for sensitive information and configuration. Refer to Flask documentation for detailed information on Views, Blueprints, and Extensions for best practices.
