FastAPI官档精编005 - 第一步

呆鸟云：发布本系列旨在推广 FastAPI 以及推进 FastAPI 中文官档翻译，目前，FastAPI 官档已完成 98% 的中文翻译，如果您对 FastAPI 有兴趣，可以为这个很赞的开源项目做些贡献，比如校译、翻译、审阅等。

开源项目的发展离不开大家的支持。当然最简单的就是在 Github 上点 Star 了。

如果觉得 FastAPI 不错，您也可以转发、转载本文，让更多人知道 Python 还有这么简单、快速的后端支持库。

FastAPI 官档地址：https://fastapi.tiangolo.com/zh/

下面先列出几个需要 Review 的 PR，希望大家多多参与。

• https://github.com/tiangolo/fastapi/pull/3826
• https://github.com/tiangolo/fastapi/pull/3827
• https://github.com/tiangolo/fastapi/pull/3828
• https://github.com/tiangolo/fastapi/pull/3829
• https://github.com/tiangolo/fastapi/pull/3830
• https://github.com/tiangolo/fastapi/pull/3832
• https://github.com/tiangolo/fastapi/pull/3793
• https://github.com/tiangolo/fastapi/pull/3795
• https://github.com/tiangolo/fastapi/pull/3796

以下为正文。

---

本指南将逐步介绍 FastAPI 的绝大部分功能。

本指南的每个章节循序渐进，但又有各自的主题，您可以直接阅读所需章节，解决特定的 API 需求。

本指南还是参考手册，供您随时查阅。

运行代码

本指南中的所有代码都能直接复制使用（实际上，这些代码都是经过测试的 Python 文件）。

要运行示例，只需把代码复制到 main.py，用以下命令启动 uvicorn：

$ uvicorn main:app --reload

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

强烈建议您在本机编辑并运行这些代码。

只在有编辑器中输入代码时，您才能真正感受到 FastAPI 的优势，体验到需要输入的代码到底有多少，还有类型检查、自动补全等功能。

---

安装 FastAPI

第一步是安装 FastAPI。

学习本教程，需要安装所有可选依赖支持库：

$ pip install fastapi[all]

......上述命令还安装了运行 FastAPI 应用的服务器 - uvicorn。

!!! note "笔记"

您可以单独安装各个支持库。

需要把应用部署到生产环境时，首先要安装 FastAPI：

```
pip install fastapi
```

然后，还要安装服务器 `uvicorn`：

```
pip install uvicorn[standard]
```

按需单独安装其它可选依赖支持库。

高级用户指南

学完用户指南后，您还可以继续学习高级用户指南。

高级用户指南基于本指南，核心概念都一样，但介绍了更多功能。

建议您先阅读用户指南。

学完用户指南就能开发完整的 FastAPI 应用。然后，再使用高级用户指南中的功能扩展应用。

第一步

最简单的 FastAPI 文件所示如下：

from fastapi import FastAPI

app = FastAPI()


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

复制代码到 main.py。

运行实时服务器：

$ uvicorn main:app --reload

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

!!! note "笔记"

`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)

这是 FastAPI 应用在本机提供服务的 URL。

查看文档

打开浏览器访问 http://127.0.0.1:8000。

JSON 响应如下：

{"message": "Hello World"}

API 文档

跳转到 http://127.0.0.1:8000/docs。

查看自动生成的（Swagger UI）API 文档：

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 概图。该概图包含由 JSON Schema 为 API 发送与接收的数据所做的定义。JSON Schema 是 JSON 数据概图标准。

查看 openapi.json

如果您对 OpenAPI 原始概图感兴趣，FastAPI 自动生成了描述所有 API 的 JSON （概图）。

直接查看：http://127.0.0.1:8000/openapi.json。

JSON 文件的开头如下：

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

OpenAPI 是干什么用的

OpenAPI 概图用于驱动 FastAPI 内置的两个 API 文档。

基于 OpenAPI 的备选方案还有很多，为 FastAPI 应用添加其它备选方案很容易。

OpenAPI 还可以用于自动生成和 API 通信的客户端代码。例如前端、移动端、物联网应用等。

分步小结

第一步：导入 FastAPI

from fastapi import FastAPI

FastAPI 是为 API 提供所有功能的 Python 类。

!!! note "技术细节"

`FastAPI` 是直接继承自 `Starlette` 的类。

`FastAPI` 可以调用 Starlette 的所有功能。

第二步：创建 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)

如果用下面的代码创建应用：

my_awesome_api = FastAPI()

把代码存入 main.py，要以如下方式调用 uvicorn：

$ uvicorn main:my_awesome_api --reload

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

第三步：创建路径操作

路径

路径是指 URL 的第一个反斜杠（/）及它之后的内容。

下列 URL 中：

https://example.com/items/foo

……路径是：

/items/foo

!!! info "说明"

**路径**通常也叫作**端点**或**路由**。

开发 API 时，路径是分离 concerns 和 resources 的主要方式。

操作

操作是指 HTTP 方法。

常用方法如下：

• POST
• GET
• PUT
• DELETE

罕见方法如下：

• OPTIONS
• HEAD
• PATCH
• TRACE

HTTP 协议支持使用上述任何一种（或多种）方法与路径通信。

---

开发 API 时，通常要使用特定 HTTP 方法执行特定操作。

常用方法：

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

OpenAPI 把 HTTP 方法称为操作。

我们也称之为操作。

定义路径操作装饰器

@app.get("/")

@app.get("/") 告诉 FastAPI 下方函数以如下方式处理访问请求：

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

!!! info "@decorator 说明"

`@something` 语法是 Python **装饰器**。

就像一顶放在函数上面的装饰帽（估计这个术语的命名就是这么来的）。

装饰器接收下方函数，并用它执行一些操作。

本例中，这个装饰器告诉 **FastAPI** 下方函数对应的**路径**是 `/` 及 `get` **操作**。

这就是***路径操作装饰器***。

其它常用操作如下：

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

及罕见的操作：

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

!!! tip "提示"

您可以随意使用任何操作（HTTP方法）。

**FastAPI** 不向操作强制附加任何特定含义。

本章中的说明仅是指导，不是要求。

例如，使用 GraphQL 时，通常所有操作都只使用 `post` 一种方法。

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

路径操作函数由以下几部分组成：

• 路径： /
• 操作： get
• 函数：装饰器下方的函数（位于 @app.get("/") 下方）

async def root():

路径操作函数就是 Python 函数。

FastAPI 每次接收使用 GET 方法访问 URL/的请求时都会调用这个函数。

本例中的路径操作函数是异步函数（async）。

---

也可以不使用 async def，把路径操作函数定义为普通函数：

def root():

!!! note "笔记"

如果不清楚普通函数与异步函数的区别，请参阅异步：***等不及了？***一节中的内容。

第五步：返回内容

return {"message": "Hello World"}

路径操作函数可以返回字典、列表，以及字符串、整数等单值。

还可以返回 Pydantic 模型（稍后介绍）。

还有很多能自动转换为 JSON 的对象与模型（比如 ORM 等）。您可以尝试使用最喜欢的对象，FastAPI 很可能已经为其提供支持了。

小结

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