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

云端造物者

2025-06-14 03:43

阅读 788

开篇：什么是FastAPI，用来做什么？

你有没有想过，网站或手机App背后的数据是怎么来的？比如你在淘宝上搜索商品时，这些商品信息并不是直接写在网页里的，而是通过一个叫做“接口”（API）从服务器获取的。
而FastAPI，就是帮你快速搭建这种接口的一种工具 —— 它是用 Python 编写的高性能后端框架。

为什么选择 FastAPI？

✅ 速度快：性能接近Go语言级别的速度
✅ 自动文档：写好接口就能自动生成交互式文档
✅ 语法简单：基于 Python 的现代语法（async/await），学习成本低
✅ 适合初学者：结构清晰，代码简洁易懂

无论你是想开发一个简单的个人项目，还是为将来进入职场做准备，FastAPI都是一个非常理想的起点。

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

我们先来安装和配置FastAPI的开发环境。整个过程只需要几分钟，跟着步骤一步一步来就可以。

第一步：安装Python

你需要确保电脑上已经安装了 Python 3.8 或以上版本。

打开终端（Mac/Linux）或命令提示符（Windows），输入：

python --version

如果输出类似下面的内容，说明你已经安装好了 Python：

Python 3.10.4

如果没有安装，请前往Python官网下载并安装。

第二步：创建虚拟环境（推荐）

为了不让我们的项目依赖影响全局Python环境，我们使用虚拟环境。

python -m venv venv

激活虚拟环境：

Windows：

venv\Scripts\activate

Mac/Linux：

source venv/bin/activate

激活成功后，命令行前会出现 (venv) 字样。

第三步：安装FastAPI和Uvicorn

pip install fastapi uvicorn

其中：

fastapi 是主框架
uvicorn 是运行服务的 ASGI 服务器

第四步：验证是否安装成功

新建一个文件 main.py，内容如下：

from fastapi import FastAPI

app = FastAPI()

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

然后在终端中运行：

uvicorn main:app --reload

访问 http://localhost:8000，你会看到页面显示：

{"Hello": "World"}

恭喜！你现在有了一个最简单的FastAPI服务！

核心概念：用通俗的语言解释关键知识

学习任何一门新技术，理解它的核心概念是非常重要的。下面是一些你必须知道的基础术语和概念，我们用通俗易懂的方式来讲解它们。

📌 API 路由（Router）

想象你在一家餐馆点菜：“我要一份宫保鸡丁”。服务员就把这个请求转给厨房处理。这里的“宫保鸡丁”就是一个接口路径，也叫路由。

在FastAPI中，你用装饰器来定义路径。例如：

@app.get("/users")
def get_users():
    return {"message": "这里是所有用户列表"}

当你访问 /users 时，就会触发这个函数返回结果。

📌 请求方法：GET / POST / PUT / DELETE

HTTP协议规定了几种主要的操作方式（方法）：

方法	含义	示例
GET	获取数据	浏览一篇文章
POST	提交数据（创建资源）	注册账号、发布文章
PUT	更新数据	修改某篇文章内容
DELETE	删除数据	删除某条消息

FastAPI中分别用 @app.get()、@app.post() 等来对应这些方法。

📌 请求参数：Query、Path、Body

Query 参数（查询参数）

URL地址后面带的“问号参数”，比如：

/users?name=Tom&age=20

FastAPI中使用普通函数参数即可获取：

@app.get("/users")
def get_user(name: str, age: int):
    return {"name": name, "age": age}

Path 参数（路径参数）

把变量嵌入URL中，例如：

/users/5

对应代码如下：

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

Body 参数（请求体）

通常用于POST等需要提交较大数据的请求，格式通常是JSON。

from pydantic import BaseModel

class UserCreate(BaseModel):
    name: str
    email: str

@app.post("/users")
def create_user(user: UserCreate):
    return {"message": f"用户 {user.name} 已创建", "email": user.email}

📌 自动文档系统（Swagger UI + ReDoc）

当你启动服务后，你可以访问这两个文档页面：

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

你可以在这里查看所有的接口，并直接点击“Try it out”进行测试！

实战项目：动手做一个“学生管理接口”

现在我们来实战演练一下，做一个可以对学生信息进行增删改查（CRUD）的小型接口。

👣 Step 1：初始化项目结构

新建项目目录如下：

student_api/
│
├── main.py
└── models.py

我们将使用一个字典作为临时数据库来保存数据。

👣 Step 2：定义学生模型（models.py）

from pydantic import BaseModel

class StudentBase(BaseModel):
    name: str
    age: int
    grade: str

class StudentCreate(StudentBase):
    pass

class Student(StudentBase):
    id: int

👣 Step 3：编写接口逻辑（main.py）

from fastapi import FastAPI
from models import StudentCreate, Student
import uuid

app = FastAPI()

# 模拟数据库
students_db = {}

@app.post("/students/", response_model=Student)
def create_student(student: StudentCreate):
    student_id = uuid.uuid4().int % 100000  # 生成简短ID
    new_student = Student(**student.dict(), id=student_id)
    students_db[student_id] = new_student
    return new_student

@app.get("/students/{student_id}", response_model=Student)
def read_student(student_id: int):
    return students_db.get(student_id, {"error": "学生不存在"})

@app.get("/students/", response_model=list[Student])
def read_students():
    return list(students_db.values())

@app.put("/students/{student_id}", response_model=Student)
def update_student(student_id: int, student: StudentCreate):
    if student_id not in students_db:
        return {"error": "找不到该学生"}
    updated = Student(**student.dict(), id=student_id)
    students_db[student_id] = updated
    return updated

@app.delete("/students/{student_id}")
def delete_student(student_id: int):
    if student_id not in students_db:
        return {"error": "找不到该学生"}
    del students_db[student_id]
    return {"message": "删除成功"}

👣 Step 4：运行项目并测试接口

运行服务：

uvicorn main:app --reload

打开 http://localhost:8000/docs，你会看到：

点击任意接口尝试调用，比如新增一个学生：

{
  "name": "张三",
  "age": 18,
  "grade": "三年级"
}

你将收到如下的响应：

{
  "name": "张三",
  "age": 18,
  "grade": "三年级",
  "id": 12345
}

常见问题：新手常遇到的问题及解答

如果你在使用过程中遇到一些疑问，下面这些问题可能对你有帮助：

❓ 1. 我访问 `/docs` 页面看不到接口怎么办？

✅ 原因：可能是服务没有启动，或者端口被占用。 🛠️ 解决方法：

检查终端是否出现错误信息
尝试换端口启动：uvicorn main:app --host 0.0.0.0 --port 8001

❓ 2. 报错 “TypeError: Object of type set is not JSON serializable”？

✅ 原因：你返回了一个无法直接转换为JSON的数据类型，比如集合 set。 🛠️ 解决方法：

使用列表（list）代替集合（set）
手动将非标准数据结构转换为可序列化的对象

❓ 3. 为什么要用 Pydantic 模型？

✅ Pydantic 是 FastAPI 推荐的数据校验库。它帮助我们在接收请求数据时：

验证字段是否存在
校验字段类型是否正确
自动生成文档说明

❓ 4. 我能用 FastAPI 开发正式项目吗？

✅ 当然可以！许多公司正在使用FastAPI构建生产级应用。不过要注意以下几点：

使用数据库替代字典模拟的数据
添加日志、异常处理、身份验证等机制
配合数据库 ORM 工具（如SQLAlchemy / Tortoise ORM）

学习建议：下一步可以学什么？

数据库设计模型-1

恭喜你完成了FastAPI的入门学习！下面是几个继续提升的方向建议：

🔹 进阶技能推荐

方向	学习目标
数据库操作	学会使用SQLAlchemy或Tortoise连接MySQL/PostgreSQL
用户认证	使用JWT实现登录、鉴权机制
异步编程	掌握async/await异步调用外部接口的能力
Docker部署	把项目打包成Docker镜像进行部署
测试与调试	写单元测试、日志记录与错误捕获

📚 推荐学习资源

✅ 官方文档：https://fastapi.tiangolo.com （含中文翻译）
✅ B站教程：搜索“FastAPI 入门教程”会有大量手把手实操视频
✅ 书籍推荐：《FastAPI Web Development》英文原版很经典

总结

FastAPI是一个非常适合初学者的后端框架，不仅容易上手，而且功能强大。本文带你一步步完成了环境配置、基础语法、实战项目以及常见问题的解决。

接下来你要做的就是：

多写、多练、多调试；
用自己的项目去实践每一个知识点；
不断扩展你的技术栈。

记住一句话：学编程最好的方式就是“边学边写”。快拿起键盘，开始你的后端之旅吧！

⚠️ 文中涉及的完整代码已上传GitHub（可补充链接）。欢迎star & fork！

标签:教程Python

最热最新

暂无评论

为你推荐

暂无相关推荐

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

开篇：什么是FastAPI，用来做什么？

为什么选择 FastAPI？

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

第一步：安装Python

第二步：创建虚拟环境（推荐）

第三步：安装FastAPI和Uvicorn

第四步：验证是否安装成功

核心概念：用通俗的语言解释关键知识

📌 API 路由（Router）

📌 请求方法：GET / POST / PUT / DELETE

📌 请求参数：Query、Path、Body

Query 参数（查询参数）

Path 参数（路径参数）

Body 参数（请求体）

📌 自动文档系统（Swagger UI + ReDoc）

实战项目：动手做一个“学生管理接口”

👣 Step 1：初始化项目结构

👣 Step 2：定义学生模型（models.py）

👣 Step 3：编写接口逻辑（main.py）

👣 Step 4：运行项目并测试接口

常见问题：新手常遇到的问题及解答

❓ 1. 我访问 `/docs` 页面看不到接口怎么办？

❓ 2. 报错 “TypeError: Object of type set is not JSON serializable”？

❓ 3. 为什么要用 Pydantic 模型？

❓ 4. 我能用 FastAPI 开发正式项目吗？

学习建议：下一步可以学什么？

🔹 进阶技能推荐

📚 推荐学习资源

总结

评论 0

为你推荐

精选内容

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

开篇：什么是FastAPI，用来做什么？

为什么选择 FastAPI？

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

第一步：安装Python

第二步：创建虚拟环境（推荐）

第三步：安装FastAPI和Uvicorn

第四步：验证是否安装成功

核心概念：用通俗的语言解释关键知识

📌 API 路由（Router）

📌 请求方法：GET / POST / PUT / DELETE

📌 请求参数：Query、Path、Body

Query 参数（查询参数）

Path 参数（路径参数）

Body 参数（请求体）

📌 自动文档系统（Swagger UI + ReDoc）

实战项目：动手做一个“学生管理接口”

👣 Step 1：初始化项目结构

👣 Step 2：定义学生模型（models.py）

👣 Step 3：编写接口逻辑（main.py）

👣 Step 4：运行项目并测试接口

常见问题：新手常遇到的问题及解答

❓ 1. 我访问 /docs 页面看不到接口怎么办？

❓ 2. 报错 “TypeError: Object of type set is not JSON serializable”？

❓ 3. 为什么要用 Pydantic 模型？

❓ 4. 我能用 FastAPI 开发正式项目吗？

学习建议：下一步可以学什么？

🔹 进阶技能推荐

📚 推荐学习资源

总结

评论 0

为你推荐

相关推荐

精选内容

❓ 1. 我访问 `/docs` 页面看不到接口怎么办？