近日只是為了想盡辦法為 Flask 實現 Swagger UI 文檔功能，基本上要讓 Flask 配合 Flasgger, 所以寫了篇 Flask 應用集成 Swagger UI 。然而不斷的 google 過程中偶然間發現了 FastAPI 這么一款集成了 Swagger UI 的更新的 Python/ target=_blank class=infotextkey>Python Web 框架。起初想要在標題中表達的意思大概是 Flask + Swagger = FastAPI, 后來發現 FastAPI 的閃亮點不僅如此，順便找了些 Flask 與 FastAPI 對比的文章來，在文后附有鏈接。

本文不對 Flask 與 FastAPI 的各個方面對進行對比，本人興趣依然還在 FastAPI 的 Swagger UI 功能，以及與 Flask 的 Blueprint 類似的特性。如果要拿 Flask 與 FastAPI 比較的話，應該用 Flask 2.x, 因為它開始支持類似 @App.get 的裝飾器，并引入了 async 路由函數。

Flask 是在 2010 年發布的，它構建于 WSGI(Python Web Server Gateway Interface) 之上的，產品環境中運行需與 uWSGI, Gunicorn 搭配，或用 mod_wsgi 模塊與 Apache 集成。因發布較早，所以目前應該有較多的使用者。Flask 2.0 需要 Python 3.6+ 的支持，如果支持 async , 需 Python 3.7+

FastAPI 發布于 2018 年，構建于 ASGI(Asynchronous Server Gateway Interface) 之上，在 IO 密集型的應用中有更優越的性能。生成環境中配合 ASGI 服務器，如 Uvicorn 或 Hypercorn . FastAPI 最為亮麗的特性是集成了 Swagger UI -- 外加一個福利 ReDoc 。FastAPI 需 Python 3.6+ 版本。

畢竟是在開始學一個新的框架，還是從它的基本用法開始，途中會穿插與 Flask 的對比。

FastAPI 的基本用法

安裝:

 $ pip install fastapi  $ pip install "uvicorn[standard]"

當前安裝的 fastapi 版本為 0.70.1, uvicorn 版本為 0.16.0。開始第一個例子，摘自官方

創建一個 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}

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 關鍵字

啟動服務，用命令

 $  uvicorn main:app --reload  INFO: Will watch for changes in these directories: ['/Users/yanbin/demo/first-fastapi']  INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)  INFO: Started reloader process [81730] using watchgod  INFO: Started server process [81732]  INFO: Waiting for application startup.  INFO: Application startup complete.

注： uvicorn --help 列出詳細幫助，如啟動多少個 worker, 綁定網絡接口和端口號, 配置 SSL 證書等。

訪問服務

 $ curl -i http://localhost:8000/  HTTP/1.1 200 OK  date: Mon, 20 Dec 2021 06:51:24 GMT  server: uvicorn  content-length: 17  content-type: application/json  {"Hello":"World"}

另一個服務就是
http://localhost:8000/items/100?q=somequery

與 Flask 的對比

Flask 對返回的 dict 類型會自動應用 jsonify(), 并且響應的 Content-Type 為 application/json; 如果返回的是字符串，響應 Content-Type 為 text/html, 除非顯式的調用 jsonify() 函數。FastAPI 都會生成 application/json 的響應，Flask 對返回的 tuple 類型還有更多的約定, 見 Flask About Response
Flask 對路徑中的參數可選擇中 @app.xxx 裝飾器中聲明類型，如 app.get("/items/<int:item_id>"
Flask 訪問查詢參數用 request.args.get('key') 的方式
啟動服務的方式不同，下面單獨列出

回顧一個 Flask 啟動服務的方式有

 $ export FLASK_APP=hello  $ flask run

如果程序文件名為 app.py 或 wsgi.py 的話，可以省略 FLASK_APP 環境變量，直接執行 flask run 就行。另一種方式就是在代碼中加上 main 入口

if __name__ == "__main__":
    app.run()

if __name__ == "__main__" :

app . run ( )

然后像普通 Python 代碼一樣執行

 $ python main.py

對于 FastAPI, 如果總是要用 uvicorn 來啟動服務的話，在 IDE 中調用就變得不那么便利。由于 uvicorn 本身就是 Python 實現，當然也就可以把命令過程寫到 Python 代碼中

from fastapi import FastAPI
import uvicorn

app = FastAPI()

if __name__ == "__main__":
    uvicorn.run(app)

from fastapi import FastAPI

import uvicorn

app = FastAPI ( )

if __name__ == "__main__" :

uvicorn . run ( app )

注：uvicorn.run() 可接受更多的參數，相當于 uvicorn --help 可接受的。

同樣把 main.py 當作普通 Python 程序來啟動即可

 $ python main.py

FastAPI 自動產生的 Web 文檔

前面講過，FastAPI 進入我的視野最首要的一個原因就是它集成了 Swagger UI, 在啟動了 FastAPI 服務后，只要訪問
http://localhost:8000/docs, 熟悉的 Swagger UI 即刻映入眼簾

同時注意到函數映射為 API 的名稱，由于參數是帶有類型提示的，所以在 SwaggerUI 中也能看到相應的類型。其他定制 Swagger UI 的工作需要時可細細研究。

FastAPI 除了 SwaggerUI 外，還同時給了我們另一個選擇，那就是 redoc, 訪問
http://localhost:8000/redoc, 看到下面的界面

我也是頭一回從 FastAPI 這里了解到還有一個 Redoc 的 Web API 文檔工具，它和 SwaggerUI 類似，都是支持 Open API。

API Spec 中包含請求/響應的 Model

使用 FastAPI 時，在 API 文檔中產生請求/響應的 Model 類型也很簡單，下面的例子同時包含自定義的輸入輸出類型

下面是 main.py 的全新內容

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

class Msg(BaseModel):
    item_id: int
    item_name: str

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

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

class Msg ( BaseModel ) :

item_id : int

item_name : str

@ app . put ( "/items/{item_id}" , response_model = Msg )

def update_item ( item_id : int , item : Item ) :

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

再查看
http://localhost:8000/docs 文檔，看到 PUT /items/{item_id} 的界面如下

我們能看到請求與響應中的 Example Value 和 Schema 定義

梳理完 FastAPI 的自動 API 文檔功能，進入下一個話題

FastAPI 的多文件支持

FastAPI 類似于 Flask 的 Blueprints 功能沒有一個特定的名稱，只籠統的給出解決方案 Bigger Applications - Multiple Files . 我們來看一下它是怎么實現的。這里簡化官方的例子，排除了 dependencies 的應用，要用到的目錄結構為

app
├── internal
│   └── admin.py
├── main.py
└── routers
    ├── items.py
    └── users.py

app

├── internal

│ └── admin . py

├── main . py

└── routers

├── items . py

└── users . py

每個目錄中都可以放一個 __init__.py 文件，標識為包，接著是每個文件的內容

app/internal/admin.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/")
def admin():
    return "admin"

from fastapi import APIRouter

router = APIRouter ( )

@ router . get ( "/" )

def admin ( ) :

return "admin"

app/routers/items.py

from fastapi import APIRouter

router = APIRouter(prefix="/items", tags=["tag_items"])

@router.get("/")
async def read_items():
    return {"__all__"}


@router.delete("/{item_id}")
def delete_item(item_id: int):
    return {"action": "delete", "item_id": item_id}

from fastapi import APIRouter

router = APIRouter ( prefix = "/items" , tags = [ "tag_items" ] )

@ router . get ( "/" )

async def read_items ( ) :

return { "__all__" }

@ router . delete ( "/{item_id}" )

def delete_item ( item_id : int ) :

return { "action" : "delete" , "item_id" : item_id }

app/routers/users.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/users/{username}", tags=["users"])
def read_user(username: str):
    return {"username": username}

@router.post("/users/{username}", tags=["users"])
async def add_user(username: str):
    return {"action": "add", "username": username, "userid": "new_id"}

from fastapi import APIRouter

router = APIRouter ( )

@ router . get ( "/users/{username}" , tags = [ "users" ] )

def read_user ( username : str ) :

return { "username" : username }

@ router . post ( "/users/{username}" , tags = [ "users" ] )

async def add_user ( username : str ) :

return { "action" : "add" , "username" : username , "userid" : "new_id" }

在每個單獨定義路由的文件里用到的是 APIRouter , 它相當是一個迷你的 FastAPI , 也類似于 Flask 的 Blueprint . 上面分別演示了兩種 APIRouter 的聲明方式，聲明時帶不帶 prefix 和 tags。同時在為函數定義路由時也可指定 tags，在后面我們將會注意到 tags 只是為 API 文檔分類用的。

app/main.py

from fastapi import FastAPI
from .internal import admin
from .routers import users, items

app = FastAPI()

app.include_router(users.router)
app.include_router(items.router)
app.include_router(admin.router, prefix="/admin", tags=["admin"])

@app.get("/")
def index():
    return "index"

from fastapi import FastAPI

from . internal import admin

from . routers import users , items

app = FastAPI ( )

app . include_router ( users . router )

app . include_router ( items . router )

app . include_router ( admin . router , prefix = "/admin" , tags = [ "admin" ] )

@ app . get ( "/" )

def index ( ) :

return "index"

這里實際上使用了三種定義路徑前綴與 tags(API 分類) 的方式