第一步¶

最简单的 FastAPI 文件如下所示

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

将其复制到 main.py 文件中。

运行实时服务器

$ <font color="#4E9A06">fastapi</font> dev

  <span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting development server 🚀

             Searching for package file structure from directories
             with <font color="#3465A4">__init__.py</font> files
             Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>

   <span style="background-color:#007166"><font color="#D3D7CF"> module </font></span>  🐍 main.py

     <span style="background-color:#007166"><font color="#D3D7CF"> code </font></span>  Importing the FastAPI app object from the module with
             the following code:

             <u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>

      <span style="background-color:#007166"><font color="#D3D7CF"> app </font></span>  Using import string: <font color="#3465A4">main:app</font>

   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font>
   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000/docs</u></font>

      <span style="background-color:#007166"><font color="#D3D7CF"> tip </font></span>  Running in development mode, for production use:
             <b>fastapi run</b>

             Logs:

     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Will watch for changes in these directories:
             <b>[</b><font color="#4E9A06">&apos;/home/user/code/awesomeapp&apos;</font><b>]</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font> <b>(</b>Press CTRL+C
             to quit<b>)</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started reloader process <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> using WatchFiles
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started server process <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Waiting for application startup.
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Application startup complete.

在输出中，有一行类似于

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

该行显示了你的应用在本地机器上运行的 URL。

检查一下¶

在浏览器中打开 http://127.0.0.1:8000。

你将看到如下 JSON 响应

{"message": "Hello World"}

交互式 API 文档¶

现在前往 http://127.0.0.1:8000/docs。

你将看到自动交互式 API 文档（由 Swagger UI 提供）

Swagger UI

替代 API 文档¶

现在，前往 http://127.0.0.1:8000/redoc。

你将看到替代性的自动文档（由 ReDoc 提供）

ReDoc

OpenAPI¶

FastAPI 使用定义 API 的 OpenAPI 标准为您所有的 API 生成一个“模式”。

“模式”¶

“模式”是对某事物的定义或描述。它不是实现该事物的代码，而仅仅是一种抽象描述。

API “模式”¶

在这种情况下，OpenAPI 是一项规范，它规定了如何定义 API 的模式。

此模式定义包含了你的 API 路径、它们接收的可能参数等。

数据 “模式”¶

术语“模式”也可能指代某种数据的形状，例如 JSON 内容。

在这种情况下，它意味着 JSON 属性、它们拥有的数据类型等。

OpenAPI 与 JSON Schema¶

OpenAPI 为你的 API 定义了一个 API 模式。该模式使用 JSON Schema（JSON 数据模式的标准）包含了 API 发送和接收的数据定义（或“模式”）。

查看 `openapi.json`¶

如果你好奇原始 OpenAPI 模式是什么样的，FastAPI 会自动生成一个包含你所有 API 描述的 JSON（模式）。

你可以直接访问：http://127.0.0.1:8000/openapi.json 查看。

它将显示一个以类似内容开头的 JSON

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {



...

OpenAPI 的用途¶

OpenAPI 模式是驱动所包含的两个交互式文档系统的基础。

此外还有许多其他替代方案，它们全部基于 OpenAPI。你可以轻松地将这些替代方案添加到使用 FastAPI 构建的应用程序中。

你还可以使用它为与你的 API 通信的客户端自动生成代码。例如，前端、移动或物联网 (IoT) 应用程序。

在 `pyproject.toml` 中配置应用 `entrypoint`¶

你可以在 pyproject.toml 文件中配置你的应用位置，例如

[tool.fastapi]
entrypoint = "main:app"

该 entrypoint 将告诉 fastapi 命令它应该像这样导入应用

from main import app

如果你的代码结构如下

.
├── backend
│   ├── main.py
│   ├── __init__.py

那么你会将 entrypoint 设置为

[tool.fastapi]
entrypoint = "backend.main:app"

这等同于

from backend.main import app

使用路径或 `--entrypoint` 命令行选项运行 `fastapi dev`¶

你也可以将文件路径传递给 fastapi dev 命令，它会猜测要使用的 FastAPI 应用对象

$ fastapi dev main.py

或者，你也可以将 --entrypoint 选项传递给 fastapi dev 命令

$ fastapi dev --entrypoint main:app

但你必须记住，每次调用 fastapi 命令时都要传递正确的路径/入口点。

此外，其他工具可能无法找到它，例如 VS Code 扩展或 FastAPI Cloud，因此建议在 pyproject.toml 中使用 entrypoint。

部署你的应用（可选）¶

你可以选择将 FastAPI 应用部署到 FastAPI Cloud，如果你还没有加入，请去加入候补名单。🚀

如果你已经拥有 FastAPI Cloud 账户（我们会从候补名单中邀请你 😉），你可以用一个命令部署你的应用。

在部署之前，请确保你已登录

$ fastapi login

You are logged in to FastAPI Cloud 🚀

然后部署你的应用

$ fastapi deploy

Deploying to FastAPI Cloud...

✅ Deployment successful!

🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev

就是这样！现在你可以在那个 URL 访问你的应用了。✨

回顾，分步说明¶

第一步：导入 `FastAPI`¶

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

FastAPI 是一个 Python 类，它提供了 API 的所有功能。

技术细节

FastAPI 是一个直接继承自 Starlette 的类。

你也可以在 FastAPI 中使用所有的 Starlette 功能。

第二步：创建 `FastAPI` “实例”¶

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

这里的 app 变量将是 FastAPI 类的一个“实例”。

这将是创建你所有 API 的主要交互点。

第三步：创建路径操作¶

路径 (Path)¶

此处的“路径”是指 URL 中从第一个 / 开始的最后一部分。

因此，在类似这样的 URL 中

https://example.com/items/foo

...路径将是

/items/foo

注意

“路径”通常也称为“端点 (endpoint)”或“路由 (route)”。

在构建 API 时，“路径”是区分“关注点”和“资源”的主要方式。

操作 (Operation)¶

此处的“操作”是指 HTTP “方法”之一。

包括

POST
GET
PUT
DELETE

...以及更少见的方法

OPTIONS
HEAD
PATCH
TRACE

在 HTTP 协议中，你可以使用这些“方法”中的一种（或多种）与每个路径进行通信。

构建 API 时，通常使用这些特定的 HTTP 方法来执行特定的操作。

通常使用

POST：创建数据。
GET：读取数据。
PUT：更新数据。
DELETE：删除数据。

因此，在 OpenAPI 中，每种 HTTP 方法都被称为一个“操作”。

我们也将其称为“操作”。

定义路径操作装饰器¶

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

@app.get("/") 告诉 FastAPI，下方的函数负责处理发往以下位置的请求

路径 /
使用 get 操作

@decorator 信息

Python 中的 @something 语法称为“装饰器”。

你把它放在函数上方。就像一顶漂亮的装饰帽（我想这就是这个术语的由来）。

“装饰器”接收下方的函数并对其进行一些处理。

在我们的例子中，该装饰器告诉 FastAPI 下方的函数对应于路径 / 和操作 get。

它是“路径操作装饰器”。

你也可以使用其他操作

@app.post()
@app.put()
@app.delete()

以及更少见的操作

@app.options()
@app.head()
@app.patch()
@app.trace()

提示

你可以随意使用每种操作（HTTP 方法）。

FastAPI 不强制任何特定含义。

此处的信息仅作为指南，而非强制要求。

例如，使用 GraphQL 时，通常仅使用 POST 操作来执行所有动作。

第四步：定义路径操作函数¶

这是我们的“路径操作函数”

路径：是 /。
操作：是 get。
函数：是“装饰器”下方的函数（@app.get("/") 下方）。

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

这是一个 Python 函数。

每当 FastAPI 收到使用 GET 操作发送到 URL “/” 的请求时，它就会被调用。

在此例中，它是一个 async 函数。

你也可以将其定义为普通函数，而不是 async def

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


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

注意

如果你不知道两者的区别，请查看异步：“赶时间吗？”。

第五步：返回内容¶

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

你可以返回 dict、list，或作为 str、int 等的单一值。

你也可以返回 Pydantic 模型（稍后会详细介绍）。

还有许多其他对象和模型会自动转换为 JSON（包括 ORM 等）。尝试使用你最喜欢的对象，它们极有可能已经被支持。

第六步：部署它¶

使用命令 fastapi deploy 将你的应用部署到 FastAPI Cloud。🎉

关于 FastAPI Cloud¶

FastAPI Cloud 由 FastAPI 背后的作者和团队构建。

它以最小的努力简化了 API 的构建、部署和访问过程。

它将使用 FastAPI 构建应用的开发者体验带到了将它们部署到云端的过程中。🎉

FastAPI Cloud 是 FastAPI 及其相关开源项目的主要赞助商和资金提供者。✨

部署到其他云提供商¶

FastAPI 是开源的并且基于标准。你可以将 FastAPI 应用部署到你选择的任何云服务提供商。

遵循你的云服务提供商的指南来部署 FastAPI 应用。🤓

回顾¶

导入 FastAPI。
创建一个 app 实例。
使用类似 @app.get("/") 的装饰器编写路径操作装饰器。
定义一个路径操作函数；例如，def root(): ...。
使用命令 fastapi dev 运行开发服务器。
选择性地使用 fastapi deploy 部署你的应用。

第一步¶

检查一下¶

交互式 API 文档¶

替代 API 文档¶

OpenAPI¶

“模式”¶

API “模式”¶

数据 “模式”¶

OpenAPI 与 JSON Schema¶

查看 openapi.json¶

OpenAPI 的用途¶

在 pyproject.toml 中配置应用 entrypoint¶

使用路径或 --entrypoint 命令行选项运行 fastapi dev¶

部署你的应用（可选）¶

回顾，分步说明¶

第一步：导入 FastAPI¶

第二步：创建 FastAPI “实例”¶

第三步：创建路径操作¶

路径 (Path)¶

操作 (Operation)¶

定义路径操作装饰器¶

第四步：定义路径操作函数¶

第五步：返回内容¶

第六步：部署它¶

关于 FastAPI Cloud¶

部署到其他云提供商¶

回顾¶

查看 `openapi.json`¶

在 `pyproject.toml` 中配置应用 `entrypoint`¶

使用路径或 `--entrypoint` 命令行选项运行 `fastapi dev`¶

第一步：导入 `FastAPI`¶

第二步：创建 `FastAPI` “实例”¶