FastAPI 入门：Python 后端开发新手指南

开篇：FastAPI 是什么？它可以做什么？

你可能听说过“后端”这个词，也可能听说过 Python 在后端开发中的强大能力。那么今天我们要介绍的 FastAPI 就是一个基于 Python 的工具，它能帮助我们快速构建一个高效、安全、现代化的后端服务。

换句话说，如果你希望：

• 把你的程序变成一个“网站后台”
• 别人可以通过互联网访问你的程序
• 你的手机应用或者网页能和服务器通信
• 程序能处理用户登录、数据存储、搜索等功能

那么你可以使用 FastAPI 来实现这些功能。

FastAPI 的优点（为什么选它入门？）

1. 上手简单：相比其他后端框架，FastAPI 更容易学习。
2. 性能高：它基于异步编程技术，处理请求非常快。
3. 自动生成文档：写完接口就能直接看到可视化说明。
4. 类型提示支持好：帮助你写出更少错误的代码。
5. 现代标准：符合最新的 API 设计规范（如 OpenAPI、Swagger）。

接下来我们就来一步步走进 FastAPI 的世界！

---

环境准备：如何安装 FastAPI 并运行第一个程序

在开始写代码之前，我们需要准备好开发环境。以下步骤适用于 Windows、macOS 和 Linux。

第一步：确保安装了 Python

FastAPI 是基于 Python 3.6 或以上版本 的，所以你需要先确认你的电脑上已经安装了 Python。

如何检查 Python 是否已安装？

打开终端（Windows 用 CMD，macOS/Linux 用 Terminal），输入：

python --version

或在某些系统中：

python3 --version

如果显示类似 Python 3.10.x 这样的信息，就表示 Python 已安装。如果没有，请先去 官网 下载安装。

---

第二步：安装 FastAPI 和 Uvicorn

FastAPI 自身并不能直接运行，需要借助一个叫做 Uvicorn 的服务器工具来运行程序。

我们使用 pip 来安装它们：

pip install fastapi uvicorn

等待安装完成后，就可以开始写第一个 FastAPI 程序了！

---

第三步：写一个最简单的 FastAPI 应用

新建一个 .py 文件，比如叫 main.py，然后在里面输入如下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, 新手！欢迎来到 FastAPI"}

这段代码做了什么？

• 引入 FastAPI 框架
• 创建了一个名为 app 的服务对象
• 定义了一条路由 /
• 当用户访问 / 时，返回一段信息

---

第四步：运行 FastAPI 应用

在终端里输入：

uvicorn main:app --reload

解释一下这条命令：

• uvicorn：是启动服务器的命令
• main:app：表示从 main.py 文件中加载 app 实例
• --reload：让服务器在代码更改后自动重启（适合开发阶段）

启动成功后，你会看到类似这样的输出：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

这意味着你的服务已经跑起来了，访问这个地址就能看到效果！

---

第五步：访问我们的第一个接口

打开浏览器，输入网址：

http://127.0.0.1:8000

你应该会看到页面上显示：

{"message": "Hello, 新手！欢迎来到 FastAPI"}

这说明你的第一个 FastAPI 接口已经成功运行了！

---

核心概念：通俗易懂地理解 FastAPI 的关键部分

现在我们知道怎么写一个最简单的接口了，但要想真正用起来，还需要了解几个核心概念。

1. 路由（Route）是什么？

想象你在家里有很多个房间，每个房间都有名字，比如“客厅”、“厨房”。当你要找人的时候，你说“我要去厨房”，别人就知道该带你去哪儿。

路由就是这个意思——它是 URL 地址的一部分，用来告诉程序应该执行哪个函数。

例如：

• /users 表示访问用户相关的功能
• /items/3 可能表示获取编号为 3 的商品信息

FastAPI 中通过装饰器定义路由，比如：

@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"id": item_id}

这里的 /items/{item_id} 就是一个带参数的路由。

---

2. 请求方法（HTTP Method）是什么？

不同的 HTTP 方法代表不同的操作意图：

方法	用途
GET	获取数据（如查询）
POST	提交数据（如注册、登录）
PUT	更新数据
DELETE	删除数据

在 FastAPI 中，分别对应：

@app.get("/")
@app.post("/submit")
@app.put("/update")
@app.delete("/remove")

初学者建议优先掌握 GET 和 POST。

---

3. 参数（Parameters）有哪些类型？

FastAPI 支持三种常见的参数传递方式：

（1）路径参数（Path Parameters）

就像前面的例子一样：

@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id}

访问：/items/5 → item_id=5

（2）查询参数（Query Parameters）

在 URL 后面加 “?” 和参数名的方式：

@app.get("/search")
def search(query: str, limit: int = 10):
    return {"query": query, "results_limit": limit}

访问：/search?query=apple&limit=3

（3）请求体参数（Request Body）

用于 POST 请求中传入复杂数据，比如 JSON：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

---

4. 数据模型（Data Models）是什么？

我们刚才用了 BaseModel，它是 FastAPI 依赖的一个库 Pydantic 提供的功能。

作用是什么呢？简单说：

• 验证传来的数据格式是否正确
• 自动生成文档说明字段含义
• 提升代码可读性和健壮性

---

5. 自动文档（Swagger / ReDoc）是怎么来的？

还记得我们在浏览器访问过 http://127.0.0.1:8000 吧？

FastAPI 不仅让你写接口，还能自动生成接口文档！

打开这两个地址看看神奇之处吧：

• Swagger 文档：http://127.0.0.1:8000/docs
• Redoc 文档：http://127.0.0.1:8000/redoc

你不用自己写文档，只需要按照 FastAPI 的规则写接口，它就能帮你生成！

---

实战项目：构建一个“任务清单”服务

为了让新手真正上手，我们一起来做一个小项目：任务清单 API

功能目标：

• 添加任务
• 查看所有任务
• 删除某个任务

步骤一：定义任务的数据结构

创建一个模型类来描述任务的内容：

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

app = FastAPI()

class TaskCreate(BaseModel):
    title: str
    description: str = ""

class Task(TaskCreate):
    id: int

这里有两个类：

• TaskCreate：添加任务时所需的字段
• Task：返回给客户端时使用的完整结构（包括 id）

---

步骤二：模拟数据库 —— 使用列表暂存数据

开发初期我们不连接真正的数据库，先用 Python 列表来存储任务：

tasks = []
next_id = 1

---

步骤三：编写添加任务的接口

POST 接口，接收用户提交的任务数据：

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

测试方法：

用 Swagger 页面调用这个接口试试，传入 title 和 description。

---

步骤四：编写查看全部任务的接口

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

访问 /tasks/ 即可看到所有的任务。

---

步骤五：编写删除任务的接口

from fastapi import HTTPException

@app.delete("/tasks/{task_id}")
def delete_task(task_id: int):
    for i, task in enumerate(tasks):
        if task.id == task_id:
            del tasks[i]
            return {"message": "任务已删除"}
    raise HTTPException(status_code=404, detail="任务未找到")

到这里为止，我们完成了基本的 CRUD 操作（增删查）。

如果你想继续扩展，可以添加：

• 修改某个任务内容（PUT）
• 查询具体某个任务（GET + ID）
• 加入真实数据库支持（比如 SQLite）

---

常见问题解答（FAQ）

Q1：为什么我运行不了 uvicorn 命令？

可能是没有安装 uvicorn。请运行：

pip install uvicorn

---

Q2：我的代码改了但页面没变化？

加上 --reload 参数可以让服务器监听文件变化并自动重启：

uvicorn main:app --reload

---

Q3：FastAPI 返回 404 错误怎么办？

确保你访问的路由路径与代码中定义的一致，比如：

@app.get("/hello")  # 要访问 /hello 而不是 /

---

Q4：为什么 Swagger 文档没有自动更新？

检查是否写了正确的注解和模型，尤其是响应模型：

response_model=Task

---

Q5：可以用 FastAPI 写网页吗？

FastAPI 主要用于提供 API 接口，前端页面通常由别的语言（如 HTML/React/Vue）完成。当然你也完全可以在 FastAPI 中直接返回 HTML 页面内容。

---

学习建议：下一步该学什么？

恭喜你完成了 FastAPI 的第一个实战项目！接下来你可以沿着以下几个方向继续学习：

✅ 继续巩固基础

• 理解异步函数 async def
• 学习中间件和全局异常处理
• 使用 Pydantic 模型做复杂校验
• 学习 JWT 认证、权限管理
• 使用 SQLAlchemy 连接真实数据库

💾 推荐学习资源

1. FastAPI 官方文档（中文版）：
   • https://fastapi.tiangolo.com/
2. 《FastAPI 教程中文》：
   • GitHub 上有中文社区翻译版本
3. YouTube 视频教程（搜关键词：FastAPI tutorial 中文）

🔍 建议的学习顺序

1. Python 基础语法
2. HTTP 协议基础
3. FastAPI 基础 CRUD
4. 数据验证与模型设计
5. 异步与数据库操作
6. 用户认证与部署上线

---

结语

FastAPI 是一个非常适合初学者的后端开发工具。它不仅简单易用，而且文档友好、性能强悍，是你走向专业后端开发的第一把钥匙。

只要你愿意动手敲代码，坚持实践每一个小功能，你就一定能掌握 FastAPI！

祝你学习愉快，早日写出属于自己的网站后台服务！

---

✅ 本文总字数：约 3554 字