Skip to content

第 3.2 章:创建第一个 API 端点

学习时间: 30 分钟


1. 端点:数据对接端口

想象一下,我们的 API 是一个空间站。端点(Endpoint,也称作“终点”)是一个特定的对接端口,专为特定类型的飞船设计。

  • 端口 1 号 —— 用于货运飞船(行星数据)。
  • 端口 2 号 —— 用于探测器(任务数据)。
  • 端口 3 号 —— 用于载客航天飞机(宇航员数据)。

每个端点都是一个唯一的 URL,负责对特定资源执行特定操作。

💡 太空类比: GET /spaceships 这条命令是“任务控制中心 → 空间站:报告所有已停靠飞船的列表”。这个端点返回一个资源集合。


2. 创建“太空舰队”

目前我们还没有数据库,所以先创建一个“模拟”——一个简单的 Python 字典形式的航天器列表。

打开 main.py 并在定义 app 之前添加以下代码:

# main.py

# 步骤 1:创建模拟数据库
db_spaceships = {
    1: {
        "name": "Voyager-1",
        "type": "探测器",
        "launch_year": 1977,
        "status": "活跃"
    },
    2: {
        "name": "Hubble Space Telescope",
        "type": "望远镜",
        "launch_year": 1990,
        "status": "活跃"
    },
    3: {
        "name": "ISS",
        "type": "空间站",
        "launch_year": 1998,
        "status": "在轨"
    }
}

// ... 这里是 app = FastAPI() 的代码
这是我们的“航天器注册表”,我们将用它来工作。


3. 第一个端点:飞船列表

现在,我们将创建一个端点,它将返回我们整个舰队的列表。

main.py 中,将以下代码添加到 @app.get("/") 之后:

# main.py

# ... 包含 db_spaceships, FastAPI, app 和 read_root() 的代码 ...

@app.get("/spaceships")
def get_spaceships():
    """
    返回注册表中所有航天器的列表。
    """
    return db_spaceships

  • @app.get("/spaceships"):我们创建了一个新路由。现在,对 URL /spaceshipsGET 请求将由 get_spaceships 函数处理。
  • return db_spaceships:FastAPI 会自动将 Python 字典转换为正确的 JSON 响应。

4. 测试新对接端口的功能

如果您的 uvicorn 服务器仍在使用 --reload 标志运行,它应该已经重新加载并准备好工作。如果没有,请重新启动它:

uvicorn main:app --reload

步骤 1:在浏览器中测试

在浏览器中打开地址 http://127.0.0.1:8000/spaceships。 您应该会看到完整的飞船列表,格式为 JSON:

{
  "1": {
    "name": "Voyager-1",
    "type": "探测器",
    "launch_year": 1977,
    "status": "活跃"
  },
  "2": {
    "name": "Hubble Space Telescope",
    "type": "望远镜",
    "launch_year": 1990,
    "status": "活跃"
  },
  "3": {
    "name": "ISS",
    "type": "空间站",
    "launch_year": 1998,
    "status": "在轨"
  }
}

步骤 2:在自动文档中测试

访问 http://127.0.0.1:8000/docs。您会看到文档中为 GET /spaceships 端点新增了一个部分。您可以点击“Try it out”和“Execute”直接在那里进行测试!


5. 带参数的端点:特定飞船的数据

如果我们需要“旅行者 1 号”的特定数据怎么办?为此,我们将创建一个带有路径参数(path parameter)的端点。

将以下代码添加到 main.py

# main.py

# ... 其他代码 ...

@app.get("/spaceships/{ship_id}")
def get_spaceship(ship_id: int):
    """
    根据 ID 返回特定航天器的数据。
    """
    return db_spaceships.get(ship_id)

  • "/spaceships/{ship_id}":花括号 {} 告诉 FastAPI,ship_id 是一个将从 URL 传递过来的变量。
  • ship_id: int:这是一个类型提示(type hint)。FastAPI 会自动检查传入的 ID 是否为整数。如果有人请求 /spaceships/voyager,FastAPI 将返回 422 Unprocessable Entity 验证错误。这真是太棒了!

测试:

打开 http://127.0.0.1:8000/spaceships/2。您应该只会收到关于“哈勃”望远镜的数据。如果您打开 http://127.0.0.1:8000/spaceships/99,您将收到 null,因为没有这样的飞船。


巩固知识小测验

1. API 中的端点是...

2. 装饰器 `@app.get("/users")` 的作用是什么?

3. 路径中的 `"/items/{item_id}"` 表示什么?

4. 函数中 `ship_id: int` 的类型提示有什么用?

5. 如果您请求 `/spaceships/abc`,而 FastAPI 期望一个 `int`,会发生什么?


🚀 本章总结:

您已成功在您的 API 空间站上创建了两个“对接端口”:

  • 🛰️ 一个用于获取所有飞船列表 (/spaceships)
  • 🔭 另一个用于获取特定航天器的数据 (/spaceships/{ship_id})

您还看到了 FastAPI 自动类型验证的强大功能,它能保护您的 API 免受不正确请求的影响。

导航系统已设置完毕! 在下一章中,我们将使用 Pydantic 创建我们的航天器“蓝图”,使我们的 API 更智能、更可靠。

📌 检查:

  • uvicorn 服务器已启动并正在运行。
  • URL http://127.0.0.1:8000/spaceships 返回包含飞船列表的 JSON。
  • URL http://127.0.0.1:8000/spaceships/1 返回关于“旅行者 1 号”的数据。
  • URL http://127.0.0.1:8000/docs 显示两个新端点。

⚠️ 如果出现错误:

  • 404 Not Found: 检查浏览器中和装饰器 @app.get(...) 中的 URL 是否正确。
  • 代码错误: 仔细检查语法,尤其是 Python 中的缩进和字典中的逗号。