Skip to content

第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 应该已经重新加载。

  1. 打开 http://127.0.0.1:8000/docs。现在您拥有了一整套 CRUD 操作!
  2. POST: 展开 POST /spaceships 端点,点击“Try it out”,填写 JSON 体(例如,创建一个“詹姆斯·韦伯望远镜”),然后点击“Execute”。您应该会收到 201 响应,其中包含新望远镜的数据。
  3. GET: 现在执行 GET /spaceships。您的新望远镜应该会出现在列表中。
  4. PUT: 使用新望远镜的 ID,通过 PUT /spaceships/{ship_id} 更新其数据。例如,更改其状态。
  5. DELETE: 使用相同的 ID,通过 DELETE /spaceships/{ship_id} 删除望远镜。您应该会收到状态为 204 的空响应。
  6. 检查: 再次执行 GET /spaceships,以确认望远镜已从列表中删除。

巩固测验

1. 创建新资源使用哪个 HTTP 方法?

2. `DELETE` 操作的标准成功状态码是:

3. FastAPI 如何从 POST 请求体中获取数据?

4. `raise HTTPException(status_code=404)` 用于:

5. 为什么为创建资源(`POST`)创建了一个单独的 `SpaceshipCreate` 模型?


🚀 本章总结:

您已经实现了完整的 CRUD 周期,并将您的 API 从简单的“信息显示板”转变为一个成熟的 舰队控制中心

  • Create:POST /spaceships 用于发射新航天器。
  • Read:GET /spaceshipsGET /spaceships/{id} 用于获取数据。
  • Update:PUT /spaceships/{id} 用于更新任务。
  • Delete:DELETE /spaceships/{id} 用于报废航天器。

您的舰队尽在掌握! 在下一章中,我们将看到 FastAPI 如何自动为我们创建了详细的“操作手册”——交互式 Swagger 文档。

📌 检查:

  • 所有 5 个端点(GET (2)、POSTPUTDELETE)在 /docs 中可见并正常工作。
  • 您可以成功创建、读取、更新和删除资源。
  • 请求不存在的 ID 时返回 404 错误。

⚠️ 如果出现错误:

  • NameError:检查您是否导入了 HTTPExceptionResponsestatus
  • KeyError:您可能正在尝试访问已删除的 ID。
  • PUTPOST 操作不正确:请确保在函数参数中使用了正确的 Pydantic 模型(SpaceshipCreate)。