第3.4章:航天器的CRUD操作
学习时间: 1小时
1. CRUD:航天任务的完整管理周期
到目前为止,我们只读取了数据(Read
)。但真正的飞行控制中心必须能够做到一切:
- Create(创建):将新卫星送入轨道。
- Read(读取):查询现有航天器的状态。
- Update(更新):调整轨道或更新软件。
- Delete(删除):让旧卫星脱离轨道。
这四项操作——CRUD——构成了大多数API的基础。在本章中,我们将实现管理我们舰队的完整周期。
2. 创建:发射新飞船 (POST)
为了创建新的航天器,我们将使用 POST
方法。新飞船的数据将以 JSON 格式在请求体中传输。
步骤1:为传入数据创建新的 Pydantic 模型
为什么需要新模型?因为在创建飞船时,我们不知道它的 id
——它应该由服务器分配。
将此模型添加到 main.py
:
# main.py
from pydantic import BaseModel, Field
class SpaceshipCreate(BaseModel):
"""用于创建新飞船的模型(不带ID)。"""
name: str = Field(..., min_length=3, max_length=50)
type: str
launch_year: int = Field(..., gt=1950)
status: str
Spaceship
几乎相同,但它将用于传入数据验证。
步骤2:实现 POST /spaceships
端点
# main.py
import random # 在文件顶部添加此导入
# ... 其他代码 ...
@app.post("/spaceships", response_model=Spaceship, status_code=201)
def create_spaceship(ship: SpaceshipCreate):
"""
将新的航天器添加到注册表中。
"""
# 为飞船生成新的唯一ID
new_id = max(db_spaceships.keys() or [0]) + 1
# 创建与完整 Spaceship 模型对应的飞船对象
new_ship = Spaceship(id=new_id, **ship.dict())
# 保存到我们的“数据库”中
db_spaceships[new_id] = new_ship.dict()
return new_ship
@app.post(...)
:用于POST
请求的装饰器。status_code=201
:指示成功创建时应返回201 Created
状态码。ship: SpaceshipCreate
:这就是魔法!FastAPI 将自动获取请求体 (JSON),根据SpaceshipCreate
模型对其进行验证,并将其作为ship
对象传递给函数。new_id = ...
:生成新ID的简单逻辑。**ship.dict()
:我们“解包”从接受的ship
模型中获取的数据到我们的完整模型中。response_model=Spaceship
:响应将符合完整模型,包括id
。
3. 更新:航向修正 (PUT)
为了完整更新现有资源,使用 PUT
方法。
实现 PUT /spaceships/{ship_id}
端点:
# main.py
from fastapi import FastAPI, HTTPException # 更新导入
# ... 其他代码 ...
@app.put("/spaceships/{ship_id}", response_model=Spaceship)
def update_spaceship(ship_id: int, ship_update: SpaceshipCreate):
"""
完整更新航天器数据。
"""
if ship_id not in db_spaceships:
raise HTTPException(status_code=404, detail="航天器未找到")
updated_ship = Spaceship(id=ship_id, **ship_update.dict())
db_spaceships[ship_id] = updated_ship.dict()
return updated_ship
ship_update: SpaceshipCreate
:我们再次使用我们的模型来验证传入数据。HTTPException
:如果找不到具有该id
的飞船,我们“抛出”标准的 FastAPI 异常,它将转换为带有404
代码的漂亮 JSON 响应。
4. 删除:脱离轨道 (DELETE)
为了删除资源,使用 DELETE
方法。通常此类端点不返回响应体。
实现 DELETE /spaceships/{ship_id}
端点:
# main.py
from fastapi import FastAPI, HTTPException, Response, status # 更新导入
# ... 其他代码 ...
@app.delete("/spaceships/{ship_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_spaceship(ship_id: int):
"""
从注册表中删除航天器。
"""
if ship_id not in db_spaceships:
raise HTTPException(status_code=404, detail="航天器未找到")
del db_spaceships[ship_id]
# 返回状态码为 204 的空响应
return Response(status_code=status.HTTP_204_NO_CONTENT)
status_code=status.HTTP_204_NO_CONTENT
:我们明确指定状态204 No Content
。del db_spaceships[ship_id]
:从我们的字典中删除记录。return Response(...)
:返回空响应,因为客户端不需要关于已删除对象的数据。
5. 在 /docs
中测试完整周期
您的 uvicorn
应该已经重新加载。
- 打开
http://127.0.0.1:8000/docs
。现在您拥有了一整套 CRUD 操作! - POST: 展开
POST /spaceships
端点,点击“Try it out”,填写 JSON 体(例如,创建一个“詹姆斯·韦伯望远镜”),然后点击“Execute”。您应该会收到201
响应,其中包含新望远镜的数据。 - GET: 现在执行
GET /spaceships
。您的新望远镜应该会出现在列表中。 - PUT: 使用新望远镜的 ID,通过
PUT /spaceships/{ship_id}
更新其数据。例如,更改其状态。 - DELETE: 使用相同的 ID,通过
DELETE /spaceships/{ship_id}
删除望远镜。您应该会收到状态为204
的空响应。 - 检查: 再次执行
GET /spaceships
,以确认望远镜已从列表中删除。
巩固测验
🚀 本章总结:
您已经实现了完整的 CRUD 周期,并将您的 API 从简单的“信息显示板”转变为一个成熟的 舰队控制中心!
- ✅ Create:
POST /spaceships
用于发射新航天器。 - ✅ Read:
GET /spaceships
和GET /spaceships/{id}
用于获取数据。 - ✅ Update:
PUT /spaceships/{id}
用于更新任务。 - ✅ Delete:
DELETE /spaceships/{id}
用于报废航天器。
您的舰队尽在掌握! 在下一章中,我们将看到 FastAPI 如何自动为我们创建了详细的“操作手册”——交互式 Swagger 文档。
📌 检查:
- 所有 5 个端点(
GET
(2)、POST
、PUT
、DELETE
)在/docs
中可见并正常工作。- 您可以成功创建、读取、更新和删除资源。
- 请求不存在的 ID 时返回
404
错误。⚠️ 如果出现错误:
NameError
:检查您是否导入了HTTPException
、Response
、status
。KeyError
:您可能正在尝试访问已删除的 ID。PUT
或POST
操作不正确:请确保在函数参数中使用了正确的 Pydantic 模型(SpaceshipCreate
)。