Python FastAPI 入门教程 – wiki基地

作者： /

Python FastAPI 入门教程

FastAPI 是一个现代、快速（高性能）的 Web 框架，用于使用 Python 3.7+ 构建 API，它基于标准的 Python 类型提示。它旨在实现快速开发、高性能和自动交互式 API 文档。

为什么选择 FastAPI？

  • 高性能: FastAPI 基于 Starlette (用于 Web 部分) 和 Pydantic (用于数据部分) 构建，使其速度堪比 Go 和 Node.js 等高性能框架。
  • 开发效率: 凭借其现代 Python 特性（如类型提示），FastAPI 极大地提高了开发速度。
  • 自动交互式文档: 自动生成 Swagger UI 和 ReDoc 形式的 API 文档，便于测试和理解 API。
  • 数据验证和序列化: 利用 Pydantic，FastAPI 提供了强大的数据验证和序列化功能，减少了手动验证代码。
  • 易学易用: 语法简洁直观，易于上手。
  • 异步支持: 原生支持 async/await，允许构建高性能的异步 API。

1. 环境搭建与安装

建议为每个项目使用虚拟环境来管理依赖。

  1. 创建虚拟环境:
    bash
    python -m venv venv

  2. 激活虚拟环境:

    • 在 macOS/Linux 上:
      bash
      source venv/bin/activate
    • 在 Windows 上:
      bash
      .\venv\Scripts\activate

  3. 安装 FastAPI 和 Uvicorn:
    FastAPI 需要一个 ASGI 服务器来运行，Uvicorn 是一个流行的选择。
    bash
    pip install fastapi uvicorn

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

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

“`python

main.py

from fastapi import FastAPI
from typing import Optional # 用于定义可选参数
from pydantic import BaseModel # 用于定义请求体模型

创建 FastAPI 实例

app = FastAPI()

定义一个处理根 URL (“/”) 的 GET 请求路由

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

定义一个带路径参数的 GET 请求

@app.get(“/items/{item_id}”)
def read_item(item_id: int, q: Optional[str] = None):
# item_id 是路径参数，被声明为整数
# q 是查询参数，被声明为可选的字符串
if q:
return {“item_id”: item_id, “q”: q}
return {“item_id”: item_id}

定义一个请求体模型

class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[float] = None

定义一个处理 POST 请求的路由，包含请求体

@app.post(“/items/”)
def create_item(item: Item):
# FastAPI 会自动验证传入的请求体是否符合 Item 模型
# 如果数据有效，它将作为 Item 实例传递给函数
return item
“`

  • from fastapi import FastAPI: 导入 FastAPI 类。
  • app = FastAPI(): 创建 FastAPI 类的实例。
  • @app.get("/"): 这是一个“装饰器”，告诉 FastAPI 下面的函数应该处理对 URL 路径 / 的 HTTP GET 请求。
  • def read_root():: 当对 / 发出 GET 请求时，将调用此函数。它返回一个 Python 字典，FastAPI 会自动将其转换为 JSON。
  • @app.get("/items/{item_id}"): 这定义了一个带有 路径参数 item_id 的 GET 接口。类型提示 item_id: int 确保 item_id 是一个整数。
  • q: Optional[str] = None: 这定义了一个可选的 查询参数 q，其默认值为 None。
  • class Item(BaseModel): 使用 Pydantic 定义了一个数据模型，用于验证和序列化请求体的数据。
  • @app.post("/items/"): 定义了一个处理 POST 请求的路由。item: Item 参数告诉 FastAPI 期望一个符合 Item 模型的 JSON 请求体。

3. 运行应用程序

在终端中导航到你的项目目录（main.py 所在的位置），并使用 Uvicorn 运行应用程序：

bash
uvicorn main:app --reload

  • main: 指的是 main.py 文件。
  • app: 指的是 main.py 中创建的 app 对象。
  • --reload: 此标志使服务器在你修改代码时自动重新启动，这在开发过程中非常有用。

你会看到类似以下内容的输出，表明服务器正在运行：

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

4. 测试你的 API

打开你的 Web 浏览器或 API 客户端（如 Postman 或 curl）并访问：

  • http://127.0.0.1:8000: 你应该会看到 {"message": "Hello, FastAPI!"}。
  • http://127.0.0.1:8000/items/5: 你应该会看到 {"item_id": 5}。
  • http://127.00.1:8000/items/5?q=somequery: 你应该会看到 {"item_id": 5, "q": "somequery"}。

要测试 POST /items/ 接口，你需要发送 JSON 请求体。例如，使用 curl：

bash
curl -X POST -H "Content-Type: application/json" -d '{"name": "Foo", "price": 10.5}' http://127.0.0.1:8000/items/

你也可以在交互式 API 文档中进行测试。

5. 交互式 API 文档

FastAPI 最强大的功能之一是其自动交互式 API 文档。

  • Swagger UI: 访问 http://127.0.0.1:8000/docs。在这里你可以看到所有已定义的接口，直接从浏览器测试它们，并查看它们的预期输入和输出模式。
  • ReDoc: 访问 http://127.0.0.1:8000/redoc。这提供了一个替代的、更紧凑的文档视图。

核心概念概览

  • 路径参数 (Path Parameters): 直接嵌入在 URL 路径中的值（例如，/items/{item_id} 中的 {item_id}）。FastAPI 根据你的类型提示自动验证它们的类型。
  • 查询参数 (Query Parameters): 附加在 URL 后面的可选键值对，用 ? 分隔（例如，/items/5?q=somequery 中的 q=somequery）。
  • 请求体 (Request Body): 对于 POST、PUT 和 DELETE 请求，你通常会在请求体中发送数据。FastAPI 使用 Pydantic 模型来定义此数据的结构和验证，充分利用 Python 类型提示。
  • 类型提示 (Type Hints): FastAPI 大量依赖 Python 类型提示（item_id: int，q: str）进行数据验证、序列化和生成文档。

这涵盖了 FastAPI 入门的基础知识。你现在可以探索更高级的功能，例如依赖注入、安全性等。

滚动至顶部