FastAPI 教程

教程说明:


FastAPI 框架,高性能,易于学习,高效编码,生产可用


文档: https://fastapi.tiangolo.com

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


FastAPI 是一个用于构建 API 的现代、快速(高性能)的 web 框架,使用 Python 3.6+ 并基于标准的 Python 类型提示。

关键特性:

  • 快速:可与 NodeJS 和 Go 比肩的极高性能(归功于 Starlette 和 Pydantic)。最快的 Python web 框架之一。

  • 高效编码:提高功能开发速度约 200% 至 300%。*

  • 更少 bug:减少约 40% 的人为(开发者)导致错误。*
  • 智能:极佳的编辑器支持。处处皆可自动补全,减少调试时间。
  • 简单:设计的易于使用和学习,阅读文档的时间更短。
  • 简短:使代码重复最小化。通过不同的参数声明实现丰富功能。bug 更少。
  • 健壮:生产可用级别的代码。还有自动生成的交互式文档。
  • 标准化:基于(并完全兼容)API 的相关开放标准:OpenAPI (以前被称为 Swagger) 和 JSON Schema

* 根据对某个构建线上应用的内部开发团队所进行的测试估算得出。


Typer,命令行中的 FastAPI


如果你正在开发一个在终端中运行的命令行应用而不是 web API,不妨试下 Typer

Typer 是 FastAPI 的小同胞。它想要成为命令行中的 FastAPI。 

依赖

Python 3.6 及更高版本

FastAPI 站在以下巨人的肩膀之上:

安装

在命令提示符(macOS或者Linux的终端)中使用pip安装FastAPI:

pip install fastapi
████████████████████████████████████████ 100%

安装完FastAPI后还需要一个 ASGI 服务器来运行相应的代码,生产环境可以使用 Uvicorn 或者 Hypercorn

安装方法也是在命令提示符中使用pip进行安装:

pip install uvicorn
████████████████████████████████████████ 100%

示例

创建

  • 创建一个 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 def...

如果你的代码里会出现 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}

如果你不知道是否会用到,可以查看文档的 并发和异步/等待 章节中 关于 async 和 await 的部分。

运行

通过以下命令运行服务器:

uvicorn main:app --reload
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.

 注意:当8000端口被占用时,使用该指令会报错:[WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试。这是由于8000端口被占用导致的,可以通过更改启动的端口或者kill使用8000端口的应用来解决:

  1. kill应用的方式:在Windows环境下使用netstat -aon|findstr "8000"查看占用8000端口的应用的PID,然后在任务管理器中找到对应应用结束。
  2. 改变启动端口方式(更通用):在启动命令后加--port来改变启动端口,例如 uvicorn main:app --reload --port 18080

关于uvicorn main:app --reload --port 18080命令

uvicorn main:app命令含义如下:

  • main:main.py文件(一个 Python "模块")。
  • app:在 main.py 文件中通过 app = FastAPI() 创建的对象。
  • --reload让服务器在更新代码后重新启动。仅在开发时使用该选项。
  • --port:指定启动的端口,该代码中指定了18080端口。

检查

使用浏览器访问 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} 路径 有一个 路径参数 item_id 并且应该为 int 类型。
  • /items/{item_id} 路径 有一个可选的 str 类型的 查询参数 q。

交互式 API 文档

现在访问 http://127.0.0.1:8000/docs

你会看到自动生成的交互式 API 文档(由 Swagger UI生成):


可选的 API 文档

访问 http://127.0.0.1:8000/redoc

你会看到另一个自动生成的文档(由 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 文档将会自动更新,并加入新的请求体:


  • 点击「Try it out」按钮,之后你可以填写参数并直接调用 API:


  • 然后点击「Execute」按钮,用户界面将会和 API 进行通信,发送参数,获取结果并在屏幕上展示:


可选文档升级

访问 http://127.0.0.1:8000/redoc

  • 可选文档同样会体现新加入的请求参数和请求体:


总结

总的来说,你就像声明函数的参数类型一样只声明了一次请求参数、请求体等的类型。

你使用了标准的现代 Python 类型来完成声明。

你不需要去学习新的语法、了解特定库的方法或类,等等。

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

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

item_id: int

或者一个更复杂的 Item 模型:

item: Item

......在进行一次声明之后,你将获得:

编辑器支持,包括:

  • 自动补全 
  • 类型检查

数据校验:

  • 在校验失败时自动生成清晰的错误信息。
  • 对多层嵌套的 JSON 对象依然执行校验

转换 来自网络请求的输入数据为 Python 数据类型。包括以下数据:

  • JSON
  • 路径参数
  • 查询参数
  • Cookies
  • 请求头
  • 表单文件

转换输出的数据:转换 Python 数据类型为供网络传输的 JSON 数据:

  • 转换 Python 基础类型 (str、 int、 float、 bool、 list 等)
  • datetime 对象
  • UUID 对象
  • 数据库模型
  • .....以及更多其他类型

自动生成的交互式 API 文档,包括两种可选的用户界面:

  • Swagger UI
  • ReDoc

    回到前面的代码示例,FastAPI 将会:

    • 校验 GET  PUT 请求的路径中是否含有 item_id
    • 校验 GET  PUT 请求中的 item_id 是否为 int 类型。
      • 如果不是,客户端将会收到清晰有用的错误信息。
    • 检查 GET 请求中是否有命名为 q 的可选查询参数(比如 http://127.0.0.1:8000/items/foo?q=somequery)。
      • 因为 q 被声明为 = None,所以它是可选的。
      • 如果没有 None 它将会是必需的 (如 PUT 例子中的请求体)。
    • 对于访问 /items/{item_id} 的 PUT 请求,将请求体读取为 JSON ,同时:
      • 检查是否有必需属性 name 并且值为 str 类型 。
      • 检查是否有必需属性 price 并且值为 float 类型。
      • 检查是否有可选属性 is_offer, 如果有的话值应该为 bool 类型。
      • 以上过程对于多层嵌套的 JSON 对象同样也会执行
    • 自动对 JSON 进行转换或转换成 JSON。
    • 通过 OpenAPI 文档来记录所有内容,可被用于:
      • 交互式文档系统
      • 许多编程语言的客户端代码自动生成系统
    • 直接提供 2 种交互式文档 web 界面。

    虽然我们才刚刚开始,但其实你已经了解了这一切是如何工作的。

    尝试更改下面这行代码:

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

    ......从:

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

    ......改为:

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

    ......注意观察编辑器是如何自动补全属性并且还知道它们的类型:


    教程 - 用户指南 中有包含更多特性的更完整示例。

    剧透警告: 教程 - 用户指南中的内容有:

    • 对来自不同地方的参数进行声明,如:请求头、cookies、form 表单以及上传的文件。
    • 如何设置校验约束如 maximum_length 或者 regex。
    • 一个强大并易于使用的 依赖注入 系统。
    • 安全性和身份验证,包括通过 JWT 令牌和 HTTP 基本身份认证来支持 OAuth2。
    • 更进阶(但同样简单)的技巧来声明 多层嵌套 JSON 模型 (借助 Pydantic)。
    • 许多额外功能(归功于 Starlette)比如:
      • WebSockets
      • GraphQL
      • 基于 requests 和 pytest 的极其简单的测试
      • CORS
      • Cookie Sessions
      • ......以及更多

    性能

    独立机构 TechEmpower 所作的基准测试结果显示,基于 Uvicorn 运行的 FastAPI 程序是 最快的 Python web 框架之一,仅次于 Starlette 和 Uvicorn 本身(FastAPI 内部使用了它们)。(*)

    想了解更多,请查阅 基准测试 章节。

    可选依赖

    用于 Pydantic:

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

    用于 Starlette:

    • requests - 使用 TestClient 时安装。
    • aiofiles - 使用 FileResponse 或 StaticFiles 时安装。
    • jinja2 - 使用默认模板配置时安装。
    • python-multipart - 需要通过 request.form() 对表单进行「解析」时安装。
    • itsdangerous - 需要 SessionMiddleware 支持时安装。
    • pyyaml - 使用 Starlette 提供的 SchemaGenerator 时安装(有 FastAPI 你可能并不需要它)。
    • graphene - 需要 GraphQLApp 支持时安装。
    • ujson - 使用 UJSONResponse 时安装。

    用于 FastAPI / Starlette:

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

    你可以通过 pip install fastapi[all] 命令来安装以上所有依赖。

    许可协议

    该项目遵循 MIT 许可协议。


    领取免费资料

    扫描下方二维码或打开微信搜一搜“w3cschool编程狮”关注公众号回复关键词【Python123】或者【Python资料包】免费领取 Python 学习资料,包含软件安装包,电子书、思维导图等


    温馨提示
    下载编程狮App,免费阅读超1000+编程语言教程
    取消
    确定
    目录

    FastAPI 用户指南

    关闭

    MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }