python-test
/
fastapi-demo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fastapi-demo/docs/complete-crud-api/CONSENSUS_complete-crud-api.md

5.8 KiB
Raw Blame History

CONSENSUS - 完善 CRUD API 功能共识文档

明确的需求描述

核心目标

将现有基于内存假数据的 FastAPI 项目转换为基于 MySQL 数据库的完整 CRUD 系统，实现 Users 和 Products 的完整增删改查操作。

具体功能需求

Users API 完善

  • POST /api/v1/users/ - 创建新用户
  • PUT /api/v1/users/{id} - 更新用户信息
  • DELETE /api/v1/users/{id} - 删除用户

Products API 完善

  • POST /api/v1/products/ - 创建新产品
  • PUT /api/v1/products/{id} - 更新产品信息
  • DELETE /api/v1/products/{id} - 删除产品

数据持久化

  • 完全移除内存假数据 (fake_users_db, fake_products_db)
  • 所有操作直接与 MySQL 数据库交互
  • 使用 SQLAlchemy ORM 进行数据库操作

技术实现方案

已确认的技术决策

1. 数据验证策略 ✅

  • Pydantic 层: 数据类型和格式验证
  • 服务层: 业务规则验证（邮箱唯一性、产品名称等）
  • 数据库层: 约束验证（主键、外键、唯一索引）

2. 错误处理方式 ✅

  • 提供详细错误信息，便于调试
  • 标准 HTTP 状态码
  • 结构化错误响应

3. 数据库会话管理 ✅

  • 使用 FastAPI 依赖注入机制
  • get_db() 依赖函数管理会话生命周期
  • 自动会话关闭和异常处理

4. API 响应格式 ✅

  • 保持现有代码风格
  • 直接返回 Pydantic 模型
  • 无需额外响应包装

5. 初始数据策略 ✅

  • 不保留假数据
  • 移除所有内存数据初始化
  • 从空数据库开始

技术约束

框架和库约束

  • FastAPI: 保持现有路由结构 /api/v1/
  • SQLAlchemy: 使用现有数据库模型
  • Pydantic: 使用现有模式定义
  • MySQL: 连接现有 fast_demo 数据库

代码规范约束

  • 保持现有项目结构和命名约定
  • 遵循现有代码风格和注释规范
  • 保持现有错误处理模式
  • 使用现有依赖包版本

架构约束

  • 维持分层架构: API层 → 服务层 → 数据库层
  • 保持应用工厂模式
  • 使用现有配置管理系统

集成方案

数据库集成

  • 利用现有 SQLAlchemy 配置
  • 复用现有数据库连接池
  • 使用现有模型定义 (app/database/models.py)

API 集成

  • 扩展现有路由文件
  • 保持现有 API 版本控制
  • 维持现有中间件配置

依赖注入集成

# 复用现有数据库依赖
from app.database.connection import get_db
from sqlalchemy.orm import Session

@router.post("/users/", response_model=UserResponse, status_code=201)
async def create_user(user: UserCreate, db: Session = Depends(get_db)):
    return user_service.create_user(db, user)

任务边界限制

包含范围 ✅

  • Users 和 Products 完整 CRUD API
  • 数据库持久化操作
  • 基础数据验证和错误处理
  • API 文档自动更新
  • 基础功能测试

排除范围 ❌

  • 用户认证和授权系统
  • API 限流和缓存机制
  • 分页、排序、过滤功能
  • 文件上传处理
  • 复杂业务逻辑验证
  • 性能优化和索引调优

验收标准

功能验收标准

Users API 验收

  • POST /api/v1/users/

    • 成功创建返回 201 状态码
    • 返回创建的用户信息
    • 数据持久化到数据库
    • 邮箱唯一性验证
    • 用户名唯一性验证

  • PUT /api/v1/users/{id}

    • 成功更新返回 200 状态码
    • 支持部分字段更新
    • 数据持久化到数据库
    • 用户不存在返回 404

  • DELETE /api/v1/users/{id}

    • 成功删除返回 204 状态码
    • 数据从数据库中删除
    • 用户不存在返回 404

Products API 验收

  • POST /api/v1/products/

    • 成功创建返回 201 状态码
    • 返回创建的产品信息
    • 数据持久化到数据库
    • 价格和库存数据验证

  • PUT /api/v1/products/{id}

    • 成功更新返回 200 状态码
    • 支持部分字段更新
    • 数据持久化到数据库
    • 产品不存在返回 404

  • DELETE /api/v1/products/{id}

    • 成功删除返回 204 状态码
    • 数据从数据库中删除
    • 产品不存在返回 404

数据验证验收

  • 必填字段验证 (422 状态码)
  • 数据类型验证 (422 状态码)
  • 邮箱格式验证 (422 状态码)
  • 唯一性约束验证 (409 状态码)
  • 数值范围验证 (价格 > 0)

错误处理验收

  • 资源不存在: 404 Not Found
  • 数据验证失败: 422 Unprocessable Entity
  • 唯一性冲突: 409 Conflict
  • 数据库连接错误: 500 Internal Server Error
  • 详细错误信息返回

技术质量验收

  • 所有内存假数据已移除
  • 数据库会话正确管理
  • 无内存或连接泄漏
  • 事务处理正确实现
  • 代码符合现有规范
  • API 文档自动生成正确

集成验收

  • 现有 GET API 正常工作
  • 应用启动无错误
  • 数据库连接正常
  • 与现有代码无冲突
  • 环境配置兼容

确认的关键假设

  1. 数据库状态: MySQL 数据库 fast_demo 已存在且可连接
  2. 表结构: SQLAlchemy 模型与数据库表结构一致
  3. 权限: 数据库用户具有完整 CRUD 权限
  4. 环境: 开发环境配置正确且稳定
  5. 依赖: 所有必要的 Python 包已安装

风险评估

低风险 🟢

  • API 端点实现 (基于现有模式)
  • 数据库 CRUD 操作 (SQLAlchemy 标准操作)
  • 基础数据验证 (Pydantic 支持)

中等风险 🟡

  • 数据库事务管理 (需要正确的异常处理)
  • 唯一性约束冲突处理 (需要适当的错误映射)

已缓解风险 ✅

  • 数据库连接问题 (已验证连接正常)
  • 模型定义不匹配 (已确认 SQLAlchemy 模型)
  • 配置环境问题 (已确认多环境配置)

共识确认: ✅ 所有关键决策点已确认 创建时间: 2025-09-28 最后更新: 2025-09-28 状态: 已批准，准备进入架构阶段