這段時間一直在做flask遷移到fastapi的工作,基於現在的Flask項目使用到的功能實現了一套腳手架項目,項目集成了sqlalchemy2(1.4+)、JWT Auth、websocket、i18n等常用功能,目錄結構也比較簡單,也封裝了一系列的web開發過程中會用到的工具,歡迎大家給項目提提建議。
https://github.com/goofy-z/fastapi-web-template
目錄結構
.
├── app # 業務應用目錄,下屬多個應用模塊
│ ├── __init__.py
│ ├── demo # 應用模塊demo
│ │ ├── apis.py # 路由定義
│ │ ├── demo.py # 模塊工具方法定義
│ │ ├── models.py # ORM model類定義
│ │ ├── schema.py # 序列化類定義
│ │ └── views.py # 視圖函數定義
│ └── ws # websocket模塊
├── core # 項目核心
│ ├── config # 項目配置文件
│ ├── dependencies # fastapi依賴定義
│ ├── i18n # 國際化翻譯
│ ├── manager # manager工具
│ ├── middleware # ASGI中間件定義
│ ├── schema # 基礎schema
│ ├── storage # SQLA相關
│ └── utils # 工具目錄
├── docs # 項目文檔
├── main.py # 入口文件
├── manage.py # manager工具
├── Dockerfile # 就是一個DOckerfile
├── README.md
└── requirements.txt # 依賴文件
主要功能模塊
1. SQLAlchemy
1.4+
的版本,這個版本支持異步IO,但是相應的得使用異步的數據庫適配器,這里使用的是aiomysql
, 同時1.4版本已經支持SQLA的2.0寫法,當然也是兼容舊版寫法的。兩者區別具體查看文檔
與SQLA相關的代碼在/core/storage
下:
model.py
: 定義了ORM表結構映射基礎對象Base
, 集成它來關聯db中的表。db.py
: 初始化SQLA,添加一些監聽事件。
應用代碼中引入session
可以直接從全局對象g
中獲取:
from core.middleware import g
g.db.execute(...)
獲取engine
對象
from core.storage import db
db.engine.execute(...)
邏輯刪除,orm對象
obj.delete()
2.dependencies
項目下所有的fastapi依賴注入函數都在/core/dependencies
:
- base_dependen: 基礎依賴注入,所有的AP都需要引入這個依賴,用於提取請求頭中的
Accept-Language
來設置全局變量local
, 用於i18n
的翻譯。 - auth_dependen: 基於
Authorization
請求頭的JWT認證。
3. config
項目的配置文件目錄,分為兩種環境配置文件dev
和prod
。啟動項目時引入哪個配置文件取決於環境變量配置CONFIG_NAME
,默認是dev
。
已有配置:
- CONFIG_NAME: 引入配置文件類型
- SERVICE_NAME:項目名稱
- TZ:時區
- TOKEN_SECRET_KEY:JWT密鑰
- DATABASE_MYSQL_URL:數據庫DSN
- SHOW_SQL:是否打開SQLA日志
- RETURN_SQL:是否在接口返回SQL記錄
- DB_POOL_RECYCLE:數據庫連接釋放事件
- DB_MAX_OVERFLOW:連接池緩沖個數
- DB_POOL_SIZE: 連接池大小
4. schema
項目的序列化和反序列化是基於pydantic實現的,業務應用需要繼承BaseSchema
來擴展各自需要的序列化器。提供兩種序列化器:
- DataSchema: 普通序列化器
- PageSchema: 分頁序列化器
還提供了數據分頁器:paginate_handler
,可以接收select
對象或迭代對象,返回分頁后的數據字典。
5. i18n
創建翻譯文件在后面的manager.py
里會有介紹,如果是已有的翻譯文件直接放入/core/i18n/lang
里。同時,項目里需要使用翻譯的地方可以如下使用,具體翻譯成何種語言取決於全局變量g.locale
from core.i18n import gettext
t = gettext("test") # t為翻譯后的內容
6. manager.py
項目下有一個類似django
的項目管理工具,現在提供了兩個命令:
-
startapp [appname]
在
/app
下創建一個標准的應用目錄,且實現了一套增刪改查的代碼 -
babel [add|run]
add: 檢測代碼中的引入了
gettext
的地方,並更新翻譯文件message.po
, 之后需要手動填入翻譯內容。run: 編譯message.po。
7. middleware
項目下的/core/middleware
是所有的ASGI的中間件,目前共有兩個中間件
fastapi-globals.py
:g
對象的實現,基於contextvarsession.py
: 注冊全局session
8.websocket
項目自帶了websocket應用,實現了ws連接管理類ConnectionManager
。目前是將連接信息存儲在內存中,第一次連接時需要進行token驗證,之后服務端會定時進行心跳檢測,所以需要客戶端隔一段時間就發送心跳包,否則服務端會主動斷開連接。
token驗證格式:
{
"Op": "bind",
"SessionID": "token"
}
心跳檢測包:
{
"Op": "heartbeat",
"SessionID": "token"
}
9.部署
下載依賴:pip3 install -r quirements.txt
啟動項目:python main.py