220 lines
5.8 KiB
Markdown
220 lines
5.8 KiB
Markdown
|
# ALIGNMENT - 完善 CRUD API 功能
|
|||
|
|
|
|||
|
|
## 项目特性规范
|
|||
|
|
|
|||
|
|
### 当前项目分析
|
|||
|
|
|
|||
|
|
#### 技术栈
|
|||
|
|
- **FastAPI**: Python 异步 Web 框架
|
|||
|
|
- **SQLAlchemy**: ORM 框架
|
|||
|
|
- **MySQL**: 数据库 (fast_demo)
|
|||
|
|
- **Pydantic**: 数据验证和序列化
|
|||
|
|
- **Uvicorn**: ASGI 服务器
|
|||
|
|
|
|||
|
|
#### 项目架构模式
|
|||
|
|
- **分层架构**: API层 → 服务层 → 数据访问层
|
|||
|
|
- **应用工厂模式**: 支持多环境配置
|
|||
|
|
- **依赖注入**: 数据库会话管理
|
|||
|
|
|
|||
|
|
#### 现有代码结构
|
|||
|
|
```
|
|||
|
|
app/
|
|||
|
|
├── api/v1/endpoints/ # API 路由层
|
|||
|
|
├── services/ # 业务逻辑层
|
|||
|
|
├── database/ # 数据库相关
|
|||
|
|
│ ├── models.py # SQLAlchemy 数据库模型
|
|||
|
|
│ ├── connection.py # 数据库连接
|
|||
|
|
│ └── base.py # Base 模型类
|
|||
|
|
├── models/ # Pydantic 数据模型
|
|||
|
|
├── schemas/ # 请求/响应模式
|
|||
|
|
└── core/ # 核心配置
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 当前状态分析
|
|||
|
|
✅ **已完成**:
|
|||
|
|
- 数据库连接配置和环境管理
|
|||
|
|
- SQLAlchemy 数据库模型 (User, Product)
|
|||
|
|
- Pydantic 模式定义
|
|||
|
|
- 基础 API 路由结构
|
|||
|
|
- GET 操作的 API 端点
|
|||
|
|
|
|||
|
|
❌ **待完善**:
|
|||
|
|
- 服务层使用内存假数据 (`fake_users_db`)
|
|||
|
|
- 缺少 POST、PUT、DELETE API 端点
|
|||
|
|
- 没有数据库持久化操作
|
|||
|
|
- 缺少数据验证和异常处理
|
|||
|
|
- 缺少完整的 CRUD 测试
|
|||
|
|
|
|||
|
|
## 原始需求
|
|||
|
|
|
|||
|
|
> "1. 🔧 完善现有 API 功能 - 为 Users 和 Products 添加完整的 CRUD 操作 (CREATE, UPDATE, DELETE) - 实现数据库持久化存储"
|
|||
|
|
|
|||
|
|
## 需求理解
|
|||
|
|
|
|||
|
|
### 核心目标
|
|||
|
|
将现有的基于内存假数据的 API 服务转换为基于 MySQL 数据库的完整 CRUD 系统。
|
|||
|
|
|
|||
|
|
### 具体需求拆解
|
|||
|
|
|
|||
|
|
#### 1. Users API 完善
|
|||
|
|
- ✅ **GET /api/v1/users/** - 获取用户列表 (已存在)
|
|||
|
|
- ✅ **GET /api/v1/users/{id}** - 获取单个用户 (已存在)
|
|||
|
|
- ❌ **POST /api/v1/users/** - 创建新用户 (需实现)
|
|||
|
|
- ❌ **PUT /api/v1/users/{id}** - 更新用户信息 (需实现)
|
|||
|
|
- ❌ **DELETE /api/v1/users/{id}** - 删除用户 (需实现)
|
|||
|
|
|
|||
|
|
#### 2. Products API 完善
|
|||
|
|
- ✅ **GET /api/v1/products/** - 获取产品列表 (已存在)
|
|||
|
|
- ✅ **GET /api/v1/products/{id}** - 获取单个产品 (已存在)
|
|||
|
|
- ❌ **POST /api/v1/products/** - 创建新产品 (需实现)
|
|||
|
|
- ❌ **PUT /api/v1/products/{id}** - 更新产品信息 (需实现)
|
|||
|
|
- ❌ **DELETE /api/v1/products/{id}** - 删除产品 (需实现)
|
|||
|
|
|
|||
|
|
#### 3. 数据库持久化
|
|||
|
|
- 替换内存假数据为真实数据库操作
|
|||
|
|
- 使用 SQLAlchemy ORM 进行数据库交互
|
|||
|
|
- 实现数据库会话管理
|
|||
|
|
|
|||
|
|
#### 4. 数据验证和异常处理
|
|||
|
|
- 输入数据验证 (Pydantic)
|
|||
|
|
- 数据库约束验证
|
|||
|
|
- 合适的 HTTP 状态码返回
|
|||
|
|
- 错误信息处理
|
|||
|
|
|
|||
|
|
## 边界确认
|
|||
|
|
|
|||
|
|
### 包含在任务范围内
|
|||
|
|
✅ **API 端点**:
|
|||
|
|
- 完整的 Users CRUD 操作
|
|||
|
|
- 完整的 Products CRUD 操作
|
|||
|
|
- 数据库持久化实现
|
|||
|
|
|
|||
|
|
✅ **技术实现**:
|
|||
|
|
- 服务层重构 (移除假数据)
|
|||
|
|
- 数据库操作集成
|
|||
|
|
- API 路由完善
|
|||
|
|
- 基础数据验证
|
|||
|
|
|
|||
|
|
✅ **质量保证**:
|
|||
|
|
- API 测试用例
|
|||
|
|
- 错误处理机制
|
|||
|
|
- 文档更新
|
|||
|
|
|
|||
|
|
### 不包含在任务范围内
|
|||
|
|
❌ **高级功能**:
|
|||
|
|
- 用户认证和授权
|
|||
|
|
- API 限流和缓存
|
|||
|
|
- 分页和复杂查询
|
|||
|
|
- 文件上传处理
|
|||
|
|
|
|||
|
|
❌ **业务逻辑**:
|
|||
|
|
- 复杂业务规则验证
|
|||
|
|
- 工作流程控制
|
|||
|
|
- 第三方集成
|
|||
|
|
|
|||
|
|
❌ **性能优化**:
|
|||
|
|
- 数据库索引优化
|
|||
|
|
- 查询性能调优
|
|||
|
|
- 缓存策略
|
|||
|
|
|
|||
|
|
## 疑问澄清
|
|||
|
|
|
|||
|
|
### 已解决的技术疑问
|
|||
|
|
|
|||
|
|
1. **数据库连接**: ✅ 已确认 MySQL 连接正常，数据库名为 `fast_demo`
|
|||
|
|
2. **表结构**: ✅ 已确认 SQLAlchemy 模型定义完整 (User, Product)
|
|||
|
|
3. **项目架构**: ✅ 已分析现有分层架构模式
|
|||
|
|
4. **配置管理**: ✅ 已确认多环境配置支持
|
|||
|
|
|
|||
|
|
### 需要确认的决策点
|
|||
|
|
|
|||
|
|
#### 1. 数据验证策略
|
|||
|
|
**选项**:
|
|||
|
|
- A) 仅依赖 Pydantic 模式验证
|
|||
|
|
- B) 添加服务层业务规则验证
|
|||
|
|
- C) 数据库层约束 + Pydantic 验证
|
|||
|
|
|
|||
|
|
**建议**: 选择 C，使用分层验证确保数据完整性
|
|||
|
|
|
|||
|
|
#### 2. 错误处理级别
|
|||
|
|
**选项**:
|
|||
|
|
- A) 基础 HTTP 状态码返回
|
|||
|
|
- B) 详细错误信息和错误代码
|
|||
|
|
- C) 结构化错误响应格式
|
|||
|
|
|
|||
|
|
**建议**: 选择 B，提供清晰的错误信息便于调试
|
|||
|
|
|
|||
|
|
#### 3. API 响应格式
|
|||
|
|
**选项**:
|
|||
|
|
- A) 直接返回数据模型
|
|||
|
|
- B) 统一响应格式包装
|
|||
|
|
- C) RESTful 标准响应
|
|||
|
|
|
|||
|
|
**建议**: 选择 A，保持与现有代码风格一致
|
|||
|
|
|
|||
|
|
#### 4. 数据库会话管理
|
|||
|
|
**选项**:
|
|||
|
|
- A) 依赖注入 SessionLocal
|
|||
|
|
- B) 上下文管理器
|
|||
|
|
- C) 服务层直接管理
|
|||
|
|
|
|||
|
|
**建议**: 选择 A，利用 FastAPI 依赖注入机制
|
|||
|
|
|
|||
|
|
## 技术约束
|
|||
|
|
|
|||
|
|
### 必须遵循的约束
|
|||
|
|
- 保持现有项目结构和命名约定
|
|||
|
|
- 使用现有的数据库模型定义
|
|||
|
|
- 保持 API 路径结构 `/api/v1/`
|
|||
|
|
- 使用现有的 Pydantic 模式
|
|||
|
|
- 保持现有的错误处理风格
|
|||
|
|
|
|||
|
|
### 技术限制
|
|||
|
|
- Python 3.11+
|
|||
|
|
- FastAPI 框架限制
|
|||
|
|
- SQLAlchemy ORM 使用
|
|||
|
|
- MySQL 数据库约束
|
|||
|
|
- 现有依赖包版本
|
|||
|
|
|
|||
|
|
## 验收标准
|
|||
|
|
|
|||
|
|
### 功能验收
|
|||
|
|
1. **Users API**:
|
|||
|
|
- [ ] POST 创建用户成功返回 201
|
|||
|
|
- [ ] PUT 更新用户成功返回 200
|
|||
|
|
- [ ] DELETE 删除用户成功返回 204
|
|||
|
|
- [ ] 所有操作均持久化到数据库
|
|||
|
|
|
|||
|
|
2. **Products API**:
|
|||
|
|
- [ ] POST 创建产品成功返回 201
|
|||
|
|
- [ ] PUT 更新产品成功返回 200
|
|||
|
|
- [ ] DELETE 删除产品成功返回 204
|
|||
|
|
- [ ] 所有操作均持久化到数据库
|
|||
|
|
|
|||
|
|
3. **数据验证**:
|
|||
|
|
- [ ] 必填字段验证
|
|||
|
|
- [ ] 唯一性约束验证
|
|||
|
|
- [ ] 数据类型验证
|
|||
|
|
|
|||
|
|
4. **错误处理**:
|
|||
|
|
- [ ] 资源不存在返回 404
|
|||
|
|
- [ ] 数据验证失败返回 422
|
|||
|
|
- [ ] 数据库错误适当处理
|
|||
|
|
|
|||
|
|
### 质量验收
|
|||
|
|
- [ ] 代码遵循现有项目规范
|
|||
|
|
- [ ] 所有新增代码有适当注释
|
|||
|
|
- [ ] API 文档自动生成正确
|
|||
|
|
- [ ] 测试覆盖主要功能点
|
|||
|
|
|
|||
|
|
### 技术验收
|
|||
|
|
- [ ] 数据库连接正常工作
|
|||
|
|
- [ ] 事务管理正确实现
|
|||
|
|
- [ ] 无内存泄漏或连接泄漏
|
|||
|
|
- [ ] 与现有代码无冲突
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**创建时间**: 2025-09-28
|
|||
|
|
**任务负责**: Claude AI
|
|||
|
|
**预计工期**: 2-3小时
|