两小时快速入门 FastAPI--第二回

两小时快速入门 FastAPI--第二回

FastAPI 实战：完成一个简单的 Todo 查询接口

一、FastAPI 简介

FastAPI 是一个用于开发 Web API 的 Python 框架，支持路径参数、查询参数、类型校验和自动接口文档。

本次练习使用 Python 列表临时保存 Todo 数据，并通过不同接口实现：

• 获取全部任务
• 按完成状态筛选任务
• 统计任务数量
• 根据 ID 查询单个任务

项目启动后，可以访问下面的地址查看 Swagger 接口文档：

http://127.0.0.1:8000/docs

---

二、本次任务目标

本次练习主要完成一个简单的 Todo 查询 API：

• 创建临时 Todo 数据
• 获取全部 Todo
• 根据完成状态筛选 Todo
• 统计总任务数和已完成任务数
• 根据任务 ID 查询单个 Todo
• 使用 curl.exe 测试接口

---

三、完成任务的整个流程

1. 编写 Todo API

打开项目中的 main.py，写入以下代码：

from fastapi import FastAPI

# 创建 FastAPI 应用实例。
# title 会显示在自动生成的 Swagger 文档页面里。
app = FastAPI(title="我的两个小时FastAPI练习")

# 定义一个 Todo 列表，作为当前项目的临时数据。（接口下的代办和状态）
# 这里没有连接数据库，所以数据只保存在程序运行时的内存中。
todos = [
    {"id": 1, "title": "学习FastAPI", "done": False},
    {"id": 2, "title": "写一个Todoapi", "done": True},
]

# 定义根路径接口。
# 当访问 http://127.0.0.1:8000/ 时，会执行这个函数。
@app.get("/")
def root():
    # 返回一个简单的 JSON 消息，用来表示服务已经正常启动。
    return {"message": "FastAPI 已经启动"}

# 定义获取 Todo 列表的接口。
# done 是一个可选查询参数，可以按完成状态筛选任务。
# 例如：/todos?done=true 或 /todos?done=false
@app.get("/todos")
def list_todos(done: bool | None = None):
    # 如果没有传入 done 参数，就直接返回全部 Todo。
    if done is None:
        return todos
    # 如果传入了 done 参数，就只返回状态匹配的 Todo。
    return [todo for todo in todos if todo["done"] == done]

# 定义统计 Todo 数量的接口。
# 这个接口会返回总任务数，以及已经完成的任务数。
@app.get("/todos/count")
def todo_count():
    # total 表示全部任务数量。
    # completed 表示 done 为 True 的任务数量。
    return {
        "total": len(todos),
        "completed": len([todo for todo in todos if todo["done"]]),
    }

# 定义根据任务 id 获取单个 Todo 的接口。
# todo_id 是路径参数，例如访问 /todos/1 时，todo_id 的值就是 1。
@app.get("/todos/{todo_id}")
def get_todo(todo_id: int):
    # 遍历 todos 列表，查找 id 和传入参数一致的任务。
    for todo in todos:
        if todo["id"] == todo_id:
            return todo
    # 如果没有找到对应 id 的任务，就返回提示信息。
    return {"message": "Todo not found"}

这里使用的 todos 是一个普通 Python 列表，并没有连接数据库。

因此，数据只会保存在程序运行时的内存中。程序重新启动后，数据会恢复为代码中定义的内容。

结果如图所示：

---

2. 获取 Todo 列表

获取全部任务的接口为：

GET /todos

访问地址：

http://127.0.0.1:8000/todos

还可以通过 done 查询参数筛选任务。

查询已完成任务：

http://127.0.0.1:8000/todos?done=true

查询未完成任务：

http://127.0.0.1:8000/todos?done=false

done 没有出现在接口路径中，因此它属于查询参数。

---

3. 统计 Todo 数量

统计接口为：

GET /todos/count

使用 PowerShell 测试：

curl.exe "http://127.0.0.1:8000/todos/count"

返回结果：

{
  "total": 2,
  "completed": 1
}

其中：

• total 表示全部任务数量
• completed 表示已经完成的任务数量

---

4. 根据 ID 查询 Todo

查询单个任务的接口为：

GET /todos/{todo_id}

其中，todo_id 是路径参数。

查询 ID 为 1 的任务：

curl.exe "http://127.0.0.1:8000/todos/1"

返回：

{
  "id": 1,
  "title": "学习FastAPI",
  "done": false
}

查询 ID 为 2 的任务：

curl.exe "http://127.0.0.1:8000/todos/2"

返回：

{
  "id": 2,
  "title": "写一个Todoapi",
  "done": true
}

如果传入的 ID 不存在，接口会返回：

{
  "message": "Todo not found"
}

需要注意，固定路径 /todos/count 应写在动态路径 /todos/{todo_id} 前面，避免 FastAPI 将 count 当成 todo_id 处理。

---

四、总结

本次练习完成了一个简单的 Todo 查询 API，主要学习了：

• 使用 Python 列表临时保存数据
• 使用查询参数筛选任务
• 使用路径参数查询单个任务
• 使用列表推导式统计和筛选数据
• 使用 curl.exe 测试 FastAPI 接口
• 理解固定路径和动态路径的定义顺序

目前的接口只能查询数据，下一步可以继续增加新增、修改和删除 Todo 的接口，完成一个基础的 Todo CRUD 项目。