FastAPI 从零搭建 Web API：Python 后端开发完整入门教程

FastAPI 是一个基于 Python 的现代 Web 框架，主要用于构建 Web API、后端服务和数据接口。它支持类型注解、自动参数校验、异步编程，并且可以自动生成交互式 API 文档。

对于 Python 初学者来说，FastAPI 是学习后端开发的一个不错的选择。通过一个简单的任务管理 API，我们可以逐步掌握环境配置、路由设计、请求参数、数据校验、增删改查以及服务器部署的基本方法。

本文使用 Python、FastAPI 和 Pydantic 构建示例项目。为了便于入门，数据暂时保存在内存中，后续再介绍如何接入数据库。

一、FastAPI 是什么？

FastAPI 是一个用于构建 API 的 Python Web 框架。它使用 Python 类型注解描述参数和数据结构，并通过 Pydantic 进行数据校验。

FastAPI 的主要特点包括：

• 开发效率高： 可以通过简洁的 Python 代码定义接口。

• 自动数据校验： 对请求参数和请求体进行类型及格式检查。

• 自动生成 API 文档： 默认提供 Swagger UI 和 ReDoc。

• 支持异步编程： 可以使用 async def 编写异步接口。

• 便于扩展： 可以与 MySQL、PostgreSQL、Redis 等组件集成。

FastAPI 适合开发用户系统、内容管理后台、数据服务、移动端接口和前后端分离项目。

二、安装 Python 和 FastAPI

1. 检查 Python 环境

首先确保系统已经安装 Python 3.10 或更新版本。

在 Windows 终端中执行：

python --version

Linux 系统可以执行：

python3 --version

如果命令能够正常显示版本号，就可以继续配置开发环境。

2. 创建项目目录

新建一个名为 fastapi-demo 的目录：

mkdir fastapi-demo
cd fastapi-demo

3. 创建虚拟环境

虚拟环境可以隔离不同项目的 Python 依赖，避免不同项目安装的库互相影响。

Windows：

python -m venv .venv
.venv\Scripts\activate

Debian 或其他 Linux 系统：

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

如果 Debian 提示缺少 venv 模块，可以安装：

sudo apt update
sudo apt install python3-venv

4. 安装 FastAPI

在虚拟环境激活后执行：

python -m pip install --upgrade pip
python -m pip install "fastapi[standard]"

其中，fastapi[standard] 会安装 FastAPI 及其常用标准依赖，包括开发服务器相关工具。

三、创建第一个 FastAPI 应用

在项目目录中创建 main.py，输入以下代码：

from fastapi import FastAPI

app = FastAPI(
    title="我的第一个 API",
    description="一个简单的 FastAPI 入门项目",
    version="1.0.0",
)


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


@app.get("/hello/{name}")
def say_hello(name: str):
    return {"message": f"Hello, {name}!"}

代码解释：

• FastAPI()：创建应用实例。

• @app.get("/")：定义一个处理 GET 请求的路由。

• @app.get("/hello/{name}")：定义带有路径参数的接口。

• name: str：声明参数为字符串类型。

• return：返回 Python 字典，FastAPI 会将其转换为 JSON 响应。

启动开发服务器

在项目目录中执行：

fastapi dev main.py

启动成功后，根据终端提示访问本地地址，通常是：

http://127.0.0.1:8000

浏览器会显示：

{
  "message": "Hello, FastAPI!"
}

再访问 /hello/Python，就会得到对应的问候信息。

四、使用自动生成的 API 文档

FastAPI 的一个重要优势是能够根据路由、类型注解和数据模型自动生成 API 文档。

启动服务后，可以访问以下地址：

例如：

http://127.0.0.1:8000/docs

打开 Swagger UI 后，可以查看接口参数、填写请求数据并直接发送请求。

开发过程中，这种方式能够大幅减少手动编写和维护接口文档的工作量。

需要注意：默认文档地址适用于开发和调试。正式部署时，应根据项目的安全需求决定是否限制文档访问。

五、学习路径参数、查询参数和请求体

Web API 经常需要接收客户端传入的数据。FastAPI 常见的参数类型包括路径参数、查询参数和请求体。

1. 路径参数

路径参数用于表示资源标识或路径中的动态部分。

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

请求：

GET /users/123

返回：

{
  "user_id": 123
}

如果传入的 user_id 不是有效整数，FastAPI 会返回参数校验错误，而不是直接把非法值传入函数。

2. 查询参数

查询参数通常用于搜索、筛选和分页。

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

请求示例：

GET /search?keyword=Python&page=2

其中，keyword 是必填参数，page 的默认值为 1。

3. 请求体与 Pydantic 模型

当客户端需要提交一组结构化数据时，可以使用 Pydantic 模型。

from pydantic import BaseModel, Field


class UserCreate(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    age: int = Field(ge=1, le=120)


@app.post("/users")
def create_user(user: UserCreate):
    return {
        "message": "用户创建成功",
        "user": user.model_dump(),
    }

客户端发送 POST 请求时，可以提交以下 JSON：

{
  "name": "张三",
  "age": 25
}

FastAPI 会根据 UserCreate 自动校验请求体。如果名称长度不符合要求，或者年龄不在规定范围内，就会返回相应的校验错误。

这里的接口只演示了参数校验，并没有真正把用户保存到数据库中。

六、实战：开发一个任务管理 API

下面将上述知识整合起来，开发一个支持任务新增、查询、修改和删除的简单 API。

为方便运行，本示例将数据保存在内存字典中。服务器进程重启后，数据会丢失，因此它适合学习和测试，不适合直接作为正式业务的数据存储方案。

1. 完整项目代码

将 main.py 替换为以下代码：

from itertools import count

from fastapi import FastAPI, HTTPException, Response, status
from pydantic import BaseModel, Field

app = FastAPI(
    title="任务管理 API",
    description="用于演示任务的增删改查",
    version="1.0.0",
)

tasks = {}
task_ids = count(1)


class TaskCreate(BaseModel):
    title: str = Field(min_length=1, max_length=100)
    description: str = Field(default="", max_length=500)
    completed: bool = False


class TaskUpdate(BaseModel):
    title: str | None = Field(default=None, min_length=1, max_length=100)
    description: str | None = Field(default=None, max_length=500)
    completed: bool | None = None


@app.get("/")
def home():
    return {"message": "任务管理 API 运行正常"}


@app.post("/tasks", status_code=status.HTTP_201_CREATED)
def create_task(task: TaskCreate):
    task_id = next(task_ids)

    new_task = {
        "id": task_id,
        **task.model_dump(),
    }

    tasks[task_id] = new_task
    return new_task


@app.get("/tasks")
def list_tasks():
    return list(tasks.values())


@app.get("/tasks/{task_id}")
def get_task(task_id: int):
    task = tasks.get(task_id)

    if task is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="任务不存在",
        )

    return task


@app.patch("/tasks/{task_id}")
def update_task(task_id: int, update: TaskUpdate):
    task = tasks.get(task_id)

    if task is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="任务不存在",
        )

    changes = update.model_dump(exclude_unset=True)
    task.update(changes)

    return task


@app.delete("/tasks/{task_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_task(task_id: int):
    if task_id not in tasks:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="任务不存在",
        )

    del tasks[task_id]
    return Response(status_code=status.HTTP_204_NO_CONTENT)

这里使用了 Python 3.10 及以上版本支持的联合类型语法，例如 str | None。

2. 理解四种核心操作

这类接口设计通常被称为 CRUD，即创建、读取、更新和删除。

其中，PATCH 用于部分更新。例如，只提交 {"completed": true}，就可以修改任务的完成状态，而不必重新提交所有字段。

3. 测试任务接口

启动服务器：

fastapi dev main.py

打开 /docs，可以直接测试各个接口。

也可以使用 curl 测试创建任务：

curl -X POST "http://127.0.0.1:8000/tasks" \
  -H "Content-Type: application/json" \
  -d '{"title":"学习 FastAPI","description":"完成第一个 API","completed":false}'

查询任务：

curl "http://127.0.0.1:8000/tasks"

修改任务状态：

curl -X PATCH "http://127.0.0.1:8000/tasks/1" \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

删除任务：

curl -X DELETE "http://127.0.0.1:8000/tasks/1"

以上命令适用于支持 curl 的终端。Windows PowerShell 中，curl 可能被定义为其他命令的别名，遇到差异时可以使用 curl.exe，或者直接在 Swagger UI 中测试。

七、如何组织正式项目的目录结构？

当 API 功能逐渐增加时，不建议把所有路由、数据模型和业务逻辑都放在一个文件里。

可以采用以下基础结构：

fastapi-demo/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── routers/
│   │   ├── __init__.py
│   │   └── tasks.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   └── task.py
│   ├── services/
│   │   └── task_service.py
│   └── db/
│       └── session.py
├── tests/
│   └── test_tasks.py
├── .env
├── .gitignore
└── requirements.txt

各目录的职责如下：

• main.py：创建 FastAPI 应用并注册路由。

• routers/：定义 HTTP 接口。

• schemas/：定义请求和响应的数据模型。

• services/：编写业务逻辑。

• db/：管理数据库连接和会话。

• tests/：编写自动化测试。

这是一个便于理解的参考结构，并非 FastAPI 强制要求的目录组织方式。小项目可以从单文件开始，功能增加后再逐步拆分。

八、FastAPI 如何连接数据库？

真实项目通常需要将数据保存到数据库中，而不是使用内存字典。

常见技术组合包括：

• MySQL：适合用户系统、内容管理系统和业务数据存储。

• PostgreSQL：适合关系型业务和复杂查询。

• SQLite：适合本地工具、原型和小型应用。

• Redis：常用于缓存、限流和临时数据存储。

如果准备使用 MySQL，可以进一步学习 SQLAlchemy 或 SQLModel 等工具，用于管理数据模型和数据库操作。

一个较为清晰的请求处理流程是：

客户端请求
    ↓
FastAPI 路由
    ↓
参数校验
    ↓
业务逻辑
    ↓
数据库操作
    ↓
返回 JSON 响应

正式项目还应处理数据库事务、连接池、异常日志、数据迁移和请求超时等问题。

不要将数据库密码直接写进公开代码仓库，也不要为了方便把数据库端口直接暴露到公网。

九、将 FastAPI 部署到 Debian 服务器

当 API 在本地测试正常后，可以将它部署到 Debian 服务器。

1. 安装基础环境

sudo apt update
sudo apt install python3 python3-venv python3-pip

将项目上传到服务器后，进入项目目录并创建虚拟环境：

cd /你的项目目录
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "fastapi[standard]"

正式部署时，建议根据项目的依赖文件安装经过验证的依赖版本，而不是每次都随意升级。

2. 启动服务

假设应用入口为 main.py，可以执行：

fastapi run main.py --host 127.0.0.1 --port 8000

这里将服务绑定到本机回环地址，便于由同一台服务器上的 Nginx 转发请求。

开发阶段使用 fastapi dev，生产环境则应使用适合生产部署的启动方式，并结合进程管理、日志、重启策略和反向代理。

3. 使用 Nginx 反向代理

基本访问流程如下：

用户浏览器
    ↓ HTTPS
Nginx
    ↓ HTTP
127.0.0.1:8000
    ↓
FastAPI 应用

Nginx 负责接收外部请求，再将请求转发给本机 FastAPI 服务。HTTPS 证书可以由 Nginx 配置，并通过合适的证书管理方式进行续期。

生产部署时还应注意：

1. 不要将数据库密码、密钥等敏感信息提交到 Git 仓库。

2. 根据需要配置 HTTPS。

3. 为应用配置系统服务或其他进程管理方案。

4. 设置日志记录与异常监控。

5. 对需要权限的接口实施身份认证和授权。

6. 按照实际需求限制 API 请求频率和资源消耗。

十、学习 FastAPI 的推荐路线

如果你刚开始学习 Python 后端开发，可以按照以下顺序推进：

1. 掌握 Python 基础语法、函数、类、模块和异常处理。

2. 学习 HTTP 方法、状态码、请求头和 JSON。

3. 学习 FastAPI 路由、路径参数、查询参数和请求体。

4. 学习 Pydantic 模型、依赖注入和异常处理。

5. 使用 SQLAlchemy 或 SQLModel 接入数据库。

6. 学习用户认证、权限管理和自动化测试。

7. 使用 Nginx 和进程管理工具部署到 Debian。

8. 尝试开发一个具有实际用途的完整项目。

对于希望从事后端开发的人来说，能够独立完成一个具有数据库、接口校验、权限控制和部署流程的项目，比单纯记忆框架语法更重要。

总结

FastAPI 通过简洁的语法和自动化的数据校验机制，让 Python 开发者能够快速构建 Web API。

本文从环境搭建开始，逐步介绍了路由、参数、Pydantic 数据模型、任务管理 CRUD 接口、项目结构和 Debian 部署的基础知识。

初学者可以先运行示例代码，理解每个接口的工作原理，再逐步引入数据库、认证机制和自动化测试。

当你能够独立设计接口、组织代码、处理异常并完成部署时，就已经迈出了使用 Python 开发真实后端应用的重要一步。

建议将官方文档作为长期参考资料，并在实际开发中结合项目需求选择合适的数据库、部署方式和安全措施。