Cookiecutter 介紹

使用 Python 這種動(dòng)態(tài)語言進(jìn)行 web 開發(fā)，團(tuán)隊(duì)中經(jīng)常會(huì)遇到的問題就是代碼的質(zhì)量比較難控制。Python 語言本身靈活性比較高，不加控制的情況下代碼質(zhì)量可能最后很難維護(hù)。而且代碼的各方面的標(biāo)準(zhǔn)，比如提示的 lint，代碼格式化等等如果不加規(guī)范，不同開發(fā)者的協(xié)作也會(huì)比較困難。因此從公司角度來看，一個(gè)統(tǒng)一的代碼規(guī)范是很有必要的。

在 Python 的開發(fā)過程中，可以選擇公司希望遵循的 Python 開發(fā)相關(guān)的規(guī)范，那么如何更好地將這些規(guī)范組織起來呢？

一個(gè)比較好的方案就是 cookiecutter，cookiecutter 是一個(gè)用于構(gòu)建工程模板的 python 庫，利用 cookiecutter 可以構(gòu)建一個(gè)標(biāo)準(zhǔn)統(tǒng)一的起步 python 項(xiàng)目，同時(shí)在構(gòu)建中還具備一定的靈活性，根據(jù)自己需要選擇合適配置。下面就對(duì) cookiecutter 進(jìn)行簡要介紹：

Cookiecutter 簡單實(shí)踐

Cookiecutter 是一個(gè)跨平臺(tái)的 Python模板組織工具，可以極其簡單地生成一個(gè) Python 起步項(xiàng)目。

使用前需要先安裝 cookiecutter，各種安裝方式都是支持的，Mac 上可以通過 brew 或者 pip 安裝。

首先你需要尋找符合你要求項(xiàng)目模板，在 github 上通過 cookiecutter 進(jìn)行搜索即可找到大量的備選模板，我們這邊以 cookiecutter 官方維護(hù)的一個(gè)模板 cookiecutter-pypackage 為例進(jìn)行介紹，找到此模板對(duì)應(yīng)的地址 https://github.com/audreyfeldroy/cookiecutter-pypackage

之后直接執(zhí)行 cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage 即可，在執(zhí)行中會(huì)有一些可供選擇的配置型，如果不確定可以使用默認(rèn)值，一路確認(rèn)下來，你需要的起步項(xiàng)目就完成了。

如果此模板不能完成滿足你的需要，你可以選擇在構(gòu)建完成后對(duì)工程進(jìn)行小幅修改，如果需要將此模板推廣給全公司使用，直接基于此模板構(gòu)建一個(gè)新的模板進(jìn)行修改，之后再重新生成工程即可。

Cookiecutter 模板

下面可以對(duì) cookiecutter 模板的組織結(jié)構(gòu)進(jìn)行簡單介紹：

cookiecutter-something/
├── {{ cookiecutter.project_name }}/  <--------- 項(xiàng)目模板，生成的工程就是這個(gè)目錄下內(nèi)容
│   └── ...
├── blah.txt                      <--------- 模板工程之外的文件
│
└── cookiecutter.json             <--------- 提示以及默認(rèn)值的配置文件，可變的變量都存儲(chǔ)在這個(gè)文件中

通過上面的模板可以生成項(xiàng)目模板目錄下的內(nèi)容，項(xiàng)目的變量名會(huì)被輸入的內(nèi)容替換。

另外 cookiecutter 還支持一些更高級(jí)的功能，比如前置或后置的檢查 Hooks，以及注入實(shí)時(shí)上下文等，可以根據(jù)自己需要進(jìn)行使用

一個(gè)合適的項(xiàng)目模板

對(duì)于公司而言，有一個(gè)標(biāo)準(zhǔn)的項(xiàng)目規(guī)范，可以幫助大家統(tǒng)一代碼風(fēng)格，提高整體的代碼質(zhì)量，我們參考了各家的標(biāo)準(zhǔn)化建議，最終提出了一個(gè)合適的代碼規(guī)范，主要包含下面的一些部分：

lint

lint 是用于檢測代碼，有助于團(tuán)隊(duì)規(guī)則的統(tǒng)一，同時(shí)借助 lint 可以規(guī)避一些常見的坑。我們最終選擇的 lint 是：

• pylint pylint 基本上是 python 的 lint 中最常見的 lint 了，限制也比較嚴(yán)格，我們根據(jù)需要關(guān)閉了 "missing-docstring", "logging-fstring-interpolation"
• mypy 此 lint 是 python 中常見的類型檢查 lint，通過此 lint 要求方法指定參數(shù)的類型

代碼格式化

代碼格式化是用于保證代碼風(fēng)格的統(tǒng)一，代碼的格式化也存在多種選擇，我們最終選擇了：

• black 這個(gè)格式化工具的有名之處在于可配置項(xiàng)比較少，基本上通過去除靈活性來換取高度統(tǒng)一性的代碼風(fēng)格，但是 black 竟然受到了大量 python 程序員的喜愛，可能是動(dòng)態(tài)語言的靈活性讓大家更想要某種確定的規(guī)范吧
• isort 這是用來調(diào)整 python 包的 import 順序的，按照系統(tǒng)庫，第三方庫，本地庫的順序進(jìn)行分開排布

單元測試

單元測試用于保證代碼的正確性，我們選擇了評(píng)價(jià)相對(duì)更好的：

• pytest 相對(duì)于默認(rèn)的 unittest, pytest 顯然更受歡迎，pytest 使用更加便利，同時(shí)不僅能支持單元測試，還能支持面向應(yīng)用的測試
• coverage 我們使用 coverage 用于計(jì)算代碼單元測試覆蓋率，方便保證代碼的充分測試

依賴管理

• requirements 在 python 項(xiàng)目中，比較常見的是通過 requirements.txt 進(jìn)行管理，但是默認(rèn)的包管理不支持管理直接依賴和間接依賴，因此需要通過 pip-compile 進(jìn)行區(qū)分，而且開發(fā)相關(guān)的依賴也需要另外通過 requirements-dev.txt，這種管理方式比較不友好，但是考慮到大部分 python 程序員都熟悉這種情況，也可以提供了這種方式
• poetry 這是一種更新的包管理方式，可以比較好地組織好依賴關(guān)系，而且已經(jīng)被納入 PEP 518 標(biāo)準(zhǔn)了，建議優(yōu)先采用此方式管理包。同時(shí) poetry 也包含了虛擬環(huán)境的管理，使用更加便利

按照上面的規(guī)范最終構(gòu)建的 cookiecutter 模板可以參考 github

更多模板

cookiecutter 的使用過程中，上手還是比較簡單的，cookiecutter 無非是一個(gè)動(dòng)態(tài)替換的機(jī)制，沒有什么特殊的復(fù)雜性。從我的使用的感受來看，cookiecutter 的一個(gè)最大價(jià)值在于有大量的開發(fā)者已經(jīng)提供了一些現(xiàn)成的工程模板，而且我們可以相對(duì)簡單地通過已有的工程模板生成新的工程模板，并在團(tuán)隊(duì)內(nèi)部統(tǒng)一規(guī)范。

可以參考 cookiecutter 提供的大量的代碼模板根據(jù)自己的需要選擇一個(gè)基礎(chǔ)模板，然后進(jìn)行必要的修改即可得到所需的上手代碼模板。進(jìn)而生成所需的項(xiàng)目工程。比如對(duì)于上面提供的項(xiàng)目模板，如果需要增加相關(guān)文檔的支持，可以引入 Sphinx ，之后重新生成項(xiàng)目模板即可。

總結(jié)

從過往的經(jīng)驗(yàn)來看，有兩點(diǎn)總結(jié)：

• 項(xiàng)目規(guī)范化很有必要，統(tǒng)一的規(guī)范省心省力
• 不要重復(fù)造輪子，盡量使用成熟方案

使用 cookiecutter 就可以輕松實(shí)現(xiàn)