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

开篇：认识FastAPI——你也能做网站背后的大脑！

在互联网的世界里，网页和APP之所以能“思考”、“记住”用户信息、甚至帮你下单购物，是因为它们背后有服务器程序在默默工作。这些程序负责处理用户的请求、操作数据，并返回结果。

而我们今天要学的 FastAPI 就是一个专门用来写这类服务器程序（专业术语叫后端 API）的 Python 工具。它简单易学、速度快，特别适合刚入门的新手。

用一个生活中的比喻来说：
想象你在餐厅点菜，服务员（相当于前端界面）把你点的菜单传给厨房（后端），厨师按单做饭（处理数据），再通过服务员给你上菜（返回结果）。这个“厨房”的部分，就是我们要学的内容。

✅ 学习目标：通过本教程，你可以用 Python 写出一个自己的“迷你服务器”，让它能接受请求并返回信息。

---

环境准备：安装开发环境——让电脑准备好开始编程

在正式写代码前，我们需要先准备好开发环境。

所需工具清单：

• Python 3.8+（建议使用最新稳定版本）
• pip（Python自带的包管理器）
• 任意文本编辑器（推荐 VS Code）

步骤1：确认你的电脑已经安装了 Python

打开终端或命令行工具（Windows 是 cmd 或 PowerShell，Mac 是 Terminal），输入：

python --version

如果看到类似输出说明安装成功：

Python 3.9.7

如果没有安装，可以去官网下载安装包：https://www.python.org/downloads/

步骤2：安装 FastAPI 和启动器 Uvicorn

执行以下命令安装所需模块：

pip install fastapi uvicorn

🧪 fastapi 是我们的核心框架；uvicorn 是 FastAPI 推荐的运行服务器工具。

步骤3：创建第一个项目文件夹

我们可以为项目新建一个简单的目录结构：

my_first_fastapi/
│
└── main.py

你可以手动新建文件夹，并在里面创建一个名为 main.py 的空白文件。

现在，万事俱备！我们可以开始编写第一个“打招呼”的服务器啦！

---

核心概念讲解：FastAPI是怎么运作的？

FastAPI 做的事其实很简单：当有人发来请求时，根据路径（URL）执行对应的函数，然后返回响应内容。

我们先来看几个关键词：

概念	解释
API	应用程序接口，是前后端沟通的标准接口
请求方法	如 GET、POST，表示客户端想干什么（查数据 or 提交数据）
路由	类似地图导航，告诉服务器“/users”应该用哪个函数处理
异步支持	提升并发性能，后面会讲到

下面我们用一个例子一步步解释这些概念。

示例一：Hello World 服务端

# main.py

from fastapi import FastAPI

app = FastAPI()

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

运行步骤：

在终端中进入 my_first_fastapi 文件夹后运行：

uvicorn main:app --reload

解释：

• main 是文件名（不含 .py）
• app 是我们在代码中定义的变量名
• --reload 表示代码改动自动重启（开发模式用）

默认情况下，服务器会运行在：http://127.0.0.1:8000

浏览器打开这个地址，你会看到：

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

太棒了，你的第一个服务器上线啦！

示例二：带路径参数的接口

现在我们添加一个可以接收名字的接口：

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

访问网址：http://127.0.0.1:8000/hello/小明

会得到：

{"greeting": "你好, 小明!"}

是不是很酷？我们可以像这样设计很多不同功能的 API！

---

实战项目：做一个迷你待办事项管理系统

我们来实战一个小项目 —— 待办事项列表（Todo List），它可以完成：

1. 查看所有待办事项
2. 添加新的待办事项

第一步：定义模型

我们先定义数据结构，比如一个任务包含什么内容：

from pydantic import BaseModel

class TodoItem(BaseModel):
    title: str
    description: str = None  # 可选描述

⚠️ BaseModel 来自 pydantic，它帮助我们规范接口的数据格式。

第二步：模拟数据库存储

为了简化演示，我们先不用真正的数据库，用一个内存列表代替：

todos = []

第三步：实现查看全部任务的接口

@app.get("/todos/", response_model=list[TodoItem])
def get_todos():
    return todos

第四步：添加新任务的接口

@app.post("/todos/")
def add_todo(todo: TodoItem):
    todos.append(todo)
    return {"status": "任务已添加", "todo": todo}

第五步：运行并测试接口

再次运行服务：

uvicorn main:app --reload

访问文档页面：http://127.0.0.1:8000/docs

你将看到一个交互式的 API 测试界面（Swagger UI）👇：

点击 /todos/ → POST → Try it out → 输入 JSON 数据：

{
  "title": "买鸡蛋",
  "description": "晚饭要用"
}

点击 Execute，提交后就能看到新增的任务了！

---

常见问题解答（FAQ）

Q1：为什么启动服务时提示找不到模块？

可能是没正确激活虚拟环境或未安装依赖。

✅ 解决办法：重新安装缺失的库，如：

pip install fastapi uvicorn

或者尝试创建一个新的虚拟环境：

python -m venv venv
source venv/bin/activate  # Windows下用 venv\Scripts\activate
pip install fastapi uvicorn

---

Q2：修改代码后需要重新启动吗？

如果你加了 --reload 参数就不需要手动重启，保存文件后服务器会自动重载。

---

Q3：FastAPI 支持中文吗？

完全支持！只要设置好字符编码即可，默认使用 UTF-8 编码。

---

Q4：我写的接口能不能用在微信小程序或 APP 上？

当然可以！只要你的接口返回的是标准 JSON 格式，任何平台都可以调用。

---

Q5：什么时候需要用 POST？GET 和 POST 有什么区别？

方法	使用场景	安全性	是否缓存
GET	获取数据	✅ 是	✅ 可缓存
POST	提交数据	❌ 否	❌ 不缓存

举个例子：

• 显示用户列表：用 GET
• 用户注册：用 POST

---

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

恭喜你完成 FastAPI 的入门课程！接下来可以继续深入学习以下内容：

学习路径建议 🚀

学习方向	学习内容	推荐资源
数据库集成	学习连接 MySQL、PostgreSQL、SQLite 等	官方教程《Databases》
认证与权限	JWT、OAuth2 等登录验证机制	FastAPI Security 文档
部署上线	了解如何把项目部署到云服务器	使用 Gunicorn、Nginx
自动化文档	Swagger / Redoc	FastAPI 默认自带
异步编程	利用 async def 优化性能	asyncio 与 await 相关知识

💡 学完 FastAPI 后，可以尝试结合 Vue.js / React / 微信小程序等前端技术一起搭建完整的 Web 应用。

---

结语：你也可以成为后端工程师！

通过这篇教程，你已经学会了：

• 什么是 API 以及它怎么运行
• 如何搭建本地开发环境
• FastAPI 的基础路由和模型用法
• 构建一个真实的 Todo 列表系统
• 常见问题的排查技巧

你现在已经是半个后端程序员啦！

如果你觉得这套教程对你有帮助，不妨动手练习一下，或者分享给正在学编程的朋友。

📌 记住一句话：实践才是最好的老师！

---

🎯 下一步行动建议：

1. 尝试自己写一个“天气查询”接口（调用免费天气 API）
2. 把今天写的 Todo 项目发布到 GitHub
3. 加入社区群组，和其他开发者交流心得（例如知乎、掘金、Stack Overflow）

加油，祝你越学越快乐！💻💡