FastAPI入门：Python后端开发新手指南
开篇：什么是FastAPI？
FastAPI 是一个现代、快速（高性能）的 Python Web 框架，用于构建 API。它非常适合用来做后端开发，特别是那些需要和前端（比如网页、APP）交互的服务。简单来说，如果你想要开发一个能让别人通过网络访问的数据服务（例如天气查询、登录注册功能），FastAPI 就是一个非常理想的选择。
为什么选择 FastAPI？
- 它使用最新的 Python 语法，写起来非常简洁。
- 它自带文档生成工具，可以自动为你写的代码生成网页版的接口说明。
- 它性能优秀，比许多其他框架更快。
在本教程中，我们将从零开始学习如何使用 FastAPI 构建自己的第一个 API 接口。
环境准备
在我们开始编写任何代码之前，首先要准备好我们的开发环境。不用担心，这个过程其实并不复杂，跟着下面的步骤一步步来就可以了。
安装 Python
首先，你需要安装 Python。请到 https://www.python.org/downloads/ 下载并安装适合你操作系统的 Python 版本（推荐 Python 3.7 或更高版本）。
安装完成后，打开终端或命令行工具，输入以下命令检查是否安装成功：
python --version
如果看到类似 Python 3.x.x 的输出，说明已经安装好了。
创建虚拟环境（可选但推荐）
为了保持项目的干净和避免包冲突，我们可以创建一个虚拟环境。运行以下命令来创建虚拟环境：
python -m venv fastapi_env
然后激活虚拟环境：
- 在 Windows 上：
fastapi_env\Scripts\activate - 在 macOS 和 Linux 上：
source fastapi_env/bin/activate
激活后，你的终端提示符前应该会出现 (fastapi_env) 字样。
安装 FastAPI 和 Uvicorn
接下来，我们需要安装 FastAPI 以及一个叫做 Uvicorn 的服务器工具，用于运行我们的项目。
执行以下命令：
pip install fastapi uvicorn
安装完成后，你可以输入：
uvicorn --version
确认是否安装成功。
测试安装
为了确保一切正常，我们来写一个简单的测试程序。
新建一个文件，比如命名为 main.py，并在其中输入以下内容：
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, World!"}
保存后，在终端运行：
uvicorn main:app --reload
打开浏览器，访问 http://localhost:8000，你应该会看到：
{"message": "Hello, World!"}
恭喜！你已经成功搭建了 FastAPI 的开发环境，并运行了第一个应用！
核心概念讲解
现在我们已经搭建好了环境，并且运行了一个最简单的示例。接下来，我们来逐步介绍 FastAPI 的一些核心概念，帮助你理解它是怎么工作的。
路由（Router）
“路由”是指你告诉服务器什么时候该执行什么代码。比如，当用户访问 / 这个路径时，我们就返回 “Hello, World!”。
在之前的例子中，我们用了 @app.get("/") 来定义一个 GET 请求的路由。
GET 是一种常见的请求方式，表示用户想获取数据。还有 POST、PUT、DELETE 等，分别对应不同的操作类型。
示例：添加更多路由
我们可以在 main.py 中继续添加几个路由：
@app.get("/hello")
def say_hello():
return {"message": "你好！"}
@app.get("/about")
def about_page():
return {"info": "这是一个关于页面"}
运行后访问：
你会看到对应的响应内容。
请求方式（HTTP Methods）
常见的 HTTP 方法包括：
| 方法 | 含义 |
|---|---|
| GET | 获取信息 |
| POST | 提交数据 |
| PUT | 更新数据 |
| DELETE | 删除数据 |
这些方法可以帮助我们设计清晰的功能接口。
示例：使用 POST 方法提交数据
修改你的 main.py 文件，加入如下内容：
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class User(BaseModel):
name: str
age: int
@app.post("/user/")
def create_user(user: User):
return {
"message": f"用户 {user.name} 已创建，年龄为 {user.age}"
}
重启服务后访问 http://localhost:8000/docs —— 这是 FastAPI 自动生成的接口文档界面。在这个界面中你可以尝试发送一个 POST 请求。
点击 “Try it out”，在输入框中填写 JSON 数据，如：
{
"name": "张三",
"age": 25
}
点击 “Execute”，你会看到返回的结果。
这就是用 POST 方法提交数据的基本流程。
参数传递（Query Parameters 和 Path Parameters）
参数是我们与客户端交换数据的重要方式之一。
- Query Parameter：就是 URL 后面问号后面的部分，例如：
?name=John - Path Parameter：是 URL 路径的一部分，例如：
/item/123
示例：使用 Query Parameters
@app.get("/search")
def search_item(q: str):
return {"query": q}
访问：http://localhost:8000/search?q=test
你会看到结果 { "query": "test" }。
示例：使用 Path Parameters
@app.get("/items/{item_id}")
def read_item(item_id: int):
return {"item_id": item_id}
访问：http://localhost:8000/items/42
你会得到：{ "item_id": 42 }
FastAPI 会自动将路径中的字符串转换为指定类型（这里是 int）。
响应格式（JSON）
大多数 API 都使用 JSON 格式来返回数据。FastAPI 默认就支持 JSON 输出，你只需要返回一个字典或者 Pydantic 模型对象即可。
Pydantic 是 FastAPI 内部用来处理数据结构的库。上面我们在 POST 请求的例子中就用到了它。
到这里为止，你已经了解了 FastAPI 的几个关键概念：
- 如何定义路由
- 不同的请求方法（GET、POST 等）
- 参数是如何传递的
- 返回 JSON 数据的方式
接下来，我们把这些知识综合起来，做一个小项目。
实战项目：构建一个简易的任务管理器
现在我们要做一个小型项目：任务管理器。它可以让我们添加任务、列出所有任务、删除某个任务。
第一步：定义数据模型
我们将使用一个简单的列表来保存任务。为了让每个任务有唯一标识，每个任务都有一个 ID。
新建一个文件 tasks.py，添加以下内容：
# 用来存储任务数据
tasks = [
{"id": 1, "title": "学习 FastAPI", "done": False},
{"id": 2, "title": "完成练习题", "done": True}
]
第二步：编写 GET 路由，列出所有任务
回到 main.py，导入任务列表并增加一个 GET 接口：
from fastapi import FastAPI
from tasks import tasks
app = FastAPI()
@app.get("/tasks")
def get_tasks():
return tasks
访问 http://localhost:8000/tasks，可以看到所有任务以 JSON 形式显示。
第三步：根据 ID 获取单个任务
接下来我们实现按任务 ID 查看详情的功能：
@app.get("/tasks/{task_id}")
def get_task(task_id: int):
for task in tasks:
if task["id"] == task_id:
return task
return {"error": "未找到该任务"}
访问 http://localhost:8000/tasks/1，可以看到 ID 为 1 的任务。
第四步：添加新任务（POST）
我们再来定义一个任务模型，并创建一个添加新任务的接口：
from pydantic import BaseModel
class TaskCreate(BaseModel):
title: str
done: bool = False
@app.post("/tasks")
def add_task(task: TaskCreate):
new_id = max(t["id"] for t in tasks) + 1 if tasks else 1
new_task = {**task.dict(), "id": new_id}
tasks.append(new_task)
return new_task
使用 Swagger 文档界面测试一下吧！
第五步：删除任务（DELETE）
接着我们实现删除任务的功能：
@app.delete("/tasks/{task_id}")
def delete_task(task_id: int):
global tasks
tasks = [t for t in tasks if t["id"] != task_id]
return {"message": "任务已删除"}
试试删除某个任务看看效果。
总结一下
我们刚刚完成了一个完整的 CRUD（创建、读取、更新、删除）小项目：
- GET /tasks — 列出所有任务
- GET /tasks/{id} — 查看某个任务
- POST /tasks — 添加新任务
- DELETE /tasks/{id} — 删除任务
虽然只是一个简单的内存数据库，但它已经具备了实际项目的核心逻辑。
下一步，我们来看看一些新手常遇到的问题和解决办法。
常见问题解答
Q1: FastAPI 和 Flask 有什么区别？
FastAPI 是一个专注于高性能 API 构建的现代框架，而 Flask 是一个更通用、灵活的轻量级 Web 框架。FastAPI 支持异步编程，并自动生成文档，更适合做 RESTful API；Flask 更适合小型网站或简单服务。
Q2: 为什么我的路径不生效？
可能是拼写错误，或者是没有加上装饰器 @app.get()，也有可能是你运行的不是最新版本。建议重启服务重新加载。
Q3: FastAPI 报错说无法找到模块怎么办？
有时候你可能会遇到类似 ModuleNotFoundError 的错误。这时候请确认你的 Python 包是否正确安装。例如如果你用到 Pydantic，请确保你安装过它：
pip install pydantic
Q4: 我应该怎么调试 FastAPI 项目？
你可以使用 Python 自带的 print() 函数临时调试，也可以使用像 Postman 或 FastAPI 自带的文档系统进行测试。
学习建议：下一步学什么？
当你掌握了基本的 FastAPI 使用技巧之后，建议你进一步学习以下内容：
🧩 使用数据库（如 SQLAlchemy）
目前我们的任务数据只是保存在内存中。真正的项目应该使用数据库来持久化数据。你可以学习如何连接 SQLite、PostgreSQL 或 MySQL。
⚙️ 认证和权限控制（Authentication & Authorization）
学会如何让用户登录、限制某些接口只能特定用户访问。
📦 异步编程（async/await）
掌握异步编程可以大幅提升后端性能，尤其是对于高并发服务。
🛠️ 单元测试（Unit Testing）
学会用 pytest 编写自动化测试，确保你的代码稳定可靠。
🔐 接口安全（JWT、CORS）
学习跨域设置、加密传输等安全性相关知识。
到这里，恭喜你完成了《FastAPI入门：Python后端开发新手指南》的学习！希望你能够动手实践，不断尝试新的想法，享受编程的乐趣！
评论 0