FastAPI 入门指南：快速构建高性能API – wiki词典

作者： /

FastAPI 入门指南：快速构建高性能API

在当今快速发展的数字世界中，API（应用程序编程接口）是连接不同软件系统、实现数据交换的基石。Python 生态系统拥有众多 Web 框架，而 FastAPI 作为后起之秀，凭借其卓越的性能、开发效率以及一系列开箱即用的功能，迅速成为构建高性能 API 的首选框架之一。

什么是 FastAPI？

FastAPI 是一个现代、高性能的 Python Web 框架，专门用于构建 API。它基于标准的 Python 类型提示，并充分利用了 Starlette (用于 Web 部分) 和 Pydantic (用于数据验证和序列化) 这两个强大的库，旨在提供：

  • 极高的开发速度：通过自动代码生成和类型检查，减少人工错误。
  • 出色的运行时性能：与 Node.js 和 Go 应用程序不相上下。
  • 直观的交互式文档：自动生成 OpenAPI (Swagger UI) 和 ReDoc 文档。
  • 强大的数据验证：确保请求和响应数据的正确性。

FastAPI 的核心优势

  1. 高性能
    FastAPI 的设计核心是性能。它使用 Starlette 作为 Web 部分，并与高性能的 ASGI 服务器（如 Uvicorn）结合，使其在基准测试中能够达到与 Go 和 Node.js 媲美的速度，远超传统的 Python Web 框架如 Flask 和 Django。这对于需要处理大量并发请求的现代 API 服务至关重要。

  2. 开发效率高
    FastAPI 深度整合了 Python 类型提示，这意味着在编写代码时，IDE（如 VS Code、PyCharm）能够提供出色的自动补全、错误检查和代码重构支持。框架能够自动处理数据验证、序列化、反序列化，并根据类型提示生成 OpenAPI 规范，从而大幅减少开发者编写样板代码的时间，加速功能开发。

  3. 自动生成 API 文档
    这是 FastAPI 最引人注目的特性之一。无需额外配置，只需编写带有类型提示的视图函数，FastAPI 就会自动生成符合 OpenAPI 规范（原 Swagger）的交互式 API 文档。您可以通过访问 /docs 路径获得 Swagger UI 文档，或通过 /redoc 路径获得 ReDoc 文档。这些文档不仅美观，还支持在线测试 API，极大地简化了前后端协作和 API 对接过程。

  4. 强大的数据验证
    FastAPI 利用 Pydantic 库实现参数的自动校验和类型推导。通过在函数参数和 Pydantic 模型中声明类型，框架可以在数据到达业务逻辑之前进行严格的验证。如果传入的数据不符合预期类型或结构，FastAPI 会自动返回详细的错误信息，有效减少运行时错误和数据不一致的问题。

  5. 异步支持
    原生支持 Python 的 async 和 await 关键字，这意味着 FastAPI 可以无缝地处理异步操作。这对于 I/O 密集型任务（如数据库查询、网络请求）来说是一个巨大的优势，能够显著提高 API 的并发处理能力和响应速度，避免阻塞。

  6. 优秀的编辑器支持
    得益于其对标准 Python 类型提示的全面使用，FastAPI 提供了无与伦比的编辑器支持。这意味着开发者在编写代码时，可以获得更智能的代码补全、即时错误反馈以及更好的重构体验，从而提高开发效率和代码质量。

入门指南

让我们通过一个简单的例子来快速构建你的第一个 FastAPI 应用。

1. 环境准备

确保你的系统安装了 Python 3.6 或更高版本。为了获得最佳的类型提示体验，推荐使用 Python 3.8+。

2. 安装 FastAPI 和 Uvicorn

FastAPI 框架本身以及一个 ASGI 服务器（如 Uvicorn）是运行 FastAPI 应用的必需组件。Uvicorn 是一个高性能的 ASGI 服务器。

打开终端并执行以下命令进行安装：

bash
pip install fastapi "uvicorn[standard]"

uvicorn[standard] 会安装 Uvicorn 以及一些常用的可选依赖，例如 python-multipart 用于表单数据。

3. 创建你的第一个 FastAPI 应用

创建一个名为 main.py 的文件，并添加以下代码：

“`python
from fastapi import FastAPI

创建 FastAPI 应用实例

app = FastAPI()

定义一个根路径的 GET 请求处理函数

@app.get(“/”)
async def read_root():
“””
一个简单的根路径 GET 请求，返回欢迎消息。
“””
return {“message”: “Hello, FastAPI!”}
“`

4. 运行应用

在 main.py 文件所在的目录下，打开终端并运行以下命令：

bash
uvicorn main:app --reload

  • main: 指的是 main.py 文件（不包含 .py 后缀）。
  • app: 指的是 main.py 文件中创建的 FastAPI() 实例对象。
  • --reload: 这是一个开发模式的选项，它会在代码发生更改时自动重新加载服务器，非常方便调试。

您将在终端中看到类似以下的输出：

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [PID] using WatchFiles
INFO: Started server process [PID]
INFO: Waiting for application startup.
INFO: Application startup complete.

5. 访问 API 和交互式文档

现在，你的 FastAPI 应用已经在 http://127.0.0.1:8000 运行了。

  • 访问 API：在浏览器中打开 http://127.0.0.1:8000，您将看到 JSON 响应 {"message": "Hello, FastAPI!"}。
  • Swagger UI 文档：访问 http://127.0.0.1:8000/docs，您将看到由 Swagger UI 提供的自动交互式 API 文档，可以方便地测试你的 API。
  • ReDoc 文档：访问 http://127.0.0.1:8000/redoc，您将看到由 ReDoc 提供的另一种风格的自动 API 文档。

6. 路径参数 (Path Parameters)

路径参数是 URL 路径的一部分，用于标识特定的资源。FastAPI 会自动根据类型提示进行验证。

“`python
from fastapi import FastAPI

app = FastAPI()

@app.get(“/items/{item_id}”)
async def read_item(item_id: int):
“””
根据 item_id 获取单个物品信息。
“””
return {“item_id”: item_id}
“`

在这个例子中，{item_id} 是一个路径参数。item_id: int 告诉 FastAPI item_id 应该是一个整数。如果你访问 /items/5，它将返回 {"item_id": 5}。如果你访问 /items/abc，FastAPI 会自动返回一个 422 验证错误。

7. 查询参数 (Query Parameters)

查询参数是 URL 中 ? 之后的部分，通常用于过滤、排序或分页。

“`python
from fastapi import FastAPI

app = FastAPI()

@app.get(“/items/”)
async def read_items(skip: int = 0, limit: int = 10):
“””
获取物品列表，支持分页。
“””
return {“skip”: skip, “limit”: limit}
“`

skip: int = 0 和 limit: int = 10 定义了带有默认值的查询参数。访问 http://127.0.0.1:8000/items/?skip=5&limit=15 将返回 {"skip": 5, "limit": 15}。

8. 请求体 (Request Body)

对于 POST、PUT 等请求，客户端通常会发送数据作为请求体。FastAPI 使用 Pydantic 模型来定义请求体的结构和数据类型。

首先，确保安装了 Pydantic：

bash
pip install pydantic

然后，修改 main.py：

“`python
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional # 用于可选字段

app = FastAPI()

定义一个 Pydantic 模型来描述请求体的结构

class Item(BaseModel):
name: str
description: Optional[str] = None # 可选字段，默认值为 None
price: float
tax: Optional[float] = None # 可选字段

@app.post(“/items/”)
async def create_item(item: Item):
“””
创建一个新物品。
“””
return item
“`

当您向 /items/ 发送一个 POST 请求，请求体为 JSON 格式时，FastAPI 会自动验证数据是否符合 Item 模型的定义。例如，发送以下 JSON：

json
{
"name": "Foo",
"price": 10.5
}

FastAPI 会接收并验证，并返回相同的 JSON 数据。如果 name 或 price 缺失，或者类型不正确，FastAPI 将自动返回 422 验证错误。

总结

FastAPI 是一个功能强大、易学易用且性能卓越的 Python Web 框架。通过充分利用 Python 类型提示，它不仅极大地提升了开发效率，还提供了自动文档生成、强大的数据验证和原生异步支持等现代化特性。无论你是构建简单的微服务还是复杂的企业级 API，FastAPI 都能提供一套高效、可靠的解决方案。

现在，你已经掌握了 FastAPI 的基本概念和用法，是时候深入探索它的更多高级特性，例如依赖注入、安全认证、中间件、数据库集成等，以构建更健壮、更强大的高性能 API 了。

滚动至顶部