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

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

一、FastAPI 简介

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

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

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

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

text 复制代码

http://127.0.0.1:8000/docs

二、本次任务目标

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

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

三、完成任务的整个流程

1. 编写 Todo API

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

python 复制代码

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 列表

获取全部任务的接口为：

text 复制代码

GET /todos

访问地址：

text 复制代码

http://127.0.0.1:8000/todos

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

查询已完成任务：

text 复制代码

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

查询未完成任务：

text 复制代码

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

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

3. 统计 Todo 数量

统计接口为：

text 复制代码

GET /todos/count

使用 PowerShell 测试：

powershell 复制代码

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

返回结果：

json 复制代码

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

其中：

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

4. 根据 ID 查询 Todo

查询单个任务的接口为：

text 复制代码

GET /todos/{todo_id}

其中，todo_id 是路径参数。

查询 ID 为 1 的任务：

powershell 复制代码

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

json 复制代码

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

查询 ID 为 2 的任务：

powershell 复制代码

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

json 复制代码

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

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

json 复制代码

{
  "message": "Todo not found"
}

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

四、总结

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

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

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