FastAPI 实战：实现学生信息的新增接口（POST）

前面我们已经完成了学生信息的查询接口，本篇继续按照 RESTful API 规范，实现学生管理中的新增学生信息接口。视频中虽然也规划了修改（PUT）和删除（DELETE），但本节实际编码与测试只完成了 POST 新增部分，下面完整还原这一操作链路。

一、先明确接口设计

按照 RESTful API 的约定，学生相关接口规划如下：

操作	请求方法	路径	成功状态码	失败状态码
获取所有学生	GET	/api/students	200	—
获取单个学生	GET	/api/students/{id}	200	404
新增学生	POST	/api/students	200	400
修改学生	PUT	/api/students/{id}	—	—
删除学生	DELETE	/api/students/{id}	200	—

本篇聚焦第三行：POST /api/students，路径中的 students 注意使用复数形式。

二、编写新增接口代码

使用 app.post 定义路由，URL 与查询接口保持一致，同样是复数 students，并打上「学生管理」标签：

@app.post("/api/students", tags=["学生管理"])
def create_student(student: Dict):
    ...

接口接收一个学生信息，前端传的是 JSON，对应到 Python 中就是字典，因此参数类型使用 Dict。

1. 校验学号是否唯一

新增前必须先判断学号是否已存在：姓名可以重名，但一个班级里学号必须唯一。遍历 fake_student_db，用传入字典的 student_no 与库中每条记录的学号比较，若相同则抛出 400 错误：

for s in fake_student_db:
    if s.get("student_no") == student.get("student_no"):
        raise HTTPException(
            status_code=400,
            detail="该学号已经存在"
        )

2. 自动生成自增 ID

新学生的 ID 不需要前端传入，而是在现有最大 ID 基础上加 1：

new_id = max(s.get("id") for s in fake_student_db) + 1

3. 用字典拆包组装新学生

如果逐个字段 get 再拼装，字段一多就非常繁琐。这里利用字典拆包，一行代码完成「新 ID + 原始字段」的合并：

new_student = {"id": new_id, **student}

可以在 IDLE 中单独验证这个写法：先创建一个字典，再执行拆包拼接，输出结果可以看到 ID 是新增的，其余内容全部来自原始字典。

4. 追加到列表并返回

把新学生追加进 fake_student_db，并将新增后的学生信息作为返回值：

fake_student_db.append(new_student)
return new_student

至此新增接口的代码编写完成。

三、在 Swagger 文档中测试

服务处于启动状态，刷新浏览器后可以看到新增的 POST 接口。进入接口点击 Try it out，在请求体中填写 JSON 格式的学生信息。

1. 第一次测试：JSON 格式错误

直接粘贴从字典拷贝过来的数据会返回 422 错误（json decoder error）。原因是 JSON 格式非常严格：

• 必须使用双引号，不能用单引号；
• 最后一个字段后不能有多余逗号。

2. 第二次测试：学号重复

改成合法 JSON 后再次 Execute，接口返回「学号已经存在」，说明唯一性校验生效。

3. 第三次测试：新增成功

修改姓名（如「安迪」）并换一个未使用的学号（如 104 或 109），点击 Execute，返回状态码 200，响应体是新增后的学生信息，其中 ID 为自动生成，其余字段为提交的内容。

文档下方出现的 validate error 并不是报错，而是接口文档预留的验证失败信息展示区；当前没有错误信息，说明验证通过。后续可以借助 Pydantic 做更规范的数据校验。

四、小结

本节完成了学生管理中的新增接口：

1. 用 app.post 定义 POST /api/students，参数类型为 Dict；
2. 新增前遍历数据库校验学号唯一，重复则抛出 400；
3. 通过 max(...) + 1 生成自增 ID，并用 {"id": new_id, **student} 字典拆包组装新记录；
4. 追加到列表后返回新增学生信息；
5. 在 Swagger 中依次验证了 JSON 格式错误（422）、学号重复（400）和新增成功（200）三种情况。

修改（PUT）与删除（DELETE）接口将在后续内容中继续实现。