三周精通FastAPI：1 第一步入门

FastAPI是一个非常棒的python web和api框架，准备用三周的时间“精通它”

学习流程参考FastAPI官网的用户教程：教程 - 用户指南 - FastAPI

 

学前提示

运行代码¶

所有代码片段都可以复制后直接使用（它们实际上是经过测试的 Python 文件）。

要运行任何示例，只需将代码复制到 main.py 文件中，然后使用以下命令启动 uvicorn：

uvicorn main:app --reload

这样就会在本地启动web服务器，默认侦听端口是8000

如果想远程访问调试，可以增加host参数：

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

这样就可以远程访问了。

 这里给一个main.py的示例文件：

from typing import Union
from fastapi import FastAPIapp = FastAPI()@app.get("/")
def read_root():return {"Hello": "World"}@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):return {"item_id": item_id, "q": q}

运行后可以远程访问：

uvicorn main:app --host 0.0.0.0 --port 8000 --reload 
INFO:     Will watch for changes in these directories: ['/home/skywalk/work/awesome']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [66615] using WatchFiles
INFO:     Started server process [66617]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     192.168.1.2:54676 - "GET / HTTP/1.1" 200 OK
INFO:     192.168.1.2:54863 - "GET /?name=tom HTTP/1.1" 200 OK
INFO:     192.168.1.2:54870 - "GET /items/5 HTTP/1.1" 200 OK

 

安装 FastAPI¶

第一个步骤是安装 FastAPI。

为了使用本教程，需要安装所有的可选依赖及对应功能：

pip install "fastapi[all]"

使用下来，感觉"fastapi[all]"比"fastapi[standard]"要多装这些库：itsdangerous-2.2.0 orjson-3.10.7 pydantic-extra-types-2.9.0 pydantic-settings-2.5.2 ujson-5.10.0

第一步入门¶

最简单的 FastAPI 文件可能像下面这样：

from fastapi import FastAPIapp = FastAPI()@app.get("/")
async def root():return {"message": "Hello World"}

将其复制到 main.py 文件中。运行实时服务器：

uvicorn main:app --reload
INFO:     Will watch for changes in these directories: ['/home/skywalk/work/awesome']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [67008] using WatchFiles
INFO:     Started server process [67010]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

uvicorn main:app 命令含义如下:

• main：main.py 文件（一个 Python「模块」）。
• app：在 main.py 文件中通过 app = FastAPI() 创建的对象。
• --reload：让服务器在更新代码后重新启动。仅在开发时使用该选项。

在输出中，会有一行信息像下面这样：

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 提供）：

可选的 API 文档¶

前往 http://127.0.0.1:8000/redoc。

将会看到可选的自动生成文档 （由 ReDoc 提供)：

个人感觉ReDoc比 Swagger UI响应速度要快。

OpenAPI¶

FastAPI 使用 OpenAPI 定义 API 的标准生成「schema」（架构？模式？  ）。

「schema」¶

「schema」是对事物的一种定义或描述。它并非具体的实现代码，而只是抽象的描述。

API「schema」¶

在这种场景下，OpenAPI 是一种规定如何定义 API 模式的规范。

定义的 OpenAPI 模式将包括 API 路径，以及它们可能使用的参数等等。

数据「schema」¶

「schema」这个术语也可能指的是某些数据比如 JSON 的结构。

在这种情况下，它可以表示 JSON 的属性及其具有的数据类型，等等。

OpenAPI 和 JSON Schema¶

OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送和接收的数据的定义（或称为「模式」），这些定义通过 JSON 数据模式标准 JSON Schema 所生成。

查看 openapi.json¶

如果你对原始的 OpenAPI 模式长什么样子感到好奇，其实它只是一个自动生成的包含了所有 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 的用途¶

驱动 FastAPI 内置的 2 个交互式文档系统的正是 OpenAPI 模式。

并且还有数十种替代方案，它们全部都基于 OpenAPI。你可以轻松地将这些替代方案中的任何一种添加到使用 FastAPI 构建的应用程序中。

你还可以使用它自动生成与你的 API 进行通信的客户端代码。例如 web 前端，移动端或物联网嵌入程序。

分步概括¶

代码

from fastapi import FastAPIapp = FastAPI()@app.get("/")
async def root():return {"message": "Hello World"}

步骤 1：导入 FastAPI¶

from fastapi import FastAPI

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

"技术细节"

FastAPI 是直接从 Starlette 继承的类。

你可以通过 FastAPI 使用所有的 Starlette 的功能。

步骤 2：创建一个 FastAPI「实例」¶

app = FastAPI()

这里的变量 app 会是 FastAPI 类的一个「实例」。

这个实例将是创建你所有 API 的主要交互对象。

这个 app 同样在如下命令中被 uvicorn 所引用：

uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

 

如果你像下面这样创建应用：

from fastapi import FastAPImy_awesome_api = FastAPI()@my_awesome_api.get("/")
async def root():return {"message": "Hello World"}

将代码放入 main.py 文件中，然后你可以像下面这样运行 uvicorn：

uvicorn main:my_awesome_api --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

 

步骤 3：创建一个*路径操作*¶

路径¶

这里的「路径」指的是 URL 中从第一个 / 起的后半部分。

所以，在一个这样的 URL 中：

https://example.com/items/foo 

路径会是：/items/foo

「路径」也通常被称为「端点」或「路由」。

开发 API 时，「路径」是用来分离「关注点」和「资源」的主要手段。

操作¶

这里的「操作」指的是一种 HTTP「方法」。

下列之一：

• POST
• GET
• PUT
• DELETE

...以及更少见的几种：

• OPTIONS
• HEAD
• PATCH
• TRACE

在 HTTP 协议中，你可以使用以上的其中一种（或多种）「方法」与每个路径进行通信。

---

在开发 API 时，你通常使用特定的 HTTP 方法去执行特定的行为。

通常使用：

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

因此，在 OpenAPI 中，每一个 HTTP 方法都被称为「操作」。

我们也打算称呼它们为「操作」。

定义一个*路径操作装饰器* @app.get("/")

@app.get("/") 告诉 FastAPI 在它下方的函数负责处理如下访问请求：

• 请求路径为 /
• 使用 get 操作

"@decorator Info"

@something 语法在 Python 中被称为「装饰器」。

像一顶漂亮的装饰帽一样，将它放在一个函数的上方（我猜测这个术语的命名就是这么来的）。

装饰器接收位于其下方的函数并且用它完成一些工作。

在我们的例子中，这个装饰器告诉 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("/") 下方）。

async def root():

这是一个 Python 函数。

每当 FastAPI 接收一个使用 GET 方法访问 URL「/」的请求时这个函数会被调用。

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

---

你也可以将其定义为常规函数而不使用 async def:

def root():

如果你不知道两者的区别，请查阅 Async: "In a hurry?"。

步骤 5：返回内容¶

    return {"message": "Hello World"}

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

你还可以返回 Pydantic 模型（稍后你将了解更多）。

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

总结¶

• 导入 FastAPI。
• 创建一个 app 实例。
• 编写一个**路径操作装饰器**（如 @app.get("/")）。
• 编写一个**路径操作函数**（如上面的 def root(): ...）。
• 运行开发服务器（如 uvicorn main:app --reload）。

实践

创建一个文件main.py

from fastapi import FastAPIapp = FastAPI()@app.get("/")
async def root():return {"message": "Hello World"}
@app.get("/test")
async def test():return {"message": "This is a test"}

启动服务

uvicorn main:app --host 0.0.0.0 --reload
INFO:     Will watch for changes in these directories: ['/home/skywalk/work/awesome']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [69072] using WatchFiles
INFO:     Started server process [69074]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

然后就可以远程访问192.168.1.5上的web服务了，在浏览器地址栏输入：http://192.168.1.5:8000/test

输出为：

{"message":"This is a test"}