github-actions-creator/docs/python-flask.md

Python (Flask) 项目：社交媒体 API

概述

使用 Python 和 Flask 构建一个轻量级社交媒体后端 API，支持用户发布动态、关注、评论和点赞。

功能需求

1. 用户认证

• 注册: POST /api/auth/register - 请求体含 username, password, email。
• 登录: POST /api/auth/login - 返回 JWT Access Token。
• 个人信息: GET /api/profile - 需认证，返回当前用户信息。

2. 用户关系

• 关注/取关: POST/DELETE /api/users/<id>/follow - 需认证。
• 获取粉丝/关注列表: GET /api/users/<id>/followers 和 GET /api/users/<id>/following。

3. 动态 (Post)

• 创建动态: POST /api/posts - 需认证，请求体含 text。
• 获取时间线: GET /api/timeline - 需认证，返回自己和关注用户的动态（时间倒序）。
• 获取用户动态: GET /api/users/<id>/posts。
• 删除动态: DELETE /api/posts/<id> - 需认证，仅限作者。

4. 互动

• 点赞/取消: POST/DELETE /api/posts/<id>/like - 需认证。
• 评论: POST /api/posts/<id>/comments - 需认证，请求体含 text。
• 获取评论: GET /api/posts/<id>/comments。

技术栈

• 语言: Python 3.9+
• 框架: Flask, Flask-RESTful
• 数据库: PostgreSQL 或 SQLite
• ORM: Flask-SQLAlchemy
• 迁移: Flask-Migrate
• 认证: PyJWT
• 序列化: Flask-Marshmallow
• 代码结构: Flask Blueprints

项目结构

/flask-social-api
├── app/
│   ├── __init__.py         # 应用工厂
│   ├── models.py           # SQLAlchemy 模型
│   ├── schemas.py          # Marshmallow Schemas
│   ├── auth/               # 认证蓝图
│   ├── posts/              # 动态蓝图
│   └── users/              # 用户蓝图
├── migrations/
├── config.py
├── run.py
└── requirements.txt

任务步骤

1. 环境设置: 创建虚拟环境，安装依赖。
2. 配置: 在 config.py 中设置数据库 URI 和 JWT 密钥。
3. 应用工厂: 在 app/__init__.py 中创建 create_app 函数，初始化扩展并注册蓝图。
4. 数据库建模: 在 app/models.py 中定义数据模型及关系。
5. 数据库迁移: 运行 flask db init, migrate, upgrade 创建表。
6. 序列化: 在 app/schemas.py 中为模型创建 Marshmallow Schema。
7. 蓝图: 为各模块（auth, posts, users）创建蓝图并定义路由。
8. 认证: 创建装饰器或使用扩展保护需认证的端点。
9. 业务逻辑: 在视图函数或服务中实现核心逻辑。
10. 测试: 使用 Pytest 为 API 端点编写集成测试。

先行任务: 设计数据库模型关系图 (ERD) 和 API 的 JSON 响应格式。