第 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/spaceships
的GET
请求将由get_spaceships
函数处理。return db_spaceships
:FastAPI 会自动将 Python 字典转换为正确的 JSON 响应。
4. 测试新对接端口的功能
如果您的 uvicorn
服务器仍在使用 --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
,因为没有这样的飞船。
巩固知识小测验
🚀 本章总结:
您已成功在您的 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 中的缩进和字典中的逗号。