FastAPI 入门教程：从零构建第一个 REST API

FastAPI 是一个现代、快速的 Python Web 框架，特别适合构建 REST API、后端服务和微服务。它基于 Python 类型提示，可以自动生成接口文档，并且开发体验非常清爽。

本文会带你从零开始创建一个 FastAPI 项目，实现一个简单的任务管理 API。

1. 为什么选择 FastAPI

FastAPI 的核心优势包括：

性能好：底层基于 Starlette 和 ASGI。
开发效率高：用类型提示描述请求和响应。
自动文档：默认提供 Swagger UI 和 ReDoc。
数据校验方便：基于 Pydantic 自动校验请求体。
适合工程化：依赖注入、路由拆分、中间件都比较完善。

如果你熟悉 Flask，FastAPI 可以看成是更现代、更重视类型和 API 文档的选择。

2. 创建项目环境

先创建一个项目目录：

mkdir fastapi-demo
cd fastapi-demo

创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate

Windows PowerShell 可以使用：

.venv\Scripts\Activate.ps1

安装依赖：

pip install fastapi uvicorn

其中 fastapi 是框架本身，uvicorn 是 ASGI 服务器，用来运行应用。

3. 编写第一个 FastAPI 应用

创建 main.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}

启动服务：

uvicorn main:app --reload

打开浏览器访问：

http://127.0.0.1:8000

你会看到返回结果：

{
  "message": "Hello FastAPI"
}

4. 查看自动接口文档

FastAPI 会自动生成接口文档：

Swagger UI：http://127.0.0.1:8000/docs
ReDoc：http://127.0.0.1:8000/redoc

这对于后端开发非常实用。你可以在页面里直接查看接口、填写参数并发送请求。

5. 路径参数和查询参数

路径参数写在 URL 路径中：

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

这里 user_id: int 表示 FastAPI 会把参数转换成整数。如果传入无法转换的值，FastAPI 会自动返回 422 错误。

查询参数写在函数参数里，但不出现在路径中：

@app.get("/search")
def search(keyword: str, page: int = 1):
    return {"keyword": keyword, "page": page}

访问示例：

/search?keyword=fastapi&page=2

6. 使用 Pydantic 定义请求体

创建任务时，通常需要接收 JSON 请求体。FastAPI 推荐用 Pydantic 模型描述数据结构：

from pydantic import BaseModel

class TaskCreate(BaseModel):
    title: str
    done: bool = False

然后添加创建接口：

@app.post("/tasks")
def create_task(task: TaskCreate):
    return {"id": 1, "title": task.title, "done": task.done}

请求体示例：

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

FastAPI 会自动完成 JSON 解析、字段校验和文档生成。

7. 构建一个简单任务 API

下面实现一个内存版任务列表，适合学习接口结构：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class TaskCreate(BaseModel):
    title: str
    done: bool = False

class Task(TaskCreate):
    id: int

tasks: list[Task] = []
next_id = 1

@app.post("/tasks", response_model=Task)
def create_task(task: TaskCreate):
    global next_id
    new_task = Task(id=next_id, title=task.title, done=task.done)
    tasks.append(new_task)
    next_id += 1
    return new_task

@app.get("/tasks", response_model=list[Task])
def list_tasks():
    return tasks

@app.get("/tasks/{task_id}", response_model=Task)
def get_task(task_id: int):
    for task in tasks:
        if task.id == task_id:
            return task
    raise HTTPException(status_code=404, detail="Task not found")

这个示例包含三个接口：

POST /tasks：创建任务。
GET /tasks：获取任务列表。
GET /tasks/{task_id}：根据 ID 获取单个任务。

response_model 可以限制和声明响应结构，让文档更准确。

8. 常见项目结构

当项目变大后，不建议所有代码都写在 main.py。可以按下面的结构拆分：

fastapi-demo/
  app/
    main.py
    routers/
      tasks.py
    schemas/
      task.py
    services/
      task_service.py

常见分层方式：

routers：放接口路由。
schemas：放 Pydantic 数据模型。
services：放业务逻辑。
main.py：创建应用、注册路由和中间件。

这种拆分可以让接口、数据结构和业务逻辑更清晰。

9. 开发建议

学习 FastAPI 时，可以按这个顺序推进：

先掌握路由、路径参数和查询参数。
再学习 Pydantic 请求体和响应模型。
然后接入数据库，例如 SQLite、PostgreSQL。
最后补充认证、日志、异常处理和测试。

不要一开始就把项目设计得过于复杂。先跑通一个最小 API，再逐步加入数据库和业务功能。

10. 总结

FastAPI 的入门门槛不高，但它的工程化能力很强。对于 Python 后端开发来说，它非常适合用来构建清晰、可维护、带自动文档的 API 服务。

本文完成了：

安装 FastAPI 和 Uvicorn。
创建第一个接口。
使用路径参数和查询参数。
使用 Pydantic 接收请求体。
实现一个简单的任务管理 API。

接下来你可以尝试把内存任务列表替换成数据库存储，这样就能进一步接近真实项目。