FastAPI官档精编005 - 第一步
共 7356字，需浏览 15分钟
·
2021-09-20 08:41
呆鸟云：发布本系列旨在推广 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 文档：
备选 API 文档
跳转到 http://127.0.0.1:8000/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 方法。
常用方法如下：
POSTGETPUTDELETE
罕见方法如下：
OPTIONSHEADPATCHTRACE
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）