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

技术碎碎念

2025-06-22 01:17

阅读 563

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

想象一下，你正在开发一个网站或者手机应用，这个应用需要访问数据（比如用户信息、商品列表、天气预报等）。这些数据通常不会直接存储在用户的设备上，而是放在服务器上。你的任务就是写代码来处理这些请求和数据交互——这就是后端的工作内容。

而 FastAPI 就是一个用 Python 编写的现代 Web 框架，它帮助你快速构建高效、易于维护的后端服务。简单来说：

FastAPI 是帮你搭建“后台服务器”的工具，让你可以专注于编写业务逻辑，而不是去折腾底层细节。

它适合用来做 RESTful API 接口开发，也就是前后端分离场景下非常常见的接口类型。它还有以下优点：

性能接近 Node.js 和 Go 的水平
自动生成交互式文档（Swagger UI / ReDoc）
支持异步编程（async/await）
基于 Python 类型注解，代码更清晰

如果你是 Python 新手但想快速上手后端开发，FastAPI 会是个不错的选择！

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

1. 安装 Python

请确保你的电脑上已经安装了 Python 3.8 及以上版本。你可以打开终端或命令行窗口，输入：

python --version

如果返回的是 Python 3.x.x，说明你已经安装好了 Python。

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

2. 创建虚拟环境（建议）

为了避免不同项目的依赖冲突，我们使用虚拟环境。在项目目录中执行：

python -m venv venv

然后激活虚拟环境：

Windows：
```
venv\Scripts\activate
```
macOS/Linux：
```
source venv/bin/activate
```

3. 安装 FastAPI 和 Uvicorn

我们使用 pip 来安装所需的包：

pip install fastapi uvicorn

fastapi 是核心库
uvicorn 是 FastAPI 推荐的 ASGI 服务器，用于运行我们的应用

4. 检查是否安装成功

创建一个名为 main.py 的文件，内容如下：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "你好，FastAPI！"}

然后在命令行中运行：

uvicorn main:app --reload

打开浏览器，访问：http://127.0.0.1:8000，你应该看到类似这样的输出：

{
  "message": "你好，FastAPI！"
}

太棒了！你现在有了一个运行中的 FastAPI 服务！

核心概念讲解：从零理解 FastAPI 的基本结构

数据库设计模型-2

1. 路由（Route）与请求方法（GET, POST 等）

Web 应用的本质就是响应客户端发送过来的 HTTP 请求。不同的请求路径和服务对应不同的功能。

在 FastAPI 中，我们通过装饰器的方式定义路由。常见的请求方式包括：

方法	描述
GET	获取资源
POST	提交数据，创建资源
PUT	更新资源
DELETE	删除资源

示例：定义一个 GET 接口 /hello

@app.get("/hello")
def say_hello():
    return {"message": "Hello World!"}

访问 http://127.0.0.1:8000/hello，你会得到一个 JSON 响应。

2. 路径参数（Path Parameters）

有时候我们需要根据不同的 ID 或名称获取特定资源。比如查询某个用户的信息，URL 可能是这样：

/users/123

这里 /users/123 中的 123 就是一个路径参数。

代码实现如下：

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

注意我们给参数加上了类型 int，FastAPI 会自动进行验证。

3. 查询参数（Query Parameters）

除了路径参数，我们也可以通过 URL 中的查询参数传递额外信息，例如分页：

/items?skip=0&limit=10

对应的函数可以这样写：

@app.get("/items")
def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

默认值分别是 0 和 10，如果不传则使用默认值。

4. 请求体（Request Body）与 Post 请求

当我们要创建或更新数据时，通常使用 POST 或 PUT 方法，并通过请求体（body）传递数据。

FastAPI 使用 Pydantic 模型来做数据校验和解析。先看一个例子：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False

@app.post("/items")
def create_item(item: Item):
    return {"received_data": item.dict()}

你可以访问 http://127.0.0.1:8000/docs 自动生成的文档界面，点击 “Try it out” 测试这个接口。

POST 数据格式应该是：

{
    "name": "笔记本",
    "price": 999.9,
    "is_offer": true
}

5. 返回值（Response）

你已经看到，默认 FastAPI 会返回 JSON 数据，但它也支持其他格式（比如 XML、HTML 等），只要你在响应中指定即可。

还可以自定义状态码：

from fastapi import FastAPI, status

@app.post("/items", status_code=status.HTTP_201_CREATED)
def create_item(item: Item):
    return {"received_data": item.dict()}

这段代码会在创建成功时返回 201 状态码。

实战项目：做一个简单的待办事项（Todo）管理系统

微服务架构示意图-1

现在我们来动手做一个完整的项目 —— 待办事项系统，包含以下功能：

查看所有待办事项（GET）
添加新任务（POST）
根据ID删除任务（DELETE）

第一步：设计数据模型

我们先定义一个 Todo 数据模型：

from pydantic import BaseModel
from typing import Optional

class TodoItem(BaseModel):
    title: str
    description: Optional[str] = None
    completed: bool = False

title 是必填项
description 和 completed 是可选字段

第二步：用一个内存变量模拟数据库

在没有连接真实数据库的情况下，我们用一个列表暂时代替：

todos = [
    {"id": 1, "title": "完成教程", "completed": False},
    {"id": 2, "title": "学习FastAPI", "completed": True}
]

第三步：添加查询所有待办事项的接口

@app.get("/todos")
def list_todos():
    return todos

访问：http://127.0.0.1:8000/todos 即可查看所有任务。

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

next_id = 3

@app.post("/todos")
def add_todo(todo: TodoItem):
    global next_id
    new_todo = {"id": next_id, **todo.dict()}
    todos.append(new_todo)
    next_id += 1
    return new_todo

测试方法：进入 Swagger 页面尝试提交数据：

{
    "title": "喝杯咖啡"
}

应该能返回新增的数据，并带有一个自增的 id。

第五步：添加删除任务的接口

@app.delete("/todos/{todo_id}")
def delete_todo(todo_id: int):
    for i, todo in enumerate(todos):
        if todo['id'] == todo_id:
            del todos[i]
            return {"status": "删除成功"}
    return {"status": "未找到对应任务"}

访问 http://127.0.0.1:8000/todos/1 并选择 DELETE 方法进行测试。

这样我们就完成了这个简单的待办事项系统！

常见问题解答：初学者容易遇到的问题汇总

Q1：为什么不能访问我的API？

常见原因有：

是否忘了启动服务？
是否用了错误的端口号（默认是8000）
是否加了 --reload 参数（仅用于开发模式）
是否写了 if __name__ == '__main__': 主程序入口（如果是用普通方式运行）

解决方法：

检查控制台是否有报错信息
使用 uvicorn main:app --reload 正确运行
访问正确的地址：http://127.0.0.1:8000/...

Q2：接口返回的字段顺序对吗？能不能控制？

JSON 本质上是无序结构，但在 Python 3.7+ 中字典默认是按插入顺序排序的。你可以放心，FastAPI 返回的 JSON 字段顺序一般和你定义的一致。

Q3：我的 POST 接口总是报错 `unprocessable entity`

这通常是因为请求的数据不符合定义的 Pydantic 模型要求。比如：

必须字段没传
字段类型不对（比如数字写成字符串）

建议：

使用 Swagger 页面测试接口
检查传入数据是否符合定义的模型

Q4：怎么设置自定义响应头或Cookie？

你可以使用 FastAPI 提供的 Response 对象：

from fastapi import Response

@app.get("/custom-header")
def custom_header(response: Response):
    response.headers["X-Custom-Header"] = "MyValue"
    return {"msg": "Custom header added"}

Q5：如何让 FastAPI 跑在线上公网访问？

本教程目前只介绍了本地运行的方法。如果你想要上线部署，可以使用 Nginx + Gunicorn + Uvicorn 组合，或将项目打包成 Docker 镜像部署到云服务器上。

这部分超出本文范围，后续可以学习相关部署课程。

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

恭喜你完成了第一个 FastAPI 应用！接下来你可以沿着这几个方向继续深入学习：

1. 数据库连接（推荐 SQLite + SQLAlchemy）

现在的 Todo 系统是纯内存的，关掉服务数据就没了。学习如何连接数据库能让数据持久化。

学习使用 SQLite（轻量级嵌入式数据库）
学习使用 SQLAlchemy ORM（对象关系映射库）

2. 异步编程（async/await）

FastAPI 原生支持异步，非常适合高并发场景。你可以尝试写一些异步接口：

@app.get("/async")
async def async_example():
    # 做一些异步操作
    return {"status": "async done"}

3. 用户认证与 Token 验证

实际项目中都需要登录权限系统。学习 JWT（JSON Web Token）机制，为你的接口加上身份验证。

4. 接口测试与自动化测试（Pytest）

学会写单元测试，保障你的接口稳定性。

5. 进阶框架特性（如中间件、后台任务等）

了解中间件、定时任务、事件监听等功能，提升你的开发效率。

总结回顾：你学到了什么？

在这篇教程中，你已经掌握了：

✅ FastAPI 是什么以及它能做什么
✅ 如何搭建 FastAPI 开发环境
✅ 路由、路径参数、查询参数、请求体的基本使用
✅ 构建一个完整的 Todo 待办系统
✅ 解决常见错误和疑问
✅ 接下来的学习方向建议

后端开发并不神秘，只要你愿意动手实践，就能一步步掌握。FastAPI 是个非常友好的起点，希望你继续探索下去，写出更强大的后端服务！

如果你喜欢这篇教程，欢迎持续关注更多进阶内容！🚀

标签:Go后端爬虫

最热最新

暂无评论

为你推荐

暂无相关推荐

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

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

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

1. 安装 Python

2. 创建虚拟环境（建议）

3. 安装 FastAPI 和 Uvicorn

4. 检查是否安装成功

核心概念讲解：从零理解 FastAPI 的基本结构

1. 路由（Route）与请求方法（GET, POST 等）

2. 路径参数（Path Parameters）

3. 查询参数（Query Parameters）

4. 请求体（Request Body）与 Post 请求

5. 返回值（Response）

实战项目：做一个简单的待办事项（Todo）管理系统

第一步：设计数据模型

第二步：用一个内存变量模拟数据库

第三步：添加查询所有待办事项的接口

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

第五步：添加删除任务的接口

常见问题解答：初学者容易遇到的问题汇总

Q1：为什么不能访问我的API？

Q2：接口返回的字段顺序对吗？能不能控制？

Q3：我的 POST 接口总是报错 `unprocessable entity`

Q4：怎么设置自定义响应头或Cookie？

Q5：如何让 FastAPI 跑在线上公网访问？

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

1. 数据库连接（推荐 SQLite + SQLAlchemy）

2. 异步编程（async/await）

3. 用户认证与 Token 验证

4. 接口测试与自动化测试（Pytest）

5. 进阶框架特性（如中间件、后台任务等）

总结回顾：你学到了什么？

评论 0

为你推荐

精选内容

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

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

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

1. 安装 Python

2. 创建虚拟环境（建议）

3. 安装 FastAPI 和 Uvicorn

4. 检查是否安装成功

核心概念讲解：从零理解 FastAPI 的基本结构

1. 路由（Route）与请求方法（GET, POST 等）

2. 路径参数（Path Parameters）

3. 查询参数（Query Parameters）

4. 请求体（Request Body）与 Post 请求

5. 返回值（Response）

实战项目：做一个简单的待办事项（Todo）管理系统

第一步：设计数据模型

第二步：用一个内存变量模拟数据库

第三步：添加查询所有待办事项的接口

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

第五步：添加删除任务的接口

常见问题解答：初学者容易遇到的问题汇总

Q1：为什么不能访问我的API？

Q2：接口返回的字段顺序对吗？能不能控制？

Q3：我的 POST 接口总是报错 unprocessable entity

Q4：怎么设置自定义响应头或Cookie？

Q5：如何让 FastAPI 跑在线上公网访问？

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

1. 数据库连接（推荐 SQLite + SQLAlchemy）

2. 异步编程（async/await）

3. 用户认证与 Token 验证

4. 接口测试与自动化测试（Pytest）

5. 进阶框架特性（如中间件、后台任务等）

总结回顾：你学到了什么？

评论 0

为你推荐

相关推荐

精选内容

Q3：我的 POST 接口总是报错 `unprocessable entity`