规范接口方法写法

2026-09-22 20:43:10 +08:00
parent b3d557e4fc
commit 6016a99bcf
1 changed files with 472 additions and 0 deletions
@@ -0,0 +1,472 @@
+# 学生模块答辩演示步骤
+
+> 演示目标：通过 Swagger 依次展示学生新增、参数校验、分页查询、条件查询、详情查询、局部更新和逻辑删除。
+
+## 一、答辩前检查
+
+### 1. 确认数据库和基础数据
+
+1. 确认 MySQL 已启动。
+2. 确认项目配置的数据库可以连接。
+3. 确认班级表中至少存在一条未删除的班级记录。
+4. 记住一个真实存在的班级 ID。下文示例使用 `class_id = 1`，如果数据库中不存在班级 1，请替换成实际班级 ID。
+
+`consultant_id` 在演示数据中使用 `null`，避免因为顾问外键不存在导致新增失败。
+
+### 2. 确认当前接口方法
+
+当前代码中的学生接口如下：
+
+| 功能 | 请求方法 | 地址 |
+| --- | --- | --- |
+| 新增学生 | `PUT` | `/students` |
+| 更新学生 | `POST` | `/students/{id}` |
+| 分页查询 | `GET` | `/students` |
+| 详情查询 | `GET` | `/students/{id}` |
+| 逻辑删除 | `DELETE` | `/students/{id}` |
+
+注意：常见 REST 规范通常使用 `POST` 新增、`PUT` 更新，但当前项目代码正好相反。答辩前如果修改了请求方法，需要同步调整本文档中的操作。
+
+### 3. 启动项目
+
+在项目根目录执行：
+
+```powershell
+python main.py
+```
+
+看到服务正常启动后，在浏览器打开：
+
+```text
+http://127.0.0.1:23333/docs
+```
+
+在 Swagger 页面找到“学生接口”。
+
+## 二、正式演示流程
+
+建议严格按照下面的顺序演示。每次操作时先展开接口，点击 **Try it out**，填写参数或请求体，再点击 **Execute**。
+
+## 步骤 1：演示新增参数校验
+
+展开：
+
+```text
+PUT /students
+```
+
+先输入一条性别不合法的数据：
+
+```json
+{
+  "student_name": "答辩演示学生",
+  "class_id": 1,
+  "consultant_id": null,
+  "native_place": "河南",
+  "graduation_school": "演示大学",
+  "major": "软件工程",
+  "enrollment_date": "2025-09-01",
+  "graduation_date": "2027-06-30",
+  "education": "本科",
+  "age": 22,
+  "gender": "未知"
+}
+```
+
+预期结果：HTTP 状态码为 `422`，提示 `gender` 只能是“男”或“女”。
+
+讲解词：
+
+> 请求进入接口之前会先经过 Pydantic 请求模型校验。性别字段使用 Literal 约束，只允许男或女，非法数据不会进入 DAO 层，也不会写入数据库。
+
+## 步骤 2：演示日期校验
+
+仍然使用新增接口，将毕业日期设置为早于入学日期：
+
+```json
+{
+  "student_name": "答辩演示学生",
+  "class_id": 1,
+  "consultant_id": null,
+  "native_place": "河南",
+  "graduation_school": "演示大学",
+  "major": "软件工程",
+  "enrollment_date": "2025-09-01",
+  "graduation_date": "2024-06-30",
+  "education": "本科",
+  "age": 22,
+  "gender": "男"
+}
+```
+
+预期结果：HTTP 状态码为 `422`，提示“毕业日期不能早于入学日期”。
+
+讲解词：
+
+> 除了单字段类型和范围校验，我还使用模型级校验器校验两个日期之间的业务关系。
+
+## 步骤 3：新增一名合法学生
+
+继续使用：
+
+```text
+PUT /students
+```
+
+输入以下合法数据：
+
+```json
+{
+  "student_name": "答辩演示学生",
+  "class_id": 1,
+  "consultant_id": null,
+  "native_place": "河南",
+  "graduation_school": "演示大学",
+  "major": "软件工程",
+  "enrollment_date": "2025-09-01",
+  "graduation_date": "2027-06-30",
+  "education": "本科",
+  "age": 22,
+  "gender": "男"
+}
+```
+
+这里故意不传 `student_no`。DAO 在插入并取得自增主键后，会自动生成类似 `STU0001` 的学生编号。
+
+预期响应：
+
+```json
+{
+  "code": 200,
+  "detail": "添加学生成功"
+}
+```
+
+讲解词：
+
+> 新增请求先由 StudentCreate 完成字段校验，再通过 model_dump 转成字典。DAO 创建 ORM 实例并执行 flush 获取自增 ID，如果没有手动传入学号，就根据 ID 自动生成学号，最后提交事务。
+
+## 步骤 4：分页查询并记录演示学生 ID
+
+展开：
+
+```text
+GET /students
+```
+
+填写：
+
+```text
+page = 1
+page_size = 5
+```
+
+其他查询条件暂时留空，然后执行。
+
+预期结果：
+
+- `code` 为 `200`；
+- `total` 表示未删除学生的总数；
+- `page` 为 `1`；
+- `page_size` 为 `5`；
+- `data` 最多返回 5 条；
+- 数据按照学生 ID 倒序排列，刚新增的学生通常在第一条。
+
+从返回结果中找到 `student_name` 为“答辩演示学生”的记录，并记下：
+
+```text
+id = ________
+student_no = ________
+```
+
+后续所有 `{id}` 都替换成这里记录的真实学生 ID。
+
+讲解词：
+
+> 查询时先添加 is_deleted 等于 0 的条件，确保逻辑删除的数据不可见；然后在分页之前调用 count 获取符合条件的总数，最后使用 offset 和 limit 完成分页。固定按 ID 倒序可以保证分页顺序稳定。
+
+分页计算公式：
+
+```text
+offset = (page - 1) * page_size
+```
+
+## 步骤 5：演示姓名模糊查询
+
+继续使用：
+
+```text
+GET /students
+```
+
+填写：
+
+```text
+student_name = 答辩
+page = 1
+page_size = 10
+```
+
+预期结果：只返回姓名中包含“答辩”的未删除学生。
+
+讲解词：
+
+> 查询参数都是可选的。前端传入姓名时，DAO 使用 LIKE 完成模糊查询；没有传入的条件不会拼接到 SQL 中。
+
+也可以补充展示以下任意一种查询：
+
+```text
+student_no = 上一步记录的学号
+```
+
+或者：
+
+```text
+class_id = 1
+```
+
+## 步骤 6：查询单个学生详情
+
+展开：
+
+```text
+GET /students/{id}
+```
+
+将 `id` 填写为步骤 4 记录的学生 ID，然后执行。
+
+预期响应结构：
+
+```json
+{
+  "code": 200,
+  "detail": "查询成功",
+  "data": {
+    "id": 1,
+    "student_no": "STU0001",
+    "student_name": "答辩演示学生",
+    "class_id": 1,
+    "consultant_id": null,
+    "native_place": "河南",
+    "graduation_school": "演示大学",
+    "major": "软件工程",
+    "enrollment_date": "2025-09-01",
+    "graduation_date": "2027-06-30",
+    "education": "本科",
+    "age": 22,
+    "gender": "男"
+  }
+}
+```
+
+实际的 `id` 和 `student_no` 以数据库返回为准。
+
+讲解词：
+
+> DAO 使用主键和 is_deleted 等于 0 两个条件查询。API 层手动组装返回字典，只暴露业务需要的字段，不返回 is_deleted、创建时间等内部字段。
+
+## 步骤 7：局部更新学生
+
+展开：
+
+```text
+POST /students/{id}
+```
+
+将 `id` 填写为步骤 4 记录的学生 ID，请求体只输入需要修改的字段：
+
+```json
+{
+  "age": 23,
+  "gender": "女"
+}
+```
+
+预期结果：返回“修改学生成功”，其他未传字段保持不变。
+
+讲解词：
+
+> 更新模型中的字段都是可选字段，接口通过 model_dump 的 exclude_unset 参数只提取前端实际传入的字段，DAO 再使用 setattr 循环完成局部更新。
+
+更新完成后，再执行一次：
+
+```text
+GET /students/{id}
+```
+
+确认：
+
+```text
+age = 23
+gender = 女
+```
+
+其余字段没有变化。
+
+## 步骤 8：演示更新参数校验
+
+再次调用：
+
+```text
+POST /students/{id}
+```
+
+输入：
+
+```json
+{
+  "age": 200,
+  "gender": "其他"
+}
+```
+
+预期结果：HTTP 状态码为 `422`。
+
+讲解词：
+
+> 年龄限制在 0 到 150 之间，性别限制为男或女。参数校验失败时，请求不会进入更新 DAO，因此数据库中的数据不会被修改。
+
+## 步骤 9：逻辑删除学生
+
+展开：
+
+```text
+DELETE /students/{id}
+```
+
+填写步骤 4 记录的学生 ID，然后执行。
+
+预期响应：
+
+```json
+{
+  "code": 200,
+  "detail": "删除学生成功"
+}
+```
+
+讲解词：
+
+> 删除操作不是物理删除，而是把 is_deleted 更新为 1。这样可以保留历史数据，同时所有正常查询都会通过 is_deleted 等于 0 将其过滤掉。
+
+## 步骤 10：验证逻辑删除
+
+删除后，再执行：
+
+```text
+GET /students/{id}
+```
+
+预期结果：HTTP 状态码为 `404`：
+
+```json
+{
+  "detail": "学生不存在"
+}
+```
+
+再执行学生列表查询或姓名模糊查询，也不应该看到刚才删除的学生。
+
+讲解词：
+
+> 数据库记录仍然存在，但详情查询和列表查询都统一增加了 is_deleted 等于 0 的条件，所以业务层已经无法查询到该记录。
+
+## 三、建议的答辩讲解顺序
+
+可以用下面这段话概括学生模块：
+
+> 学生模块采用 API、Schema、DAO 和 Model 分层。Schema 负责请求参数的类型、范围和业务规则校验；API 负责接收请求、处理 HTTP 状态码以及控制响应字段；DAO 负责数据库查询和事务处理；Model 负责学生表与字段的 ORM 映射。列表接口支持学号精确查询、姓名模糊查询、班级查询以及分页，并统一过滤逻辑删除数据。新增支持自动生成学生编号，修改支持局部更新，删除采用逻辑删除。
+
+## 四、常见提问与回答
+
+### 1. 为什么分页之前先执行 count？
+
+因为前端需要知道符合条件的总数据量。`count()` 必须在 `offset` 和 `limit` 之前执行，否则统计到的可能只是当前页的数据量。
+
+### 2. 为什么分页查询要排序？
+
+如果不指定排序，数据库每次返回数据的顺序不一定稳定，可能造成翻页时数据重复或遗漏。当前代码按照学生 ID 倒序排列。
+
+### 3. 为什么使用逻辑删除？
+
+逻辑删除能够保留历史数据，避免误删除后无法恢复。正常查询通过 `is_deleted == 0` 过滤已删除记录。
+
+### 4. 为什么列表和详情要手动组装字典？
+
+手动组装能够明确控制暴露给前端的字段，避免把 `is_deleted` 等数据库内部字段返回给用户。
+
+### 5. 为什么修改接口只更新部分字段？
+
+前端可能只修改年龄或手机号等个别字段。使用 `exclude_unset=True` 只获取实际传入的字段，再通过 `setattr` 更新，可以避免未传字段被错误覆盖。
+
+### 6. 为什么非法参数返回 422？
+
+FastAPI 会先调用 Pydantic 校验请求体。数据类型、字段范围或 Literal 约束不满足时，请求不会进入业务函数，而是直接返回 422。
+
+### 7. 为什么学生编号可以不传？
+
+学生记录执行 `flush()` 后可以取得数据库生成的自增主键，系统再根据主键生成学生编号，能够减少手工编号冲突。
+
+## 五、故障排查
+
+### 请求体报 JSON decode error
+
+检查以下问题：
+
+- 属性名和值必须使用英文双引号；
+- 最后一个字段后面不能有逗号；
+- JSON 中不能写注释；
+- 日期必须使用 `YYYY-MM-DD` 格式。
+
+合法示例：
+
+```json
+{
+  "age": 23,
+  "gender": "女"
+}
+```
+
+### 新增返回 500
+
+优先检查：
+
+1. MySQL 是否启动；
+2. 数据库连接配置是否正确；
+3. `class_id` 是否在班级表中真实存在；
+4. 手动填写的 `student_no` 是否与已有记录重复；
+5. 如果填写了 `consultant_id`，该顾问是否真实存在。
+
+### 查询详情返回 404
+
+检查：
+
+1. ID 是否填写正确；
+2. 该学生是否已经被逻辑删除；
+3. 是否误用了列表中的班级 ID 或顾问 ID。
+
+### Swagger 请求体只显示 `{}`
+
+检查 `StudentUpdate` 是否被错误地重复嵌套。正确写法应该只有一层：
+
+```python
+class StudentUpdate(BaseModel):
+    student_name: str | None = None
+    # 其他字段……
+```
+
+## 六、演示结束检查表
+
+- [ ] 服务可以正常启动；
+- [ ] Swagger 可以打开；
+- [ ] 已确认一个真实存在的班级 ID；
+- [ ] 性别非法数据返回 422；
+- [ ] 日期非法数据返回 422；
+- [ ] 合法学生新增成功；
+- [ ] 已从列表中记录新增学生 ID 和学号；
+- [ ] 分页和条件查询成功；
+- [ ] 详情查询不暴露内部字段；
+- [ ] 局部更新后未传字段保持不变；
+- [ ] 逻辑删除成功；
+- [ ] 删除后详情查询返回 404。
+