前記

在編寫項目時，都會對代碼質量有一定的追求， 比如代碼藝術、設計模式、 重構設計等等。但是一個良好 Python 項目除了程序員本身的代碼質量能力之外， 還有系統設計和代碼質量工具等等。不過由于每個系統的設計都會有一些不同， 系統設計需要程序員一定的經驗， 需要跟著項目去一起成長。

代碼質量工具可以都抽離出來，應用到每個項目中， 本文則是我對這些代碼質量工具的簡要使用總結。

0.提交代碼規范

每個團隊或個人， 都必須要有一套自己的分支管理和提交代碼規范， 對于分支管理， 一般會選用 git flow , 如果不太會使用， 前期可以使用git flow 備忘清單(https://danielkummer.github.io/git-flow-cheatsheet/index.zh_CN.html), 并且對于 master ,  develop 等分支設置一些權權限。另外提交的信息也要有對應的規范， 比如本次提交屬于哪種類型， 本次提交的功能是什么等等, 但是這個提交規范往往都沒有一個標準， 只要團隊和個人用的順心， 能通過這些規范來減少開發矛盾， 復盤代碼等等即可。我常使用的是：

git commit -m"<issue_id>:<file change>:<operating>:<info>" 

其中每個字段代表的含義如下：

• issue_id: 代表一個issue的id, 在準備寫功能或者修復一個bug時，都應該先提一個issue, 這個issue要詳細的寫明要修改什么，達到什么目的，然后再針對這個issue提交代碼

• file change: 代表文件的變化， 如增加， 刪除， 修改;也有人使用 +,-，* 來分別代表增加， 刪除， 修改

• operating: 代表本次代碼變化, 具體有如下幾種

  • feat：新功能

  • fix：修復bug

  • doc：文檔改變

  • style：代碼格式改變

  • refactor：某個已有功能重構

  • perf：性能優化

  • test：增加測試

  • build：改變了build工具 如 grunt換成了 npm

  • revert：撤銷上一次的commit

• info: 簡要的說明本次提交信息

1.項目環境管理-Poetry

一個項目最重要的就是跑起來， 而大家基本會同時在本地開發多個項目， 每個項目用到的環境都是不一樣的， 所以就需要用到虛擬環境隔離。在Python中提供了一個叫 venv 的虛擬環境管理包，他非常穩定， 同時功能也不是很多， 一般只用在服務器上， 對于本地開發來說， 都會想要更多的功能， 更加方便的對虛擬環境， 依賴包進行管理， Python包管理領域相關工具很多， 包括爭議很大的 Pipenv , 我在經過多種嘗試后， 覺得 Poetry 比較好用, 坑也比較少。

Poetry(https://python-poetry.org/)官網的簡介就是讓Python包安裝和依賴管理變得容易，  我覺得 Poetry 是最好用的, 他不止對包管理有很多的支持， 還有其他的拓展功能， 如方便的打包和發布， 腳本簡寫等等。

在第一次大多數的Python項目編寫中， 基本上都是按以下流程進行：

• 1.安裝對應的Python版本

• 2.通過 python -m venv <name> 的方式在項目創建venv的虛擬環境
• 3.在使用的過程中通過 python -m pip install <name> 的方式安裝依賴
• 4.在代碼編寫完畢后通過 python -m pip freeze > requirements.txt 生成依賴文件

而 Poetry 則十分簡單， 以下是 poetry 的創建流程：

1.1.創建項目

通過命令 poetry new 就可以創建一個項目手腳架

➜ poetry new example 
➜ tree 
. 
└── example 
    ├── example 
    │   └── __init__.py 
    ├── pyproject.toml 
    ├── README.rst 
    └── tests 
        ├── __init__.py 
        └── test_example.py 
 
3 directories, 5 files 

可以看到 Poetry 創建了一個 example 的項目， 生成了對應的文件夾以及包括項目信息的 pyproject.toml 。如果在已有項目， 則通過命令 poetry init 來初始化：

➜  example poetry init 
 
This command will guide you through creating your pyproject.toml config. 
# 交互bash， 通過該交互bash填寫項目信息。 
Package name [example]:  example 
Version [0.1.0]:  0.0.8 
Description []:  example project 
Author [so1n <qaz6803609@163.com>, n to skip]:  n 
License []:   
Compatible Python versions [^3.7]:   
 
Would you like to define your main dependencies interactively? (yes/no) [yes] no 
Would you like to define your development dependencies interactively? (yes/no) [yes] no 
Generated file 
# 填寫完項目信息后會生成以下內容， 之后會在剛才的路徑創建pyproject.toml文件， 并寫入。  
[tool.poetry] 
name = "example" 
version = "0.0.8" 
description = "example project" 
authors = ["Your Name <you@example.com>"] 
 
[tool.poetry.dependencies] 
python = "^3.7" 
 
[tool.poetry.dev-dependencies] 
 
[build-system] 
requires = ["poetry-core>=1.0.0"] 
build-backend = "poetry.core.masonry.api" 
 
 
Do you confirm generation? (yes/no) [yes] yes 

1.2.創建虛擬環境

Poetry 默認使用系統默認的Python環境， 不過可以通過 poetry env use <python version> 來指定Python版本， 之后就創建了一個虛擬環境了。默認的虛擬環境配置是存放在 /home/{user}/.cache/pypoetry 目錄的, 可以直接查看配置了解：

➜  poetry config --list 
# poetry使用的緩存目錄的路徑 
cache-dir = "/home/so1n/.cache/pypoetry" 
experimental.new-installer = true 
installer.parallel = true 
# 默認值為true，如果執行 poetry install/poetry add時沒有虛擬環境，就自動創建一個虛擬環境，設置為false的話，當虛擬環境不存在時，會將包安裝到系統環境 
virtualenvs.create = true 
# 默認值為false，設置為true的話，會在當前項目目錄下創建虛擬環境 
virtualenvs.in-project = false 
# 虛擬環境的路徑，默認路徑 {cache-dir}\virtualenvs 
virtualenvs.path = "{cache-dir}/virtualenvs"  # /home/so1n/.cache/pypoetry/virtualenvs 

而默認的使用習慣（包括一些第三方包） 都是認為venv是創建在項目路徑下的， 同時這也方便管理。 poetry 可以通過如下命令進行更改后再創建虛擬環境，達到在項目路徑下創建虛擬環境的效果：

# 更改配置 
➜ poetry config virtualenvs.in-project true  

在虛擬環境創建好后可以通過

➜ poetry run <commod>  

來執行想要運行的命令或者調用Python包， 也可以通過 poetry shell 啟動一個被虛擬環境包裹的交互shell.

1.3.安裝依賴

虛擬環境創建好后， 就可以安裝依賴了， 可以直接使用 poetry 的 add 命令安裝依賴， 其中帶有 --dev 表示他是開發環境依賴包(開發環境依賴包和生成環境依賴包區分是很有益的)：

➜ poetry add flask 
➜ poetry add pytest --dev  

安裝依賴后可以看到 pyproject.toml 文件發生變動：

... 
[tool.poetry.dependencies] 
python = "^3.7" 
Flask = "^1.1.2" 
 
[tool.poetry.dev-dependencies] 
pytest = "^6.2.4" 
... 

文件中多了剛剛安裝的 flask 依賴和 pytest 依賴， 且 pytest 依賴是屬于dev依賴。在后面還可以通過 poetry 的命令生成對應的生產環境依賴文件 requirement.txt 和測試環境依賴文件 requirements-dev.txt ：

# 生產環境 
poetry export -o requirements.txt --without-hashes --with-credentials 
# 測試環境 
poetry export -o requirements-dev.txt --without-hashes --with-credentials --dev 

這樣區分測試環境和生產環境的依賴可以盡量的減少測試需要的依賴包對生成環境造成影響。

除了增加依賴外， poetry 還支持很多種依賴操作方法， 具體如下：

# 查看依賴 
poetry show 
# 以樹形結構查看依賴 
poetry show -t 
# 更新所有鎖定版本的依賴 
poetry update 
# 更新指定的依賴 
poetry update flask 
# 刪除依賴 
poetry remove flask 

1.4.其他

對于一般的自用Python項目來說， 上面的 poetry 操作已經夠了， 如果需要發布自己的包到pypi, 或者安裝github最新的并未發布的包則可以使用他的其他拓展命令， 具體可以見文檔(https://python-poetry.org/docs/)。個人覺得 poetry 已經非常優秀了， 但是由于缺少一個穩定的維護團隊， 所以難免有bug, 這時候可以采用降級的方法解決， 比如安裝依賴失敗， 則可以使用 poetry run pip install 安裝包， 再手動補上 pyproject.yml 文件。

2.代碼質量工具

在大型的項目中， 一般都不追求花哨的代碼， 而是追求穩定， 容易理解， 復雜度低的代碼， 最完美的代碼應該是入行的人一看就能理解， 又能完美的解決需求。但是人無完人， 很多時候在寫代碼可能會出現一些小問題， 而這些小問題靠人來檢查是費時費力的， 同時又很難排查出來，這時就需要代碼檢查工具了。一般代碼檢查工具分為三類， 一類是檢查代碼風格， 并把不標準的代碼風格格式化為標準的代碼風格；另一類則是代碼邏輯檢查，他會檢查代碼邏輯， 代碼復雜度， 引用的包是否有問題等等, 最后一類是代碼安全檢查， 比如是否在代碼中引入密鑰， 或者像在 Python 代碼中寫 eval 函數等。

2.1.flake8

Flake8 是由Python官方發布的一款輔助檢測Python代碼是否規范的工具，相對于目前熱度比較高的 Pylint 來說， Flake8 檢查規則靈活，支持集成額外插件，擴展性強。 Flake8 是對下面三個工具的封裝：

• 1.PyFlakes：靜態檢查Python代碼邏輯錯誤的工具。

• 2.Pep8：靜態檢查PEP8編碼風格的工具。

• 3.NedBatchelder’s McCabe ：靜態分析Python代碼復雜度的工具。

Flake8 除了支持上面3種功能外， 還支持通過插件的方式引入其他功能， 比如使用 flake8-docstrings 強制要求編寫函數 docstring 等。

在項目中可以通過 poetry add flake8 --dev 引入flake8到dev依賴， 然后通過在根目錄增加 .flake8 文件：

[flake8] 
# 適當提高最大行長度 
max-line-length = 120 
# 設置最大復雜度 
max-complexity = 24 
# 忽略這些錯誤類型 
ignore = F401, W503, E203 
# 忽略以下文件 
exclude = 
    .git, 
    .venv, 
    __pycache__, 
    scripts, 
    logs, 
    upload, 
    build, 
    dist, 
    docs, 
    migrations, 

指定 Flke8 該如何執行, 最后調用命令 poetry run flake8. 即可。

2.2.mypy

毫無疑問， Python的語法讓人能簡潔的寫出代碼， 但是他的動態語言特性會使大型項目變得不牢固， 而 mypy 的出現恰好能解決這一問題。 mypy 是一個靜態類型檢查工具，它可以幫助我們像靜態語言一樣在運行代碼之前就捕獲到某些錯誤， 但是我們在寫Python代碼時， 要像靜態語言一樣， 會參數寫上他的類型， 這就是Type Hints, 通過 mypy 和 Type Hints 的結合， 雖然會增加我們的代碼量，  但它可以引入如下好處：

• 1.可以使 IDE 通過類型推斷提供更好的代碼補全和提示功能, 方便項目重構以及提前檢查出錯誤。

• 2.強制你去思考動態語言程序的類型可能會幫助你構建更清晰的代碼架構。

比如有如下一個函數：

def foo(a, b): 
    return a + b 

一般來說無法知道這個函數要傳什么類型的參數進去， 也許一開始是傳 int 變量， 后面變為 str 變量， 而通過 Type Hints 則可以指定這個變量的類型是什么， 以及返回的類型是什么， 經過改造后將會變為：

def foo(a: int, b: int) -> int: 
    return a + b 

這個函數的a， b參數以及返回的值類型都被標注為 int 類型， 這時候假如在程序內有兩個調用：

foo(1, 2) 
foo("a", "b") 

他們雖然都能運行， 但是可以通過 mypy 檢查出第二種調用方式是錯誤的。雖然這種示例簡簡單單， 看不出什么痛點， 但是在復雜的邏輯中， 他的優勢就非常明顯了。

在項目中可以通過 poetry add mypy --dev 安裝依賴包， 然后通過在根目錄增加 mypy.ini 文件：

# mypy的核心配置 
[mypy] 
# 指明函數的值類型也要檢查 
disallow_untyped_defs = True 
# 忽略一些import的錯誤， 有些舊包架構可能不符合mypy的要求 
ignore_missing_imports = True 
 
# 指明針對根目錄tests的配置 
[mypy-tests.*] 
# 指明忽略對這個范圍的檢查 
ignore_errors = True 

指定 mypy 該如何執行， 最后調用 poetry run mypy . 即可

2.3.自動格式化代碼

Python是一個動態語言， 而且不會對代碼風格做強要求， 這就會導致一千個人一千種Python代碼風格， 這同樣在大型項目中非常糟糕的...好在Python生態中有很多自動格式化的工具， 但這里并不會詳細對比他們的差異， 只是簡要介紹下我在試用了多種后保留了以下3個工具（適不適合自己團隊， 還是得自己試試才知道）：

Pycharm 
Pycharm 
poetry add autopep8 --dev 

• • --in-place : 直接對文件進行更改， 而不是把差異打印出來（用它就要相信他）
  • --exclude : 排除哪些文件/文件夾不進行格式化
  • --recursive : 遞歸的遍歷文件
  • --remove-all-unused-imports : 刪除所有未導入的依賴包
  • --ignore-init-module-imports : 刪除所有未導入的包時排除 __init__.py 文件
  • --remove-unused-variables :刪除未使用的變量
• 2.isort, 這個工具主要是用來給import語句進行格式化， 比如語句超出文件允許最大長度自動換行， 以及對import語句進行自動排序（這個功能對強迫癥來說爽飛了）。isort可以通過 poetry add isort --dev 進行安裝， isort支持 pyproject.toml 文件配置， 以下是我的一個常用配置:

[tool.isort] 
# 兼容black模式, 因為使用到了black進行自動格式化 
profile = "black" 
# 當import包過多超過文件長度后需要換行時， 采用哪種模式 
multi_line_output = 3 
include_trailing_comma = true 
force_grid_wrap = 0 
use_parentheses = true 
ensure_newline_before_comments = true 
# 每行的最長長度 
line_length = 120 
# 忽略的文件夾 
skip_glob = "tests" 

• 3.black, 號稱不妥協的自動格式化工具， 只要它認為不合適的， 就自動格式化， 沒有選擇的余地， 如果與團隊標準不一樣的請慎用， 我是挺接受他的自動格式化風格的...。black可以通過 poetry add black --dev 進行安裝， mypy同樣支持 pyprojrct.toml 文件配置， 以下是我的一個常用配置(black的配置項不多):

[tool.black] 
# 每行的最長長度 
line-length = 120 
# 當前是哪個Python版本 
target-version = ['py37'] 

3.pre-commit

自動格式化的工具引入到項目沒多久后就會開始尋求自動化了， 因為每次提交之前都要手動跑一些自動格式化的腳本， 實在是太麻煩了， 好在有 pre-commit 這個專門為 git hooks 而生的工具。

pre-commit 是一個用于管理和維護多種語言的  git pre-commit hooks 框架，就像Python的包管理器  pip 一樣，可以通過  pre-commit 將他人創建并分享的  pre-commit hooks 安裝到自己的項目倉庫中。 pre-commit 的出現大大減少了我們使用  git hooks 的難度，只需要在配置文件中指定想要的  hooks ，它會替你安裝任意語言編寫的  hooks 并解決環境依賴問題，然后在每次提交前執行 hooks 。

3.1.安裝

一般來說， 通過 pip install pre-commit 就可以安裝了， 但是為了環境隔離， 需要使用  poetry add pre-commit --dev 安裝， 安裝完后就可以在項目根目錄創建文件 .pre-commit-config.yaml , 以下是我的配置， 除了上面提到的幾個工具外， 還有一些其他腳本的校驗工具:

repos: 
  - repo: https://github.com/pre-commit/mirrors-mypy 
    rev: v0.910 
    hooks: 
      - id: mypy 
  - repo: https://github.com/PyCQA/isort 
    rev: 5.9.3 
    hooks: 
      - id: isort 
  - repo: https://github.com/psf/black 
    rev: 21.7b0 
    hooks: 
      - id: black 
  - repo: https://github.com/PyCQA/flake8 
    rev: 3.9.2 
    hooks: 
      - id: flake8 
  - repo: https://github.com/myint/autoflake 
    rev: v1.4 
    hooks: 
      - id: autoflake 
        args: ['--recursive',  '--in-place', '--remove-all-unused-imports', '--remove-unused-variable'] 
  - repo: https://github.com/pre-commit/pre-commit-hooks 
    rev: v3.2.0 
    hooks: 
      - id: check-ast 
      - id: check-byte-order-marker 
      - id: check-case-conflict 
      - id: check-docstring-first 
      - id: check-executables-have-shebangs 
      - id: check-json 
      - id: check-yaml 
      - id: debug-statements 
      - id: detect-private-key 
      - id: end-of-file-fixer 
      - id: trailing-whitespace 
      - id: mixed-line-ending 

文件中的內容很簡單， 它指明使用了哪些工具， 工具是哪個版本， 以及使用哪些 hook (一個倉庫可能有多個hook), 每個參數的解釋如下：

• repo: 倉庫url， pre-commit通過git來安裝存在于github的工具

• rev: 每個工具的版本， 這里是利用到git的tag屬性

• hooks/id: 每個倉庫會有很多個hook, 通過hooks-id來選擇要使用的hooks

• hook/id/args: 每個hook都支持一些參數， args就是配置hook的參數

這些工具都會讀取根目錄的配置文件， 而 autoflake 我找不到他的 pyproject.toml 配置說明， 所以直接通過的 args 參數配置參數。之后就可以直接調用 hook 腳本， 如果是第一次引入已有項目則應該先手動調用 poetry run pre-commit run --all-files , 他會調用所有 hook 對項目進行檢查, 然后再根據檢查結果對代碼和配置進行調整。調整完畢之后可以調用 poetry run pre-commit install 把 hook 腳本進行安裝，它會自動安裝在 .git/hooks/pre-commit 。安裝后， 每執行次 git commit 時， 都會通過 git hooks 機制自動執行腳本， 自動對代碼進行檢查和格式化。

上面的配置文件是我的常用配置， pre-commit 的hook有很多, 不止這些, 如有興趣可以到pre-commit hook合集(https://pre-commit.com/hooks.html)查閱所有hook

4.遠程倉庫自動執行

本地的hook只針對本地提交者， 而在團隊協作中， 其他人員可以暫時屏蔽或者刪除hook文件， 導致本地hook沒辦法達到強制的作用， 所以團隊一般會在Github&Gitlab中的 pre-recevice 階段配置一個自己的腳本， 用來跑上面的代碼檢測工具， 雖然兩種的做法有點不同， 但核心步驟都是一樣：

• 1.先拉取最新的代碼到容器里

• 2.安裝階段， 這時候會向容器安裝Python版本以及類似 Redis 容器等等

• 3.代碼檢查， 這時候會運行代碼質量檢測工具， 如果有一個檢測錯誤， 那么就拒絕提交， 并顯示哪里錯誤了, 如果沒有問題就走下一步。

• 4.測試階段， 該階段會運行測試用例，檢測測試代碼覆蓋率是否合格， 同樣的， 如果檢測不合格就會拒絕提交， 成功就進入下一步。

• 4.風格統一， 使用風格統一插件， 如Python中的 isort ,  black 等， 把項目的代碼進行格式化。

一般每個公司都有自己的一套標準 CI/CD ， 而他們的使用方法可能都會有些差別, 但核心原理也差不多， 以下會以開源項目為例介紹如何使用Github的action(這個功能是免費的！！！).

Gitlab的CI/CD相關文章比較多， 可以查閱網絡或查閱書籍《持續交付》(https://book.douban.com/subject/6862062/), 也可以查看文章：https://www.mindtheproduct.com/what-the-hell-are-ci-cd-and-devops-a-cheatsheet-for-the-rest-of-us/， 如果對Gitlab hook有興趣可以查閱Gitlab pre-receive webook 的添加與使用(treesir.pub/post/gitlab-pre-receive-webhook)

該例子來自于我的項目rap。首先在項目目錄創建 script 目錄， 這里面的目錄可以被本地調用， 但主要還是用于 Github action , 首先創建一個install的腳本, 這個腳本用于安裝依賴包：

#!/bin/sh -e 
 
# Use the Python executable provided from the `-p` option, or a default. 
[ "$1" = "-p" ] && PYTHON=$2 || PYTHON="python3" 
 
REQUIREMENTS="requirements-dev.txt" 
VENV="venv" 
 
set -x 
 
if [ -z "$GITHUB_ACTIONS" ]; then 
    "$PYTHON" -m venv "$VENV" 
    PIP="$VENV/bin/pip" 
else 
    PIP="pip" 
fi 
 
"$PIP" install -r "$REQUIREMENTS" 

注意這里是以 venv 為虛擬環境依賴的， 而不是我上面提到的 poetry . 使用 venv 的原因是線上一般是一個機器跑一個項目， 同時生產的機器都追求穩定， 這時候venv簡單而穩定的好處就體現出來了， 所以比較推薦在線上使用 venv 。上面這個腳本就是創建一個虛擬環境， 然后根據 requirements-dev.txt 安裝測試環境依賴。

依賴部分搞定了， 接下來就是告訴 Github action 該如何進行代碼質量檢查了， 于是編寫一個check的腳本：

#!/bin/sh -e 
 
export PREFIX="" 
if [ -d 'venv' ] ; then 
    export PREFIX="venv/bin/" 
fi 
 
set -x 
echo 'use venv path:' ${PREFIX} 
${PREFIX}mypy . 
${PREFIX}flake8 
${PREFIX}isort . 
${PREFIX}black . 
${PREFIX}autoflake --in-place --remove-unused-variables --recursive . 

這個腳本就是簡單的調用各個命令， 命令的順序就如同上面一樣， 先進行代碼檢查， 再跑測試用例， 最后進行代碼格式化。這里的命令沒有寫各個的配置， 因為他們都會自動讀取項目下的配置文件， 與我們的本地hook保持一致。

給Github action調用的腳本創建好后， 就開始創建真正的Github action文件了。首先在項目創建 .github/workflows 目錄， 并在 .github/workflows 目錄創建 test-suite.yml 文件(文件的更多說明見官方文檔(https://docs.github.com/cn/actions/learn-github-actions/introduction-to-github-actions))：

--- 
# 指定workflows名稱 
name: Test Suite 
 
# 指定操作push到master, 或者提pr到master時才執行 
on: 
  push: 
    branches: ["master"] 
  pull_request: 
    branches: ["master"] 
 
jobs: 
  tests: 
    # 設置任務名 
    name: "Python ${{ matrix.python-version }}" 
    # 選擇跑在哪種容器類型  
    runs-on: "ubuntu-latest" 
 
    # 設置變量, 這里設置多個Python版本表示會對每個Python版本都運行一次 
    strategy: 
      matrix: 
        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10.0-beta.3"] 
 
    steps: 
      # 調用官方的檢查和安裝python版本  
      - uses: "actions/checkout@v2" 
      - uses: "actions/setup-python@v2" 
        with: 
          python-version: "${{ matrix.python-version }}" 
      # 更改腳本權限 
      - name: "Change permissions" 
        run: | 
          chmod +x scripts/install 
          chmod +x scripts/check 
      # 安裝依賴 
      - name: "Install dependencies" 
        run: "scripts/install" 
      # 進行檢查   
      - name: "Run linting checks" 
        run: "scripts/check" 

文件編寫完畢后就可以推送代碼到遠程了, 然后就可以到Github對應的項目地址查看action執行情況， 一般成功結果如下(這里只測一個Python3.7, 如果失敗了， 你還會收到郵件提醒)：

也可以點開查看某個步驟的詳情， 比如檢查代碼的詳情:

5.總結

這些工具都是我慢慢實踐和整合后找到最符合自己的構建 Python 項目質量的工具集了， 但是這些工具只能檢查表面情況， 而其他情況如代碼邏輯是否有問題， 則需要編寫測試用例后再運行才能知道。

而有些團隊甚至會采用壓力測試， 線上仿真測試等等， 這些工具/系統的引入和使用初期會帶來很大的學習和時間成本， 但它們卻能讓項目一直保持茁壯成長, 減少線上項目Bug出現的次數（當然這些工具還有測試用例等等也要一起跟著維護）。