Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md

Python 应用示例

一个完整的 FastAPI 后端实现，用于简单社交网络服务 (SNS)，允许用户创建、检索、更新和删除帖子；添加评论；以及对帖子点赞/取消点赞。

🏗️ 架构概述

框架: FastAPI with Python 3.12+
数据库: SQLite (sns_api.db)
API 文档: Swagger UI + OpenAPI 3.1 规范
CORS: 启用跨域请求
数据验证: 具有全面验证的 Pydantic 模型

📁 项目结构

python/
├── main.py              # FastAPI 应用程序入口点
├── models.py            # Pydantic 数据模型和模式
├── database.py          # SQLite 数据库操作
├── openapi.yaml         # OpenAPI 3.0.1 规范
├── sns_api.db          # SQLite 数据库文件（自动创建）
├── README.md           # 此文档
└── .venv/              # 虚拟环境（在设置期间创建）

🚀 快速开始

先决条件

请参考 README 文档进行准备。

1. 环境设置

首先，设置 $REPOSITORY_ROOT 环境变量。

# bash/zsh
REPOSITORY_ROOT=$(git rev-parse --show-toplevel)

# PowerShell
$REPOSITORY_ROOT = git rev-parse --show-toplevel

然后，导航到 python 目录并创建虚拟环境：

cd $REPOSITORY_ROOT/complete/python

创建虚拟环境

# 使用 uv（推荐）
uv venv .venv

# 使用标准 Python（替代方案）
python -m venv .venv

2. 激活虚拟环境

# 在 Linux/macOS
source .venv/bin/activate

# 在 Windows 命令提示符
.venv\Scripts\activate

3. 安装依赖

# 使用 uv（推荐）
uv pip install fastapi uvicorn python-multipart pyyaml

# 使用 pip（替代方案）
pip install fastapi uvicorn python-multipart pyyaml

4. 复制 OpenAPI 规范

从父目录复制 OpenAPI 规范。

# 在 Linux/macOS
cp ../openapi.yaml .

# 在 Windows 命令提示符
xcopy ..\openapi.yaml .

5. 运行应用程序

启动开发服务器

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

应用程序将在以下地址可用：

API 基础 URL: http://localhost:8000/api/
Swagger UI: http://localhost:8000/docs
OpenAPI 规范: http://localhost:8000/openapi.json

📊 数据库模式

应用程序使用 SQLite，具有以下表：

帖子表

id (TEXT, PRIMARY KEY) - UUID
username (TEXT, NOT NULL) - 作者用户名
content (TEXT, NOT NULL) - 帖子内容
created_at (TEXT, NOT NULL) - ISO 时间戳
updated_at (TEXT, NOT NULL) - ISO 时间戳

评论表

id (TEXT, PRIMARY KEY) - UUID
post_id (TEXT, NOT NULL) - 帖子外键
username (TEXT, NOT NULL) - 作者用户名
content (TEXT, NOT NULL) - 评论内容
created_at (TEXT, NOT NULL) - ISO 时间戳
updated_at (TEXT, NOT NULL) - ISO 时间戳

点赞表

post_id (TEXT, NOT NULL) - 帖子外键
username (TEXT, NOT NULL) - 点赞的用户
liked_at (TEXT, NOT NULL) - ISO 时间戳
主键: (post_id, username)

🔌 API 端点

帖子

GET /api/posts - 列出所有帖子
POST /api/posts - 创建新帖子
GET /api/posts/{postId} - 获取特定帖子
PATCH /api/posts/{postId} - 更新帖子
DELETE /api/posts/{postId} - 删除帖子

GET /api/posts/{postId}/comments - 列出帖子的评论
POST /api/posts/{postId}/comments - 创建评论
GET /api/posts/{postId}/comments/{commentId} - 获取特定评论
PATCH /api/posts/{postId}/comments/{commentId} - 更新评论
DELETE /api/posts/{postId}/comments/{commentId} - 删除评论

POST /api/posts/{postId}/likes - 为帖子点赞
DELETE /api/posts/{postId}/likes?username={username} - 取消帖子点赞

🧪 测试 API

使用 cURL

创建帖子

curl -X POST "http://localhost:8000/api/posts" \
  -H "Content-Type: application/json" \
  -d '{"username": "john_doe", "content": "你好世界！这是我的第一篇帖子。"}'

获取所有帖子

curl -X GET "http://localhost:8000/api/posts"

添加评论

curl -X POST "http://localhost:8000/api/posts/{POST_ID}/comments" \
  -H "Content-Type: application/json" \
  -d '{"username": "jane_smith", "content": "很棒的帖子！"}'

为帖子点赞

curl -X POST "http://localhost:8000/api/posts/{POST_ID}/likes" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice_johnson"}'

使用 Swagger UI

导航到 http://localhost:8000/docs
交互式地探索和测试所有 API 端点
查看请求/响应模式和示例

📝 数据模型

请求模型

NewPostRequest: {username: str, content: str}
UpdatePostRequest: {username: str, content: str}
NewCommentRequest: {username: str, content: str}
UpdateCommentRequest: {username: str, content: str}
LikeRequest: {username: str}

响应模型

Post: 包含元数据和计数的完整帖子对象
Comment: 包含元数据的完整评论对象
LikeResponse: 带时间戳的点赞确认

⚙️ 配置

环境变量

应用程序使用默认设置，但可以自定义：

数据库: SQLite 文件 sns_api.db（自动创建）
主机: 0.0.0.0（所有接口）
端口: 8000
CORS: 为所有来源启用

生产环境考虑

对于生产部署，请考虑：

数据库: 切换到 PostgreSQL 或 MySQL
环境变量: 用于敏感配置
安全性: 添加身份验证和授权
CORS: 限制到特定域名
日志记录: 实现结构化日志记录
监控: 添加健康检查和指标

🛠️ 开发

文件组织

main.py: FastAPI 应用配置、中间件和路由定义
models.py: 用于数据验证和序列化的 Pydantic 模型
database.py: SQLite 操作、连接管理和 CRUD 函数

代码风格

项目遵循：

Python PEP 8 风格指南
FastAPI 最佳实践
函数式编程模式
全面的类型提示
全面的错误处理

添加新功能

在 models.py 中定义 Pydantic 模型
在 database.py 中添加数据库操作
在 main.py 中创建 API 端点
如果需要，更新 OpenAPI 规范

🐛 故障排除

常见问题

端口已被占用: 使用 --port 8001 更改端口
虚拟环境问题: 使用 rm -rf .venv && uv venv .venv 重新创建
数据库锁定: 停止应用程序的所有运行实例
导入错误: 确保虚拟环境已激活

调试模式

使用附加日志记录运行：

uvicorn main:app --host 0.0.0.0 --port 8000 --reload --log-level debug

📚 其他资源

免责声明: 本文档由 GitHub Copilot 本地化。因此，可能包含错误。如果您发现任何不当或错误的翻译，请创建一个 issue。

FilesExpand file tree

python

Directory actions

More options