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

变量 appFastAPI类实例

该实例是创建所有 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 时,路径是分离 concernsresources 的主要方式。

操作

操作是指 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

你可能感兴趣的:(FastAPI官档精编005 - 第一步)