需要轻量级 Python Web 框架构建微服务、REST…

适用于使用 Python 快速构建微服务、REST API、轻量级 Web 应用，需要灵活架构和丰富扩展生态的场景。

适用场景

解决思路

1. 安装 Flask：`pip install flask`；安装常用扩展：`pip install flask flask-restful flask-sqlalchemy flask-login flask-cors`；安装数据库支持：`pip install flask flask-sqlalchemy psycopg2-binary`；安装完整微服务栈：`pip install flask flask-restful marshmallow flask-jwt-extended redis`。
2. 创建最小 Flask 应用：新建 `app.py`，导入 `Flask, jsonify, request`，实例化 `app = Flask(__name__)`；用 `@app.route('/')` 定义路由返回 `jsonify`；用 `@app.route('/api/users/<int:user_id>')` 定义动态路由；用 `methods=['POST']` 和 `request.get_json()` 处理 POST 请求。
3. 运行开发服务器：`python app.py`；或设置环境变量 `export FLASK_APP=app.py`、`export FLASK_ENV=development` 后运行 `flask run`；自定义端口和主机：`flask run --port 8000 --host 0.0.0.0`。
4. 采用应用工厂模式：在 `app/__init__.py` 中定义 `create_app(config_class=Config)`；在函数内创建 `app = Flask(__name__)`，执行 `app.config.from_object(config_class)`；初始化扩展如 `db.init_app(app)`；注册蓝图如 `app.register_blueprint(api_bp, url_prefix='/api')`。
5. 创建扩展实例文件 `app/extensions.py`，实例化 `db = SQLAlchemy()`、`migrate = Migrate()`、`jwt = JWTManager()` 等扩展对象。
6. 创建配置文件 `app/config.py`，定义 `Config`、`DevelopmentConfig`、`ProductionConfig` 类；从环境变量读取 `SECRET_KEY`、`DATABASE_URL`、`JWT_SECRET_KEY` 等；设置 `SQLALCHEMY_TRACK_MODIFICATIONS = False`。
7. 创建 `run.py`，导入 `create_app`，实例化 `app = create_app()`；在 `if __name__ == '__main__':` 中运行 `app.run()`。
8. 处理请求和响应：用 `request.args.get('page', 1, type=int)` 读取查询参数；用 `request.get_json()` 读取 JSON 体；验证失败时调用 `abort(400, description="...")`；用 `make_response(jsonify(...), 201)` 创建自定义响应并设置 `response.headers['X-Custom-Header'] = 'value'`；用 `@app.errorhandler(404)` 注册错误处理器返回 JSON。
9. 使用 Blueprints 模块化：为每个模块创建 `Blueprint` 对象，如 `users_bp = Blueprint('users', __name__)`；用 `@users_bp.route('/', methods=['GET'])` 定义路由；在 `create_app` 中用 `app.register_blueprint(users_bp, url_prefix='/api/users')` 注册。
10. 使用 Flask-RESTful：创建 `Resource` 子类，定义 `get`、`post`、`put`、`delete` 方法；用 `fields` 定义序列化字段，用 `@marshal_with(user_fields)` 装饰方法；用 `reqparse.RequestParser()` 解析请求参数；用 `Api(app, prefix='/api/v1')` 创建 API 并调用 `api.add_resource(UserListResource, '/users')` 注册资源。
11. 使用 Marshmallow 进行请求验证：定义 `Schema` 子类，字段用 `fields` 和 `validate`；用 `@validates('email')` 自定义验证逻辑；在路由中用 `user_schema.load(request.get_json())` 验证，捕获 `ValidationError` 返回 400；用 `user_schema.dump(user)` 序列化响应。
12. 使用 Pydantic 进行请求验证：定义 `BaseModel` 子类，字段用 `Field` 和 `validator`；在路由中用 `UserCreate(**request.get_json())` 验证，捕获 `ValidationError` 返回 400；用 `UserResponse.from_orm(user).dict()` 序列化响应。
13. 使用 Flask-SQLAlchemy 定义模型：继承 `db.Model`，设置 `__tablename__`；定义 `db.Column` 字段，用 `db.relationship` 定义关系，用 `db.ForeignKey` 定义外键；实现 `set_password`/`check_password` 使用 `generate_password_hash` 和 `check_password_hash`；实现 `to_dict` 序列化方法。
14. 执行数据库操作：用 `db.session.add(user)`、`db.session.commit()`、`db.session.delete(user)`；用 `User.query.get_or_404(user_id)` 查询或 404；用 `User.query.paginate(page=page, per_page=20)` 分页。
15. 管理数据库迁移：运行 `flask db init`、`flask db migrate -m "Create users table"`、`flask db upgrade`、`flask db downgrade`。
16. 使用 Flask-Login 实现会话认证：初始化 `LoginManager`，设置 `user_loader`；让 `User` 继承 `UserMixin` 并实现 `get_id`；在路由中用 `login_user(user, remember=...)`、`logout_user()`、`@login_required`、`current_user`。
17. 使用 JWT 认证：初始化 `JWTManager`，配置 `JWT_SECRET_KEY`、`JWT_ACCESS_TOKEN_EXPIRES`、`JWT_REFRESH_TOKEN_EXPIRES`；用 `create_access_token(identity=user.id)` 和 `create_refresh_token` 生成令牌；用 `@jwt_required()` 保护路由，用 `get_jwt_identity()` 获取用户身份。
18. 管理配置：在 `Config` 类中用 `os.getenv` 读取环境变量；定义 `DevelopmentConfig`、`TestingConfig`、`ProductionConfig`；创建 `config_by_name` 字典和 `get_config(env_name)` 函数；在 `create_app` 中用 `app.config.from_object(get_config(config_name))`。
19. 支持 `.env` 文件：在 `.env` 中设置 `FLASK_APP`、`FLASK_ENV`、`SECRET_KEY`、`JWT_SECRET_KEY`、`DATABASE_URL`、`CORS_ORIGINS` 等；用 `from dotenv import load_dotenv; load_dotenv()` 加载。
20. 注册全局错误处理器：为 404、400、401、403、500、`HTTPException`、`SQLAlchemyError` 编写处理函数，返回 JSON 错误信息；在 500 错误中执行 `db.session.rollback()`。
21. 配置日志：创建 `logs` 目录，使用 `RotatingFileHandler` 写入 `logs/flask_app.log`，设置 `maxBytes=10240000` 和 `backupCount=10`；设置格式 `'%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]'` 和级别；在路由中用 `current_app.logger.info` 记录日志。
22. 使用 pytest 测试：在 `conftest.py` 中定义 `app` fixture（`create_app('testing')`，`db.create_all()`/`db.drop_all()`）、`client` fixture（`app.test_client()`）、`runner` fixture（`app.test_cli_runner()`）、`db_session` fixture（`db.session.begin_nested()`/`rollback()`）、`sample_user` fixture、`auth_headers` fixture（登录获取 token）。
23. 编写 API 测试：使用 `client.post('/api/users', json={...})`、`client.get(...)`、`client.put(...)`、`client.delete(...)`；断言 `response.status_code` 和 `response.get_json()`。
24. 使用 Gunicorn 部署：`pip install gunicorn`；运行 `gunicorn --workers 4 --bind 0.0.0.0:8000 "app:create_app()"`；创建 `gunicorn.conf.py` 配置 `bind`、`workers`、`worker_class`、`timeout`、`accesslog`、`errorlog`、`loglevel` 等。
25. 使用 Docker 部署：编写 `Dockerfile`，基于 `python:3.11-slim`，设置 `WORKDIR /app`，复制 `requirements.txt` 并安装，复制应用，创建非 root 用户 `flask`，`CMD ["gunicorn", "--config", "gunicorn.conf.py", "app:create_app()"]`；编写 `docker-compose.yml` 定义 `app`、`db`、`redis`、`nginx` 服务，配置环境变量和卷。
26. 实现微服务外部 API 调用：创建 `ExternalAPIService` 类，用 `requests.get`/`requests.post` 调用外部 API，设置超时，捕获 `requests.RequestException` 并记录日志。
27. 实现健康检查：创建 `health_bp` 蓝图，`/health` 返回 `{"status": "healthy"}`；`/health/ready` 用 `db.session.execute(text('SELECT 1'))` 检查数据库，返回状态码 200 或 503。
28. 遵循最佳实践：使用应用工厂模式；使用蓝图模块化；验证所有输入（Marshmallow/Pydantic）；使用环境变量存储密钥；实现全局错误处理。
29. 快速 Flask 测试模式：定义 `app`、`client`、`runner` fixture；测试路由、数据库操作、错误处理（如 `test_404_error` 断言 `b'Not Found' in response.data`）。
30. 快速 SQLAlchemy 集成：定义 `Base(DeclarativeBase)`，创建 `db = SQLAlchemy(model_class=Base)`；定义模型类；使用 `db.session.get(User, user_id)`、`db.session.add`、`db.session.commit`；用 `IntegrityError` 捕获并 `db.session.rollback()` 处理事务。
31. FastAPI 对比与迁移：当需要 async/await、自动 API 文档、内置 Pydantic 验证、WebSocket 时选择 FastAPI；当构建传统服务端渲染、现有大型 Flask 代码库、需要成熟生态和同步模式时保留 Flask；迁移时将 Flask 路由和 `jsonify` 替换为 FastAPI 的 `@app.get` 和 `response_model`，使用 `Depends` 注入数据库。

适用边界 · 注意事项

• 需要原生 async/await 高并发、自动生成 OpenAPI/Swagger 文档、内置数据验证或 WebSocket 支持时，FastAPI 是更合适的选择。
• 需要内置管理后台、完整 ORM、认证等“batteries-included”功能时，Django 可能比 Flask 更合适。