FastAPI官档精编001 - 简介

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

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

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

下面先列出几个需要 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

以下为正文。


文档: https://fastapi.tiangolo.com
源码: https://github.com/tiangolo/fastapi


FastAPI 是快速构建高效 API 的现代 Web 框架,它使用的是 Python 3.6+,并基于 Python 标准类型提示。

核心特性:

  • 速度快:可与 NodeJSGo 比肩的极高性能(归功于 Starlette 和 Pydantic),是最快的 Python 网络框架之一
  • 开发快:开发速度提高约 200% 至 300%
  • Bug 少:人为错误减少约 40%*
  • 智能:强大的编辑器支持,处处皆可自动补全,减少调试时间
  • 简单:易学、易用,阅读文档所需时间更短
  • 简短:代码重复最小化,通过不同的参数声明实现丰富功能,Bug 更少
  • 健壮:生产级别的代码,还有自动交互文档
  • 标准:完全兼容并基于 API 开放标准:OpenAPI 和 JSON Schema

依赖项支持

  • Python 3.6 及更高版本
  • Starlette 网络
  • Pydantic 数据验证

安装

$ pip install fastapi

FastAPI 还需要 ASGI 服务器,生产环境下可以使用 Uvicorn 或 Hypercorn。

$ pip install uvicorn[standard]

示例

创建应用

  • 创建 main.py,写入以下内容:
from typing import Optional

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}

如果代码中使用了 async / await,请配套使用 async def

from typing import Optional

from fastapi import FastAPI

app = FastAPI()


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


@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}

运行

执行以下命令运行服务器:

$ 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.

uvicorn main:app 命令含义如下:

  • mainmain.py( Python 模块
  • appmain.py 中通过 app = FastAPI() 创建的对象
  • --reload:代码更新后,重启服务器。仅在开发时使用

查看文档

使用浏览器访问 http://127.0.0.1:8000/items/5?q=somequery。

可以获得如下 JSON 响应:

{"item_id": 5, "q": "somequery"}

至此,我们就创建了具有以下功能的 API:

  • 通过路径 //items/{item_id} 接收 HTTP 请求
  • 这两个路径都能接收 GET 操作(也叫作 HTTP 方法
  • /items/{item_id} 包含类型为 int路径参数 item_id
  • /items/{item_id} 还包含类型为 str 的可选查询参数 q

API 文档

访问 http://127.0.0.1:8000/docs。

查看(由Swagger UI)自动生成的 API 文档:

Swagger UI

备选 API 文档

访问 http://127.0.0.1:8000/redoc。

查看(由 ReDoc)自动生成的 API 文档:

ReDoc

更新示例

修改 main.py,从 PUT 请求中接收请求体。

借助 Pydantic 使用 Python 标准类型声明请求体。

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    is_offer: Optional[bool] = None


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}


@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_name": item.name, "item_id": item_id}

(因为之前为 uvicorn 命令添加了 --reload 选项),服务器会自动重载。

更新 API 文档

访问 http://127.0.0.1:8000/docs。

  • 自动更新 API 文档,加入新的请求体:
Swagger UI
  • 点击「Try it out」按钮,填写参数,直接调用 API:
Swagger UI interaction
  • 然后,点击「Execute」按钮,用户界面和 API 通信,发送参数,获取结果,并在屏幕上显示:
Swagger UI interaction

更新备选文档

访问 http://127.0.0.1:8000/redoc。

  • 备选文档也会显示新加入的请求参数和请求体:
ReDoc

小结

总的来说,和声明函数的参数一样,只需声明一次参数类型和请求体。

在此,使用了现代 Python 的标准类型进行声明。

开发者不用学习新语法,也不用了解特定库的方法或类。

只要使用标准的 Python 3.6 及更高版本

举个例子,比如,声明 int 类型:

item_id: int

或者使用更复杂的 Item 模型:

item: Item

......只需一次声明,就可以获得以下好处:

  • 编辑器支持,包括:
    • 自动补全
    • 类型检查
  • 数据校验:
    • 在校验失败时自动生成清晰的错误信息
    • 对多层嵌套的 JSON 对象依然执行校验
  • 转换输入数据:转换为 Python 数据与类型。可以从以下对象中读取:
    • JSON
    • 路径参数
    • 查询参数
    • Cookies
    • 请求头
    • 表单
    • 文件
  • 转换输出数据:把 Python 数据类型转换为供网络传输的( JSON )数据:
    • Python 基础类型 (strintfloatboollist 等)
    • datetime 对象
    • UUID 对象
    • 数据库模型
    • ......及更多其它类型
  • 自动生成 API 文档,包括两种用户界面:
    • Swagger UI
    • ReDoc

回顾本章的代码示例,FastAPI 可以:

  • 校验 GETPUT 请求的路径中是否含有 item_id
  • 校验 GETPUT 请求中的 item_id 是否为 int 类型
    • 如果不是 int 类型,客户端返回错误信息
  • 检查 GET 请求中是否包含可选查询参数 q(比如 http://127.0.0.1:8000/items/foo?q=somequery
    • q 声明为 = None,所以是可选的
    • 没有 Noneq 就是必选的(如 PUT 例子中的请求体)
  • 对于访问 /items/{item_id}PUT 请求,把请求体读取为 JSON,并且:
    • 检查是否包含必选属性 name,并且值的类型为 str
    • 检查是否包含必选属性 price,并且值的类型为 float
    • 检查是否包含可选属性 is_offer, 如果包含,值的类型应为 bool
    • 以上过程也适用于多层嵌套的 JSON 对象
  • 自动转换 JSON
  • 通过 OpenAPI 文档存档所有内容,可被用于:
    • API 文档
    • 其它编程语言的客户端代码自动生成系统
  • 直接提供两种 API 文档

虽然本篇的介绍比较浅,但涵盖了 FastAPI 的所有工作原理。

试着把下面这行代码:

    return {"item_name": item.name, "item_id": item_id}

......从:

        ... "item_name": item.name ...

......改为:

        ... "item_price": item.price ...

......注意,编辑器可以自动补全属性,还能识别属性的类型:

editor support

可选依赖支持库

用于 Pydantic:

  • ujson - 更快的 JSON 解析
  • email_validator - 用于 email 校验

用于 Starlette:

  • requests - 使用 TestClient 时安装
  • aiofiles - 使用 FileResponseStaticFiles 时安装
  • jinja2 - 使用默认模板配置时安装
  • python-multipart - 通过 request.form() 解析表单时安装
  • itsdangerous - 需要 SessionMiddleware 支持时安装
  • pyyaml - 使用 Starlette 的 SchemaGenerator 时安装(FastAPI 可能不需要此支持库)
  • graphene - 需要 GraphQLApp 支持时安装
  • ujson - 使用 UJSONResponse 时安装

用于 FastAPI / Starlette:

  • uvicorn - 用于加载和运行应用的服务器
  • orjson - 使用 ORJSONResponse 时安装

使用 pip install fastapi[all] 可安装上述所有依赖支持库。

许可协议

FastAPI 遵循 MIT 许可协议。

你可能感兴趣的:(FastAPI官档精编001 - 简介)