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

赵静_技术

2025-06-14 12:41

阅读 414

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

你有没有想过，当你在使用手机或浏览器访问一个网站时，比如登录微信、查看天气预报或者下单购物，这些操作背后其实是很多“服务器”在帮你处理数据。而这些服务器的程序，就是我们常说的后端（Backend）。

FastAPI 就是 Python 中非常流行的一个工具，用来帮助开发者快速搭建后端服务。它的特点是：

✅ 速度快：性能接近 Go 和 Node.js
✅ 易于上手：不需要很深的编程经验也能快速上手
✅ 自带接口文档：你写完接口后，FastAPI 会自动生成网页版的 API 说明文档，方便测试和沟通

简单来说，你可以用 FastAPI 来构建能被其他网站或 App 使用的“接口”，比如用户登录接口、查询天气的接口等。

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

要开始学习 FastAPI，你需要准备好一个开发环境。不用担心，过程很轻松！

步骤一：安装 Python

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

打开命令行（Windows 按下 Win+R 输入 cmd 回车；Mac 打开终端），输入：

python --version

如果你看到类似这样的一行（版本号可能略有不同）：

Python 3.10.6

那说明你已经装好了 Python。

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

步骤二：创建项目目录并进入

先在电脑上找个地方新建一个文件夹，比如叫做 fastapi_tutorial。然后在命令行中切换到这个目录下：

cd fastapi_tutorial

步骤三：安装 FastAPI 和 Uvicorn

FastAPI 需要配合一个叫 uvicorn 的服务器来运行。安装命令如下：

pip install fastapi uvicorn

等待几分钟，安装完成后就可以开始编写代码啦！

核心概念：几个关键点让你看懂 FastAPI 的结构

即使你是零基础，也别担心。接下来我会用最简单的方式带你认识 FastAPI 的几个核心概念。

1. “路由”就像地图上的门牌号

想象一下你要去朋友家玩，你知道地址是“某条街第12号”。那么这扇门就像是你的“接口”。

在 FastAPI 中，每个功能都对应一个“路由”，也就是 URL 地址。

举个例子：

from fastapi import FastAPI

app = FastAPI()

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

这段代码做了什么事情呢？

@app.get("/") 表示当有人访问根路径（也就是 /）时，调用下面的函数。
函数名是 read_root()，返回一个字典内容。
访问方式是 HTTP 协议中的 GET 方法。

保存上面代码为 main.py，然后运行启动命令：

uvicorn main:app --reload

你现在可以用浏览器打开：

http://localhost:8000

你会看到：

{
  "message": "欢迎来到我的第一个接口！"
}

2. 基本的数据交互：请求与响应

假设我们要做一个“打招呼”的接口：

示例：

@app.get("/hello/{name}")
def say_hello(name: str):
    return {"message": f"你好，{name}！"}

访问地址例如：

http://localhost:8000/hello/小明

返回结果：

{
  "message": "你好，小明！"
}

这是什么意思呢？

{name} 是一个路径参数，表示这部分可以替换。
在函数中声明 name: str，表示这个参数是字符串类型。

FastAPI 支持自动验证数据类型哦！

3. 请求体（POST 接口）怎么弄？

GET 是获取数据，POST 是提交数据。我们来看一个注册用户的例子：

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

class User(BaseModel):
    username: str
    password: str

@app.post("/register")
def register_user(user: User):
    return {
        "status": "success",
        "data": user
    }

现在，在浏览器或者用 Postman 工具发送 POST 请求到 /register，带上 JSON 数据：

{
  "username": "testuser",
  "password": "123456"
}

你会收到：

{
  "status": "success",
  "data": {
    "username": "testuser",
    "password": "123456"
  }
}

⚠️ 注意：这里的密码没有加密，只是为了演示基本功能。实际项目中一定要注意安全问题！

实战项目：动手做一个任务清单 API（To-Do List）

现在我们来做一个小项目：实现一个简单的任务管理接口。它支持添加任务和列出所有任务。

第一步：设计思路

我们要实现两个接口：

添加任务：POST 到 /tasks，带任务标题
获取任务列表：GET 到 /tasks

我们需要一个变量来临时保存任务数据。

第二步：完整代码如下

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

app = FastAPI()

# 定义任务的数据格式
class TaskCreate(BaseModel):
    title: str

class Task(TaskCreate):
    id: int

# 模拟数据库，存储任务数据
fake_db = []
next_id = 1

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

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

提示：pydantic 是 FastAPI 默认用于数据校验的库，我们这里用它来规范输入输出数据格式。

保存为 todo_app.py，运行：

uvicorn todo_app:app --reload

第三步：测试你的 API

打开浏览器访问：

http://localhost:8000/docs

你会看到 FastAPI 自动生成的交互式文档页面，看起来像这样：

Try it out ➡ Execute

尝试使用 POST 方法添加任务：

{
  "title": "买菜"
}

再使用 GET 查看所有任务：

[
  {
    "id": 1,
    "title": "买菜"
  }
]

恭喜你！你已经完成了一个完整的后端功能模块！

常见问题解答：新手遇到这些问题怎么办？

❓Q：我运行的时候报错：“Uvicorn is not found”

❌ 错误示例：

'uvicorn' 不是内部或外部命令，也不是可运行的程序...

✅ 解决方法：确保你已经正确安装 FastAPI 和 Uvicorn：

pip install fastapi uvicorn

还可以检查是否使用了正确的 Python 环境（有些系统有多个 Python 版本共存）。

❓Q：为什么访问 http://localhost:8000 出现 404 Not Found？

❌ 可能原因：你写的路径拼错了，比如写了 /helloo 而不是 /hello。

✅ 检查建议：

确保函数上的装饰器路径正确
重启服务看看改动生效了吗？
查看控制台是否有错误提示

❓Q：为什么我的 POST 接口不能传参？

❌ 一般因为：你没有使用 Pydantic 模型来定义参数类型。

✅ 正确做法：使用 BaseModel 类来封装输入参数，并在接口函数里接收该类对象。

❓Q：我可以不写 docs 文档吗？会影响别人调用接口吗？

FastAPI 自动生成的 /docs 页面只是为了方便调试和测试，对正式生产部署影响不大。但它是开发过程中非常强大的助手。

学习建议：下一步还能学哪些知识？

你现在已经掌握了 FastAPI 的基础，接下来可以朝着以下几个方向继续深入：

🔹 1. 进阶功能：中间件 & 异常处理

掌握统一错误返回格式
实现日志记录
拦截非法请求

🔹 2. 数据库连接（如 SQLite / MySQL / PostgreSQL）

学习使用 SQLAlchemy 或 Tortoise ORM
把我们之前用的“假数据库”换成真实数据库

🔹 3. 身份验证与权限控制

用户登录系统
JWT Token 实现身份认证
分角色管理权限

🔹 4. 异步编程（async/await）

FastAPI 支持异步编程模式，有助于提升并发能力。

🔹 5. 项目实战进阶：前后端分离架构

搭建前后端分离项目结构
使用 FastAPI 对接 Vue / React 前端
整合 Nginx、Docker 部署上线

📘 推荐学习资料

学习资源名称	内容特点
FastAPI 官方中文文档	最权威、最全面
《Python Web 全栈开发实战》	包含大量实践案例
B站课程《零基础掌握 FastAPI 后端开发》	新手友好
GitHub 开源项目搜索关键词 `fastapi example`	优秀开源参考

结语：你已经迈出了成为后端工程师的第一步！

在这篇教程中，你学会了：

什么是 FastAPI，它适合做什么？
如何配置开发环境？
怎么写最简单的 API？
如何构建一个小型任务管理接口？
新手常见问题如何解决？
下一步应该学什么？

虽然这只是刚刚开始，但你已经走在了一条充满可能性的路上。继续加油！

🎯 小练习：试着写一个计算两个数相加的接口（如输入 a 和 b，返回 sum）。你可以尝试用 POST 请求实现。完成后可以在评论区分享你的代码，我会为你点评哦！

Happy coding 🧑‍💻✨

标签:产品Java实战经验求职

最热最新

暂无评论

为你推荐

暂无相关推荐