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

一、开篇：FastAPI是什么？我能用它做什么？

你可能听说过“后端”这个词，但它到底是什么呢？简单来说，后端就是处理网站数据和逻辑的那一部分。比如你在微信上发消息、在淘宝上下单、在抖音看视频，这些操作背后都有一个“看不见的程序”在运转，这个程序就运行在后端。

FastAPI 是一个基于 Python 的现代后端开发框架，它能帮助我们快速创建高性能、易于维护的 Web 接口（API）。它的设计非常友好，特别适合刚接触编程的新手，并且支持自动化的接口文档生成，让你写完接口就能自动生成网页版说明文档！

✅ FastAPI 的特点：

• 快速（性能堪比 Node.js 和 Go）
• 易学易用
• 支持异步编程
• 自动生成 API 文档（Swagger 和 ReDoc）
• 基于最新的 Python 特性（如类型提示）

在这篇教程中，我们将从零开始学习如何使用 FastAPI 来构建一个简单的后端服务，即使你之前没写过后台代码也没关系！我们会一步一步带你走完整个过程。

---

二、环境准备：搭建你的第一个 FastAPI 开发环境

1. 安装 Python

FastAPI 是基于 Python 的，所以第一步你要安装好 Python 3.8 及以上版本。

你可以通过以下命令查看是否已经安装了 Python：

python --version

如果显示类似 Python 3.9.x 或更高版本，那就没问题；如果没有安装，请前往 Python官网 下载安装。

2. 安装 FastAPI 和 Uvicorn

FastAPI 本身只是一个框架，我们需要一个服务器来运行它。这里我们使用 Uvicorn —— 一个专为 FastAPI 提供高性能的 ASGI 服务器。

打开终端或命令行工具，运行以下命令安装 FastAPI 和 Uvicorn：

pip install fastapi uvicorn

💡 小技巧：如果你使用的是 Python 虚拟环境（建议这么做），请先创建虚拟环境再安装这些包。

3. 验证安装是否成功

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

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "欢迎来到我的第一个 FastAPI 项目！"}

保存之后，在终端执行下面这条命令启动服务：

uvicorn main:app --reload

解释一下这条命令：

• uvicorn 是我们用的服务器
• main 是你的 Python 文件名（不带 .py）
• app 是我们在代码里创建的 FastAPI 实例对象
• --reload 表示当代码变化时自动重启服务（非常适合开发阶段）

然后打开浏览器，访问 http://127.0.0.1:8000，你应该能看到类似下面的 JSON 数据：

{
  "message": "欢迎来到我的第一个 FastAPI 项目！"
}

🎉 恭喜你，你的第一个 FastAPI 网站已经跑起来了！

---

三、核心概念：通俗讲解几个关键词

刚开始学后端开发，可能会遇到一些专业术语，比如“GET 请求”、“路由”、“API”。别担心，我来用最简单的语言解释给你听。

1. 什么是“API”？

API 的全称是 Application Programming Interface，翻译成中文就是应用程序编程接口。说人话就是：“别人可以通过特定的方式调用你写的代码。”

比如你想做一个天气查询的功能，你可以把这部分功能做成一个 API。这样其他程序员或者前端页面只需要发送一个请求（request）给这个 API，就能得到天气数据。

2. 什么是“路由”？

想象一下你在玩“连连看”，每条线代表一个路径。在网络请求中，“路由”就是根据不同的 URL 地址找到对应的函数去执行。

例如：

• 当用户访问 /users/1，系统就会执行“获取用户信息”的函数；
• 当用户访问 /login，系统就会执行“登录验证”的函数。

这就是路由的工作方式。

3. 什么是“HTTP 方法”？

HTTP 方法是指客户端（比如浏览器）向服务器请求资源的方式。最常见的几种方法如下：

HTTP 方法	含义
GET	获取数据（比如读取文章内容）
POST	提交数据（比如注册账号）
PUT	更新数据（比如修改个人信息）
DELETE	删除数据（比如删除一条评论）

在 FastAPI 中，我们可以像这样分别定义这些方法：

@app.get("/items")
def get_items():
    return {"action": "GET"}

@app.post("/items")
def create_item():
    return {"action": "POST"}

你访问 http://localhost:8000/items 会看到返回 "action": "GET"，而用 POST 方法访问，则会变成 "action": "POST"。

🧪 小实验：可以尝试用浏览器访问上面的例子，看看结果是否一致；也可以使用 Postman 进行不同类型的请求测试。

4. 什么是“参数”？

很多时候，我们的 API 需要接收一些来自用户的数据，例如用户名、密码、ID等。这些数据就是“参数”。

（1）路径参数（Path Parameters）

路径参数就是在 URL 路径中包含变量的部分。

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

访问 /users/123，你会得到：

{
  "user_id": "123"
}

注意：这里的参数默认是字符串类型，如果你想让它是数字，可以在参数后面加类型声明：

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

这时候如果传入非数字，比如 /users/hello，FastAPI 会自动返回错误提示。

（2）查询参数（Query Parameters）

查询参数是附加在 URL 后面的键值对，通常用于筛选或排序。

比如我们想通过名字搜索用户：

@app.get("/search")
def search_users(name: str = None, age: int = None):
    return {"name": name, "age": age}

访问 /search?name=Tom&age=25，返回结果如下：

{
  "name": "Tom",
  "age": 25
}

可以看到，查询参数是可选的，因为我们在代码里写了默认值（None）。

---

四、实战项目：做一个简易学生管理系统

接下来我们动手做一个小项目：学生信息管理系统，实现以下几个功能：

• 获取所有学生列表
• 添加一个新学生
• 根据 ID 查询某个学生
• 修改学生信息
• 删除学生信息

第一步：初始化项目结构

新建一个文件夹，比如叫 student-api，在其中创建文件 main.py。

我们先把基础模块写好：

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

app = FastAPI()

# 学生模型
class Student(BaseModel):
    id: int
    name: str
    age: int
    email: str

# 用来存储学生的模拟数据库（实际项目应使用数据库）
students_db = []

这里我们引入了 Pydantic 的 BaseModel，它可以帮我们自动验证数据格式。这很重要！

第二步：获取所有学生（GET）

@app.get("/students", response_model=List[Student])
def get_students():
    return students_db

访问 /students，现在数据库是空的，但你可以用 POST 先添加几条数据后再查看。

第三步：新增学生（POST）

@app.post("/students")
def add_student(student: Student):
    students_db.append(student)
    return {"message": "学生已添加"}

你可以用 Postman 或 curl 测试提交一条数据：

{
  "id": 1,
  "name": "张三",
  "age": 20,
  "email": "zhangsan@example.com"
}

第四步：根据 ID 查询学生（GET）

@app.get("/students/{student_id}", response_model=Student)
def get_student(student_id: int):
    for student in students_db:
        if student.id == student_id:
            return student
    return {"error": "未找到该学生"}

访问 /students/1，你会看到刚才添加的学生数据。

第五步：更新学生信息（PUT）

@app.put("/students/{student_id}")
def update_student(student_id: int, updated_student: Student):
    for i, student in enumerate(students_db):
        if student.id == student_id:
            students_db[i] = updated_student
            return {"message": "学生信息已更新"}
    return {"error": "未找到该学生"}

第六步：删除学生（DELETE）

@app.delete("/students/{student_id}")
def delete_student(student_id: int):
    for i, student in enumerate(students_db):
        if student.id == student_id:
            del students_db[i]
            return {"message": "学生已删除"}
    return {"error": "未找到该学生"}

---

五、常见问题答疑区

下面是很多初学者常问的问题，看看有没有你遇到的困惑：

Q1：FastAPI 和 Flask 有什么区别？

FastAPI 比 Flask 更新，内置异步支持和更现代化的特性。Flask 更适合小型项目，FastAPI 更适合需要高性能和复杂逻辑的项目。

---

Q2：为什么访问 API 返回 404？

检查你的 URL 是否正确，以及是否启用了正确的 HTTP 方法。另外检查是否有拼写错误，比如路由名字写错了。

---

Q3：为什么 POST 请求的数据不生效？

有可能是你没有传入符合定义的数据结构（Pydantic Model），FastAPI 会自动校验格式，如果不符合就会报错。

---

Q4：怎么让 FastAPI 支持数据库？

目前我们是用 Python 列表模拟数据库。实际项目中，可以连接 MySQL、PostgreSQL、MongoDB 等数据库。后续我们会专门讲。

---

Q5：FastAPI 怎么部署上线？

可以用 Gunicorn + Nginx，或者使用 Docker 包装整个项目。FastAPI 部署非常灵活。

---

六、学习建议：下一步怎么学？

你现在已经掌握了 FastAPI 的基本使用。接下来你可以沿着这几个方向继续提升自己：

✅ 方向 1：深入掌握数据交互（数据库连接）

• 学习 SQLAlchemy 或 Tortoise ORM 连接数据库
• 实践项目：做一个完整的博客后台系统

✅ 方向 2：掌握权限管理（认证 & 授权）

• 学习 JWT、OAuth2 认证机制
• 实践项目：用户登录系统

✅ 方向 3：异步编程 & 性能优化

• 学习 async/await 异步语法
• 实战项目：并发请求处理、高并发场景优化

✅ 方向 4：自动化测试 & 单元测试

• 使用 pytest 编写单元测试
• 自动化部署流程

---

结语：坚持练习才是关键！

FastAPI 并不难，只要多写代码、多做项目、多思考问题，你就一定能成为一个优秀的后端开发者！

如果你刚刚完成了这篇文章的学习，不妨试着扩展本节的小项目：

🧠 尝试挑战：

• 给学生加一个“年级”字段
• 实现分页功能（limit、offset）
• 实现按年龄区间筛选学生

最后提醒一句：学习编程一定要亲手敲代码，不要只是看！

Happy coding! 🧑‍💻