第一步¶

最简单的 FastAPI 文件可能看起来像这样：

from fastapi import FastAPI

app = FastAPI()


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

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

运行实时服务器：

$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:single">main.py</u>
<font color="#3465A4">INFO    </font> 使用路径 <font color="#3465A4">main.py</font>
<font color="#3465A4">INFO    </font> 解析绝对路径 <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
<font color="#3465A4">INFO    </font> 从包含 <font color="#3465A4">__init__.py</font> 文件的目录中搜索包文件结构
<font color="#3465A4">INFO    </font> 从 <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font> 导入

 ╭─ <font color="#8AE234"><b>Python 模块文件</b></font> ─╮
 │                      │
 │  🐍 main.py          │
 │                      │
 ╰──────────────────────╯

<font color="#3465A4">INFO    </font> 导入模块 <font color="#4E9A06">main</font>
<font color="#3465A4">INFO    </font> 找到可导入的 FastAPI 应用

 ╭─ <font color="#8AE234"><b>可导入的 FastAPI 应用</b></font> ─╮
 │                          │
 │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
 │                          │
 ╰──────────────────────────╯

<font color="#3465A4">INFO    </font> 使用导入字符串 <font color="#8AE234"><b>main:app</b></font>

 <span style="background-color:#C4A000"><font color="#2E3436">╭────────── FastAPI CLI - 开发模式 ───────────╮</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  服务地址: http://127.0.0.1:8000                  │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  API 文档: http://127.0.0.1:8000/docs               │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  运行在开发模式，用于生产环境请使用:               │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#555753"><b>fastapi run</b></font></span><span style="background-color:#C4A000"><font color="#2E3436">                                        │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">╰─────────────────────────────────────────────────────╯</font></span>

<font color="#4E9A06">INFO</font>:     将监视这些目录中的更改: [&apos;/home/user/code/awesomeapp&apos;]
<font color="#4E9A06">INFO</font>:     Uvicorn 运行在 <b>http://127.0.0.1:8000</b> (按 CTRL+C 退出)
<font color="#4E9A06">INFO</font>:     启动重载进程 [<font color="#34E2E2"><b>2265862</b></font>] 使用 <font color="#34E2E2"><b>WatchFiles</b></font>
<font color="#4E9A06">INFO</font>:     启动服务器进程 [<font color="#06989A">2265873</font>]
<font color="#4E9A06">INFO</font>:     等待应用程序启动。
<font color="#4E9A06">INFO</font>:     应用程序启动完成。

在输出中，有一行类似于：

INFO:     Uvicorn 运行在 http://127.0.0.1:8000 (按 CTRL+C 退出)

这一行显示了你的应用在本地机器上服务的 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 使用 OpenAPI 标准为定义 API 生成一个包含所有 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": {



这是“**路径操作装饰器**”。

///

你也可以使用其他操作：

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

以及更少见的操作：

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

/// tip

你可以自由地使用每个操作（HTTP 方法），按照你的意愿。

**FastAPI** 不会强制任何特定的含义。

这里的信息是作为指导方针提供的，而不是要求。

例如，在使用 GraphQL 时，你通常会使用仅包含 `POST` 操作来执行所有操作。

///

### 步骤 4：定义 **路径操作函数**

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

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

```Python hl_lines="7"
from fastapi import FastAPI

app = FastAPI()


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

这是一个 Python 函数。

每当它接收到使用 GET 操作的 URL “/” 的请求时，FastAPI 都会调用它。

在这种情况下，它是一个 async 函数。

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

from fastapi import FastAPI

app = FastAPI()


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

Note

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

步骤 5：返回内容¶

from fastapi import FastAPI

app = FastAPI()


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

你可以返回一个 dict、list，单个值如 str、int 等。

你还可以返回 Pydantic 模型（稍后你会了解更多相关内容）。

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

总结¶

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