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

·赵建国

2025-06-25 12:26

阅读 514

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

你可能听说过一些编程术语，比如“后端开发”、“RESTful API”或者“Web服务”，听起来很高大上。不过没关系，在这篇教程里，我会用最简单的语言带你认识一个非常现代又高效的工具 —— FastAPI。

什么是FastAPI？

简单来说，FastAPI 是一个用于构建 Web API 的 Python 框架，它的特点是：

速度快：性能接近 Go 和 Node.js 这类编译型语言的框架
自动化文档生成：写好接口后会自动帮你生成交互式文档（就像网页一样可以直接测试）
代码简洁：使用 Python 新特性（比如类型注解）让代码更清晰易懂
适合初学者：虽然功能强大，但学习门槛很低

它能用来做什么？

想象你正在做一款手机App或者网站，需要访问服务器里的数据，比如用户登录、展示商品信息、保存订单等等。这些后台的数据处理和服务，就是 FastAPI 的用武之地。你可以用它快速搭建出一套对外提供服务的接口，别人（包括你自己写的前端代码）可以通过网络请求调用这些接口来完成操作。

举个例子：

用户点击“注册账号”，你的App会把用户填写的手机号和密码通过网络发送给 FastAPI 写的接口
接口接收到数据后，验证是否合法，再存入数据库或返回错误信息
前端根据返回结果决定是跳转到主页还是提示错误

所以，如果你打算学习 Python 后端开发、想做一个项目的服务端部分，或者想搞清楚 Web 开发的整体流程，从 FastAPI 开始是最合适不过的选择！

接下来，我们先从环境准备开始，一步步教你如何在电脑上搭建起自己的第一个 FastAPI 项目。

环境准备：搭建你的开发环境

学习任何一门技术，第一步都是准备好开发环境。别担心，这一步其实并不复杂。我们只需要安装 Python 和 FastAPI 相关的依赖即可。

第一步：安装 Python

FastAPI 是一个 Python 框架，所以你需要先确保你的电脑已经安装了 Python。

如何检查是否安装了 Python？

打开命令行工具（Windows 是 cmd 或 PowerShell，Mac/Linux 是 Terminal），输入以下命令：

python --version

如果你看到了类似这样的输出：

Python 3.9.13

那恭喜你，Python 已经装好了！如果没有看到版本号或者报错，说明你还没安装 Python，可以去官网下载安装包并安装：

👉 Python 官网下载地址

⚠️ 小贴士：安装时记得勾选 "Add to PATH"，这样可以在任意地方运行 python 命令

第二步：安装虚拟环境管理工具 pipenv（可选）

为了更好地管理我们的项目，建议使用虚拟环境。你可以理解为：给每个项目一个“独立的小空间”，互不干扰。

安装 pipenv：

pip install pipenv

安装完成后创建虚拟环境：

pipenv shell

📝 实际效果：你会进入一个新的命令行环境，前面可能会显示 (your_project_name) 字样

第三步：安装 FastAPI 和 Uvicorn

FastAPI 本身只是一个库，我们需要再安装一个叫做 Uvicorn 的工具，它负责启动服务器并运行我们的应用。

执行以下命令安装 FastAPI 和 Uvicorn：

pip install fastapi uvicorn

✅ 安装成功后，你就拥有了构建 Web API 所需的基本工具

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

我们可以写一段最简单的代码来测试一下环境是否正常。

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

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

然后在命令行中运行这个文件：

python main.py

你应该会看到类似下面的输出：

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

现在打开浏览器，访问：http://localhost:8000，你会看到：

{
  "message": "Hello, FastAPI!"
}

🎉 太棒了！你的第一个 FastAPI 应用跑起来了！

第五步：自动生成文档功能

FastAPI 的一大特色是它可以自动生成接口文档。

访问下面两个地址看看神奇的功能吧：

Swagger UI 文档界面：http://localhost:8000/docs
ReDoc 文档界面：http://localhost:8000/redoc

这两个页面会自动列出你写的接口，并且可以在线测试接口！

至此，我们的开发环境就已经准备完毕啦！现在是时候了解 FastAPI 中的核心概念了，让我们继续前进！

核心概念讲解：让你真正看懂 FastAPI 的工作机制

要写出能用的 FastAPI 程序，你需要理解几个关键概念。别担心，我会用最通俗的语言加上实际代码来解释每一个概念。

1. 路由（Route）是什么？

路由其实就是“请求路径”。你可以把它理解成快递员送包裹的路线 —— 比如你想寄一个包裹到 /index.html 地址，快递员就知道应该送到哪个接口函数来处理。

在 FastAPI 中，我们使用装饰器来定义路由。比如：

@app.get("/hello")
def say_hello():
    return {"msg": "你好！"}

这段代码表示当有人访问 /hello 这个路径时，就执行 say_hello() 函数。

常见的 HTTP 方法有：

方法	描述	使用场景示例
GET	获取数据	查看文章内容
POST	提交数据	注册、登录
PUT	更新数据	修改用户资料
DELETE	删除数据	删除某篇文章

2. 请求方式（Method）有哪些？

前面我们用了 .get() 来监听 GET 请求，FastAPI 也支持其他请求方法：

@app.post("/login")        # 处理 POST 请求
@app.put("/update")        # 处理 PUT 请求
@app.delete("/delete_user")# 处理 DELETE 请求

你完全可以根据业务需求选择合适的请求方式，它们在代码结构上几乎是一样的。

3. 数据传参的方式

有时候我们要向接口传递参数，比如用户 ID、用户名、搜索关键词等等。FastAPI 支持几种常见的传参方式：

（1）路径参数（Path Parameters）

像 /user/123 中的 123 就是一个路径参数：

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

注意这里的 user_id: int 是类型声明。FastAPI 会自动校验传入的值是否符合类型要求。

（2）查询参数（Query Parameters）

查询参数就是在 URL 中带的参数，例如：/search?keyword=abc

@app.get("/search")
def search(keyword: str, limit: int = 10):
    return {"result": f"搜索 {keyword}，最多返回 {limit} 条"}

这里有两个参数：

keyword 是必填项
limit 是可选项，默认值为 10

（3）请求体（Request Body）

对于 POST 请求，我们通常使用请求体传参。比如用户注册时提交表单数据：

from pydantic import BaseModel

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

@app.post("/register")
def register(user: UserCreate):
    return {"msg": f"欢迎{user.username}注册！"}

这里定义了一个模型 UserCreate，它规定了接口接收的数据结构。如果传进来的 JSON 不符合规范，FastAPI 会自动报错。

4. 自动文档生成是怎么回事？

还记得我们之前访问的 /docs 吗？那是 FastAPI 自动生成的接口文档页面。

它是基于 OpenAPI 规范自动生成的，也就是说：

只要你按 FastAPI 的规范写好接口函数
FastAPI 就会知道这个接口的作用、接受什么参数、返回什么数据
然后就能自动生成漂亮的文档界面，还能直接试用接口！

这种机制叫做 类型驱动开发（Type-driven Development）

5. 异常处理与返回格式统一

FastAPI 默认会将你的返回值转换成 JSON 格式。如果你想抛出异常，也可以使用：

from fastapi import HTTPException

@app.get("/error")
def error():
    raise HTTPException(status_code=404, detail="找不到资源")

当你访问 /error 时，就会返回状态码 404 的标准错误信息。

小结：记住这几个核心概念

概念	作用
路由（@app.get）	决定哪个函数响应哪个URL路径
请求方法（GET/POST）	控制请求动作，对应不同的业务逻辑
参数传递（路径/查询/Body）	接收外部传来的数据
模型定义（BaseModel）	规定数据结构，提升代码可读性和安全性
错误处理（HTTPException）	提供标准错误响应
自动文档（SwaggerUI）	可视化查看和测试接口

以上这些内容构成了 FastAPI 的基础骨架。接下来我们就要动手实践，把这些知识点用起来，做出一个真正的项目！

实战项目：一步一步搭建你的第一个 FastAPI 应用

现在，我们将一起做一个小项目，来巩固前面学到的知识。项目目标：创建一个简易的图书管理系统 API。

我们将实现以下几个基本功能：

获取所有图书列表
添加一本新书
根据书名模糊搜索
删除一本书
返回标准格式的响应

第一步：规划项目结构

我们会建立一个名为 book_api 的项目目录，其大致结构如下：

book_api/
│
├── main.py           # 主程序入口
└── models.py         # 数据模型定义

你可以手动创建这些文件，也可以用你喜欢的编辑器创建，比如 VSCode、PyCharm、Sublime 等。

第二步：定义图书模型

打开 models.py 文件，写入以下内容：

from pydantic import BaseModel
from typing import Optional

class BookCreate(BaseModel):
    title: str
    author: str
    category: str
    published_year: int

class Book(BookCreate):
    id: int

这里我们定义了两个模型：

BookCreate：用户添加新书时使用的数据格式
Book：完整书籍信息（包括唯一标识 id）

💡 注意：Optional 表示该字段可为空，但我们暂时不需要用到它。

第三步：编写主程序逻辑

接下来打开 main.py 文件，开始编写主要逻辑。

初始化 FastAPI 实例 & 导入模型

from fastapi import FastAPI, HTTPException
from models import BookCreate, Book

app = FastAPI()

我们现在先模拟一个临时数据库：

# 模拟数据库
books_db = []
current_id = 1

实现接口一：获取所有图书（GET /books）

@app.get("/books", response_model=list[Book])
def get_books():
    return books_db

这里我们用了 response_model 来指定返回的数据结构类型，FastAPI 会自动帮你转换格式。

实现接口二：添加新书（POST /books）

@app.post("/books", response_model=Book)
def create_book(book: BookCreate):
    global current_id
    new_book = Book(**book.model_dump(), id=current_id)
    books_db.append(new_book)
    current_id += 1
    return new_book

API接口文档-1

⚠️ 技术点解析：

model_dump()：将模型对象转换为字典形式

使用 global 是因为我们目前只是模拟数据库，正式项目中应该使用真实的数据库系统

实现接口三：模糊搜索图书（GET /books/search）

@app.get("/books/search", response_model=list[Book])
def search_books(title: str):
    result = [b for b in books_db if title.lower() in b.title.lower()]
    return result

实现接口四：删除一本书（DELETE /books/{book_id}）

@app.delete("/books/{book_id}", status_code=204)
def delete_book(book_id: int):
    for book in books_db:
        if book.id == book_id:
            books_db.remove(book)
            return
    raise HTTPException(status_code=404, detail="未找到这本书")

第四步：运行并测试你的项目

保存好文件后，在终端执行：

python main.py

访问 http://localhost:8000/docs 查看生成的文档，并试试各个接口的功能：

POST /books：添加新书
GET /books：查看所有书
GET /books/search?title=xxx：搜索书
DELETE /books/{book_id}：删除书

最终效果预览

假设你添加了一本书：

{
  "title": "Python 入门",
  "author": "张三",
  "category": "编程",
  "published_year": 2023
}

那么调用 /books 你会看到类似这样的结果：

[
  {
    "title": "Python 入门",
    "author": "张三",
    "category": "编程",
    "published_year": 2023,
    "id": 1
  }
]

一切正常，恭喜你完成了人生第一个 FastAPI 项目！

常见问题解答（FAQ）

在刚学习的过程中，你会遇到各种各样的疑问。下面是新手最容易踩坑的问题和对应的解决办法：

❓1. 为什么我的接口不能访问？返回 404？

常见原因：

✅ 解决方法：

确保 URL 正确（比如有没有多空格、有没有拼错）
检查路由是否正确写了前缀 /
如果是 POST 请求，请确认是否加了装饰器 @app.post
重启服务后重新尝试访问

❓2. 如何修改默认端口号？

默认 FastAPI 是运行在 8000 端口的。如果你想改端口号，比如改成 8080，只需要修改启动代码中的 port 即可：

uvicorn.run(app, host="0.0.0.0", port=8080)

❓3. 我的 Pydantic 模型无法识别中文字段名怎么办？

FastAPI 使用的是 Python 的标准语法，所以字段名必须是英文（推荐使用下划线命名法）。如果你写成中文会出现报错。

✅ 正确做法：

class StudentCreate(BaseModel):
    name: str      # 英文字段
    age: int

❌ 错误示范：

class StudentCreate(BaseModel):
    姓名: str      # 中文字段会导致错误

❓4. 为什么我的 POST 请求总是返回 422？

422 是 FastAPI 的数据校验失败错误码。通常意味着你提交的 JSON 数据不符合模型定义的结构。

✅ 解决方法：

查看接口文档中的模型要求
检查 JSON 是否缺少必要字段
是否字段类型不对（比如应该是整数却传了字符串）

❓5. 能否在 Windows 上使用？

当然可以。FastAPI 在 Windows 上完全支持。如果你使用 PyCharm、VSCode 等 IDE，甚至可以一键启动调试。

❓6. 我写的 API 返回中文乱码？

FastAPI 默认会以 UTF-8 编码返回数据，一般不会出现乱码。但如果浏览器或 Postman 显示乱码，可以试试以下方法：

浏览器右键 → 页面信息 → 查看编码是否设置为 UTF-8
Postman 设置中确认编码为 UTF-8

掌握了这些常见问题的解决方案，你在学习过程中就会少走很多弯路啦！

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

恭喜你完成了本次入门教程，现在你已经具备了一个 FastAPI 初级开发者的技能！

那么接下来该怎么进一步提升呢？我给你几点实用建议：

1. 学习连接真实数据库

我们当前的例子用的是内存中的模拟数据。下一步应该学会使用数据库，比如：

SQLite：适合小型项目、本地测试
PostgreSQL：适合中大型项目
MySQL：广泛应用的关系型数据库

你可以配合 ORM 工具如：

进行数据库操作。

2. 学习中间件和依赖注入

FastAPI 提供了强大的中间件机制和依赖注入系统，可以用来：

记录日志
验证权限
处理请求头或 Cookie
实现认证（如 JWT）

这些知识会让你的应用更加安全、专业。

3. 学习异步编程（async/await）

FastAPI 对异步支持非常好。掌握 async/await

标签:JavaGo综合Springboot

最热最新

暂无评论

为你推荐

暂无相关推荐