告别Postman！FastAPI框架自带了接口测试神器

王二哥的技术笔记
34 阅读7分钟

[toc]

告别Postman！FastAPI框架自带了接口测试神器

项目概述

image-20251223215343455

本小节，我们将总体的介绍我们的 “书籍项目”。

我们将创建一个 FastAPI 项目。通过此项目，我们将学习所有的基本的 HTTP 请求方法。以及，我们将真正的学习如何使用 FastAPI。

So, 我们需要一个书籍的列表。这些书籍信息以一个键值对形式存在。所以，标题要有一个值、作者要有一个值、类别也要有一个值。

我们将使用标题一～标题五来命名这些标题。使用作者一～作者五来命名这些作者。类别的话，将分成不同的类别，如科学、历史、数学。

BOOKS = [
    {
        'title': 'Title One', 
        'author': 'Author One', 
        'category': 'science'
    }, {
        'title': 'Title Two', 
        'author': 'Author Two', 
        'category': 'science'
    }, {
        'title': 'Title Three', 
        'author': 'Author Three', 
        'category': 'history'
    }, {
        'title': 'Title Four',
        'author': 'Author Four', 
        'category': 'math'
    }, {
        'title': 'Title Five', 
        'author': 'Author Five', 
        'category': 'math'
    }, {
        'title': 'Title Six', 
        'author': 'Author Six', 
        'category': 'math'
    }
]

对于这些书籍，我们将会使用 CRUD 来操作这些书籍列表。

CRUD 分别代表：创建 Create、读取 Read、更新 Update、删除 Delete。

So, 我们将会创建新的书籍信息添加到列表中；我们将读取书籍信息；我们也会更新书籍信息；并且也能够从列表中删除书籍信息；

image-20251224105507966

首先，我们需要先了解 HTTP 的请求和响应。

我们将通过一个浏览器网页与 FastAPI 服务器进行通信。网页将向 FastAPI 服务器发送请求，FastAPI 将向网页发送响应。

然后，在网页的请求从 FastAPI 获取信息时，它使用 HTTP 请求方法进行通信。这些 HTTP 请求方法是网页与服务器之间的通信方式，它们会告诉服务器，它们请求的请求类型。

想想，这是不是有点像 CRUD 操作（创建 Create、读取 Read、更新 Update、删除 Delete）。

幸运的是，FastAPI 已经有了一个叫做 Swagger ui 的实现，并且，已经集成到了应用程序中了。现在获取 Swagger ui 非常容易。它将随着 FastAPI 应用程序启动，自动生成交互式的文档。Swagger ui 包含了FastAPI 服务器可以调用的请求方法的列表。在后面的小节中，我将一步一步地给大家来做介绍。

HTTP 的请求方法有自己的关键词，与我们的应用程序中需要使用的 CRUD 操作一一对应。

CRUD 操作HTTP 请求方法
CreatePOST
ReadGET
UpdatePUT
DeleteDELETE

HTTP 的 GET 请求方法

我们将在 FastAPI 应用程序中进行讨论，如何创建 GET 请求方法？这样，我们就可以从 FastAPI 服务器读取信息给客户端。

首先，我们将讲解 HTTP 中的 GET 请求方法。我们先来创建一个 FastAPI 应用程序，并新建一个名为 “books.py” 的文件。

现在，我们在这个新文件中，先导入 FastAPI 。

from fastapi import FastAPI

然后，把 FastAPI 进行初始化，创建一个应用实例。并把它赋值给 app 变量，后续将通过它来定义和运行接口。

app = FastAPI()

最后，定义你的第一个 HTTP GET 接口。

@app.get("/api-endpoint")
async def first_api():
    return {"message": "Hello World!"}

代码解读：

@app.get("/api-endpoint")

这表示我们定义了一个 HTTP GET 接口，访问路径为 /api-endpoint。

async def first_api():

这是一个异步处理函数。虽然在 FastAPI 中并非强制使用 async（FastAPI 也支持普通同步函数），但这里我们显示的使用 async来标识它可用于异步处理，这也是现代 Web 框架的常见做法。

{“message”: "Hello World!"}

当客户端请求这个接口时，服务器将以 JSON 格式返回这个字典内容。

启动你的 FastAPI 服务器

打开的终端，准备运行我们的 FastAPI 应用程序。在终端中输入如下命令：

uvicorn book:app --reload

命令解读

uvicorn 高性能的 ASGI 服务器，专门为运行 FastAPI 等异步 Web 应用而设计

books:app 指定要运行的应用。books：Python 文件名称（books.py）。app：在文件中创建的 FastAPI 实例名称。

--reload 开发模式下启用热重载，代码更改后服务器自动重启

执行命令后，你将在终端看到 Application startup complete. ，这表示服务器已经启动的成功了。此时，你的 FastAPI 应用已运行在 http://127.0.0.1:8000。

优化你的 API 接口设计

回顾我们当前的 API 接口

@app.get("/api-endpoint")
async def first_api():
    return {"message": "Hello World!"}

这个接口虽然功能正常，但在设计上存在一个明显问题：路径/api-endpoint无法清晰表达接口的实际功能，用户无法从 URL 直观理解这个接口的作用。

为了让 API 更加直观和易用，我们需要遵循 RESTful 设计原则，做如下修改：

1、修改路径，以明确功能

# 修改前
@app.get("/api-endpoint")

# 修改后：路径可以清晰的表达功能
@app.get("/books")

2、返回实际的数据，将接口返回从简单的欢迎消息改为实际的书籍列表

BOOKS = [
    {'title': 'Title One', 'author': 'Author One', 'category': 'science'},
    {'title': 'Title Two', 'author': 'Author Two', 'category': 'science'},
    # .... 更多书籍信息
]


@app.get("/books")
async def read_all_books():
    return BOOKS

完整代码示例：

from fastapi import FastAPI

app = FastAPI()

BOOKS = [
    {'title': 'Title One', 'author': 'Author One', 'category': 'science'},
    {'title': 'Title Two', 'author': 'Author Two', 'category': 'science'},
    {'title': 'Title Three', 'author': 'Author Three', 'category': 'history'},
    {'title': 'Title Four', 'author': 'Author Four', 'category': 'math'},
    {'title': 'Title Five', 'author': 'Author Five', 'category': 'math'},
    {'title': 'Title Six', 'author': 'Author Six', 'category': 'math'},
]


@app.get("/books")
async def read_all_books():
    return BOOKS

现在，你可以通过浏览器去访问 127.0.0.1:8000/books 这个地址，这将快速返回当前这个 FastAPI 应用程序中的所有书籍。

image-20251224095554743转存失败，建议直接上传图片文件

API 接口优化

基于前面的学习，我们已经拥有了第一个 API 接口。在浏览器中访问 http://127.0.0.1:8000/books 后，得到正确的响应如下：

image-20251224095554743

不知道你在浏览器中看到密密麻麻、难以阅读的JSON数据时，是不是有种“锦衣夜行”的遗憾？就像精心准备的宴席，却用一次性饭盒装盘呈现。

在本小节中，我们就来解决这个痛点，让你的FastAPI接口从“能用的工具”升级为“好用的产品”。

1、构建专业的数据模型，让返回的内容结构化
BOOKS = [
    {'title': 'Title One', 'author': 'Author One', 'category': 'science'},
    {'title': 'Title Two', 'author': 'Author Two', 'category': 'science'},
    {'title': 'Title Three', 'author': 'Author Three', 'category': 'history'},
    {'title': 'Title Four', 'author': 'Author Four', 'category': 'math'},
    {'title': 'Title Five', 'author': 'Author Five', 'category': 'math'},
    {'title': 'Title Six', 'author': 'Author Six', 'category': 'math'},
]

设计要点：字段命名要直观，数据结构要一致，这是API专业性的基础

2、优化接口，让路径语义化
# 模糊的接口设计
@app.get("/api-endpoint")
async def fast_api():
    return BOOKS

# 清晰的语义化设计
@app.get("/books")
async def read_all_books():
    return BOOKS

read_all_books 函数名准确描述了功能，便于团队协作和维护

3、利用 Swagger UI，让 API 文档自动化

这是 FastAPI 最强大的特性之一！访问 http://127.0.0.1:8000/docs 就可以看到。

image-20251224102111188

Swagger UI 的三大优势：

  1. 自动生成文档：无需手动编写API文档，节省大量时间
  2. 交互式测试：直接在浏览器中测试接口，无需Postman等工具
  3. 实时反馈：每次代码修改后，文档自动更新

如何使用 Swagger UI:

  1. 访问 http://127.0.0.1:8000/docs
  2. 找到 /books 接口，点击打开它
  3. 点击 “Try it out”，再点击 “Execute” 执行请求
  4. 查看响应码和响应结果
4、利用热重载，提升效率

开发期间，使用--reload参数启动服务：

uvicorn books:app --reload

每次保存代码文件后，服务器自动重启，无需手动停止再启动。

-------- 写在最后 --------

希望这篇教程能让你感受到 FastAPI 的魅力！对 FastAPI 有一个全面的了解。

点赞 ：如果觉得有收获，点个赞支持一下吧！

分享 ：分享给身边同样对数据分析和Python感兴趣的朋友！

关注 ：不错过每一篇 Python 实战干货！

每周更新 Python 自动化办公、Web 开发、算法等硬核技巧，助你成为 10 倍效率的开发者！

#Python #FastAPI #API #Web开发 #程序员 #编程教程 #效率提升

avatar
文章
阅读
粉丝