起步指南¶
最简单的 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:solid">main.py</u>
<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">'/home/user/code/awesomeapp'</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://极速API.tiangolo.com/zh/</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><极速API.tiangolo.com/zh/></font><b>]</b> using WatchFiles
<span style="background-color:#007166"><font color="#极速API.tiangolo.com/zh/"> 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极速API.tiangolo.com/zh/></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:800极速API.tiangolo.com/zh/。
你将看到自动生成的交互式 API 文档（由 Swagger UI 提供）：
替代性 API 文档¶
现在，访问 http://127.0.0.1:8000/redoc。
你将看到替代性的自动文档（由 ReDoc 提供）：
OpenAPI¶
FastAPI 使用 OpenAPI 标准为你的所有 API 生成一个“模式”。
“模式”¶
“模式”是对某事物的定义或描述。不是实现它的代码，而只是一个抽象描述。
API “模式”¶
在这种情况下，OpenAPI 是一个规范，规定了如何定义 API 的模式。
这个模式定义包括你的 API 路径、它们可能接受的参数等。
数据“模式”¶
术语“模式”也可能指某些数据的形状，比如 JSON 内容。
在这种情况下，它将指 JSON 属性及其数据类型等。
OpenAPI 和 JSON Schema¶
OpenAPI 为你的 API 定义了一个 API 模式。该模式包括使用 JSON Schema（JSON 数据模式的标准）发送和接收的数据的定义（或“模式”）。
检查 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 通信的客户端。例如，前端、移动或物联网应用。
逐步回顾¶
步骤 1：导入 FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
FastAPI 是一个 Python 类，为你的 API 提供所有功能。
步骤 2：创建一个 FastAPI “实例”¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
这里的 app 变量将是 FastAPI 类的一个“实例”。
这将是创建所有 API 的主要交互点。
步骤 3：创建一个路径操作¶
路径¶
这里的“路径”指的是 URL 中从第一个 / 开始到最后的部分。
因此，在如下 URL 中：
https://example.com/items/foo
...路径将是：
/items/foo
Info
“路径”通常也称为“端点”或“路由”。
在构建 API 时，“路径”是分离“关注点”和“资源”的主要方式。
操作¶
这里的“操作”指的是 HTTP“方法”之一。
其中之一：
POSTGETPUTDELETE
...以及更特殊的方法：
OPTIONSHEADPATCHTRACE
在 HTTP 协议中，你可以使用这些“方法”中的一个（或多个）与每个路径通信。
在构建 API 时，通常使用这些特定的 HTTP 方法来执行特定操作。
通常使用：
POST：创建数据。GET：读取数据。PUT：更新数据。DELETE：删除数据。
因此，在 OpenAPI 中，每个 HTTP 方法被称为一个“操作”。
我们也将称它们为“操作”。
定义一个路径操作装饰器¶
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()
Tip
你可以自由使用每个操作（HTTP 方法）。
FastAPI 不强制任何特定含义。
这里的信息是作为指南呈现的，而不是要求。
例如，在使用 GraphQL 时，通常只使用 POST 操作执行所有操作。
步骤 4：定义路径操作函数¶
这是我们的“路径操作函数”：
- 路径：是
/。 - 操作：是
get。 - 函数：是“装饰器”下面的函数（在
@app.get("/")下面）。
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
这是一个 Python 函数。
每当 FastAPI 收到对 URL“/”使用 GET 操作的请求时，它将调用此函数。
在这种情况下，它是一个 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运行开发服务器。