FastAPI 教學

教程 - 用户指南 - 简介¶

本教程将一步步向你展示如何使用 FastAPI 的绝大部分特性。

各个章节的内容循序渐进，但是又围绕着单独的主题，所以你可以直接跳转到某个章节以解决你的特定需求。

本教程同样可以作为将来的参考手册。

你可以随时回到本教程并查阅你需要的内容。

运行代码¶

所有代码片段都可以复制后直接使用（它们实际上是经过测试的 Python 文件）。

要运行任何示例，请将代码复制到 main.py 文件中，然后使用以下命令启动 uvicorn：

$ uvicorn main:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<span style="color: green;">INFO</span>:     Started reloader process [28720]
<span style="color: green;">INFO</span>:     Started server process [28722]
<span style="color: green;">INFO</span>:     Waiting for application startup.
<span style="color: green;">INFO</span>:     Application startup complete.

强烈建议你在本地编写或复制代码，对其进行编辑并运行。

在编辑器中使用 FastAPI 会真正地展现出它的优势：只需要编写很少的代码，所有的类型检查，代码补全等等。

安装 FastAPI¶

第一个步骤是安装 FastAPI。

为了使用本教程，你可能需要安装所有的可选依赖及对应功能：

$ pip install "fastapi[all]"

---> 100%

......以上安装还包括了 uvicorn，你可以将其用作运行代码的服务器。

Note

你也可以分开来安装。

假如你想将应用程序部署到生产环境，你可能要执行以下操作：

并且安装uvicorn来作为服务器：

pip install "uvicorn[standard]"

然后对你想使用的每个可选依赖项也执行相同的操作。

进阶用户指南¶

在本教程-用户指南之后，你可以阅读进阶用户指南。

进阶用户指南以本教程为基础，使用相同的概念，并教授一些额外的特性。

但是你应该先阅读教程-用户指南（即你现在正在阅读的内容）。

教程经过精心设计，使你可以仅通过教程-用户指南来开发一个完整的应用程序，然后根据你的需要，使用进阶用户指南中的一些其他概念，以不同的方式来扩展它。

• TL;DR
• Requirements & Installation
• 撰寫第一支API
• 基本結構
• 啟動服務
• 型態提示(Typing Hints)
  • 1. FastAPI 在收到請求時，會自動檢查參數的格式是否符合條件
  • 2. 自動轉換文件

TL;DR

FastAPI是近期受到矚目的網頁框架，與Python常用的框架 Flask 、 Django 相同，可以用來建立 API 及網頁服務， 用以下幾點來概括FastAPI的特色：

• 快速： 如同它的名字，執行速度相當快速，是當前最快的Python框架
• 直覺： FastAPI 使用 OpenAPI 的開源標準，所以在開發時，能夠套用 auto complete
• 自動產生文件: API撰寫完成後，FastAPI會自動產生對應的文件。
• 簡單: 語法上與 Flask 相差不大，轉換陣痛並不高。

Requirements & Installation

• Python 環境 : Python 3.6 +

• 基本套件: (bash script)

  pip install fastapi # FastAPI
  pip install uvicorn[standard] # ASGI Server
  

基本結構

與 Flask 的 run.py 類似， 可以將所有程式碼放在 main.py 中，快速建立第一個 FastAPI。

在語法結構上，與Flask大同小異，,也是透過 @app 裝飾子來定義API路徑。

不過FastAPI在定義路徑時，會透過裝飾子一併定義API可提供的HTTP Method:

• @app.post() : Post 方法
• @app.get() : Get 方法
• @app.put() : Put 方法
• @app.delete() : Delete 方法

了解裝飾子的概念後，參考官方文件的範例，在main.py中輸入:

from typing import Optional

from fastapi import FastAPI

app = FastAPI() # 建立一個 Fast API application

@app.get("/") # 指定 api 路徑 (get方法)
def read_root():
    return {"Hello": "World"}


@app.get("/users/{user_id}") # 指定 api 路徑 (get方法)
def read_user(user_id: int, q: Optional[str] = None):
    return {"user_id": user_id, "q": q}

啟動服務

與 Flask 不同的是，如果直接執行此 main.py 不會啟動服務。

需要透過 ASGI Server gvicorn 來啟用：

(bash script)
uvicorn main:app --reload
# uvicorn <檔名>:<app名稱>
# --reload 在專案更新時，自動重新載入，類似Flask的debug模式

啟用後在瀏覽器輸入 127.0.0.1:8000/users/8?q=minglunwu，將會得到如下的回傳結果:

{"user_id":8,"q":"minglunwu"}

當我們鍵入 127.0.0.1:8000/users/8?q=minglunwu時， FastAPI會在定義好的裝飾子中，尋找符合路徑前綴: /users 的 function，也就是 read_user()。 這部分的機制與Flask相當類似。

FastAPI 與 Flask不同的地方在於：

FastAPI 在建立API時，需要以 型態提示 (Typing Hints) 來定義參數的型態

型態提示(Typing Hints)

舉例來說： 在上圖的 read_user() 中，我們定義了以下的格式：

@app.get("/users/{user_id}") # 指定 api 路徑 (get方法)
def read_user(user_id: int, q: Optional[str] = None):
    return {"user_id": user_id, "q": q}

在定義function的參數時，使用Python內建的型態檢查語法，指定各參數的型態，以上圖的Function來看，我們分別設定了下列的參數及型態:

• user_id: int格式
• q: str格式（Optional)

使用 Typing Hint 有兩項優點：

1. FastAPI 在收到請求時，會自動檢查參數的格式是否符合條件

當FastAPI收到 Request時，會先檢查URL，尋找符合 @app 所定義的路徑規則。

在解析 Request 所攜帶的參數時，將比對定義的變數型態，如果有不符合的，將會回傳錯誤訊息，舉例來說：

如果我們嘗試在瀏覽器中輸入 不符合規則的URL:

127.0.0.1:8000/users/error_type?q=minglunwu

(將原本的整數 8 換成字串 error_type)

此時因為收到的參數 error_type?q=minglunwu 因為參數 error_type 並不符合預先定義好的參數型態: int，此次Request無效。

不像 Flask 會回傳驚心動魄的錯誤訊息， FastAPI 會自動將錯誤訊息轉換成下列「有用」且「清楚」的錯誤訊息後，進行回傳:

{"detail":[{"loc":["path","user_id"],"msg":"value is not a valid integer","type":"type_error.integer"}]}

2. 自動轉換文件

FastAPI 的另一項特色在於:

自動生成 API 文件

完成了第一支 API 後，在瀏覽器輸入: http://127.0.0.1:8000/docs:

可以看到在畫面中，除了API的名稱外，參數的型態及Response的結果都包含在自動產生的文件中！

除了方便使用者閱讀外，這些文件也有提供即時互動功能，能夠即時測試:

撰寫API是一件費力耗神的工作，我曾傻傻地使用 Markdown 手刻文件，大概寫到十來個函式時就崩潰放棄 Orz

後來嘗試使用 Sphinx 工具，能直接將註解轉換為文件，不過在使用時還需要再多進行一次轉換，稍嫌麻煩。

個人蠻喜歡FastAPI 內建的轉換功能，在撰寫好API的同時就自動產生完整的文件。

前往下集:

Fast API 入門筆記 (二) - Typing Hint & Async

Post Tags Fast API