Django項目開發(fā)規(guī)范

這里會簡單介紹下基于 Django 框架開發(fā) Web 項目中要遵守的一些基本開發(fā)規(guī)范。

1. Django 開發(fā)規(guī)范

對于 Django 的開發(fā)規(guī)范，我個人的總結(jié)如下：

• 正式開始基于 Django 的 Web 服務(wù)項目之前，需要完成相應(yīng)的需求和接口設(shè)計， 而不要冒冒然直接開寫；
• 工程需要有完整的文檔介紹 、服務(wù)部署腳本（start、stop） 等等，讓這個項目至少看起來高大上和完整；
• 完善的版本迭代機制，每個版本的需求說明、bug 更新文檔以及相應(yīng)的版本號。

這些初始的規(guī)范在其他 Web 項目開發(fā)中也是合適的，最重要也是最難的一件事情就是堅持做好上面這些，同時堅持良好的代碼規(guī)范。

2. Django 文件規(guī)范

首先針對 Django 的文件規(guī)范，其實和其他 Web 開發(fā)差不多，需要做到如下幾點：

• 項目中目錄命名盡量有含義。比如常用的 utils 目錄下，一般放一些自己寫的常用函數(shù)或者通用類；

• 項目中新增加的代碼文件命名盡量準(zhǔn)確并體現(xiàn)里面代碼功能，比如新增一個處理路徑相關(guān)的代碼，文件可以命名為 path.py；

• Django 中給我們新建的 models.py，views.py，我們要盡量按照它定義的功能編寫代碼，比如 models.py 是用來定義所在應(yīng)用的數(shù)據(jù)庫模型的，views.py 是用來編寫本應(yīng)用的視圖函數(shù)。我們在該應(yīng)用中添加的模塊代碼也要命名清晰，比如后面我們在每個應(yīng)用中會添加 urls.py 文件，該文件中定義了本應(yīng)用的所有 URL 和對應(yīng)的視圖；

來看看 Django 框架的源代碼示意圖，如下：

從這里我們是不是能夠感受到一個流行框架的項目是不是具備我們上面描述的規(guī)范呢？在 Django 的框架源碼中，每一個模塊的代碼都在對應(yīng)的目錄中，每個目錄下的代碼文件命名十分清晰明了，比如 request.py 和 response.py 直接從文件名就能看出這個文件的功能。

3. Django 接口規(guī)范

對于 Django 的 URL 接口規(guī)范，遵循如下幾點規(guī)則：

• 開發(fā)之前，先要詳細(xì)設(shè)計項目的 API 接口，包括輸入?yún)?shù)以及響應(yīng)數(shù)據(jù)的格式，最好能形成相關(guān)的接口文檔；

• URL 接口要按照應(yīng)用劃分，每個 App 目錄里面要有自己的 urls.py 文件。里面是本應(yīng)用中的所有 url 和 視圖的映射關(guān)系?？偟?url 入口在 settings.py 文件中配置，默認(rèn)是和 settings.py 文件同目錄下的 urls.py；

• 對于 URL 接口本身，傾向于使用 Restful 風(fēng)格的 API 接口設(shè)計，比如接口：

  • /manage/user：對應(yīng)的 GET、POST、PUT 和 Delete 請求，我們往往會對應(yīng)著用戶模型 user 的增刪改查操作

  這樣的規(guī)范只是一種廣泛使用的 API 接口設(shè)計風(fēng)格，并不是必須的。因此在 Django 中的 各種 View 類來輔助我們設(shè)計這樣的 API 接口。

• 在項目中實現(xiàn) Django 的 Web API 接口時，往往是使用 DFR （Django Rest Framework）來輔助構(gòu)建項目的 API 接口。DRF 在 Django 的基礎(chǔ)上迅速實現(xiàn) API ，并且自身還帶有 Web 的測試頁面，可以方便的測試自己的 API 接口；

• 最后就是關(guān)于公司內(nèi)部接口設(shè)計人的喜好了，比如有人喜歡講第一版本和第二版本接口設(shè)計用這樣的 URL區(qū)分：

  https://example.com/api/v1/book/1  -> v1 版本接口
  https://example.com/api/v2/book/1  -> v2 版本接口
  

  還有設(shè)計響應(yīng)數(shù)據(jù)的格式，也要簡單明了。比如可以簡單使用如下的 JSON 數(shù)據(jù)表示響應(yīng)結(jié)果：

  {
      "code": 200,                # 響應(yīng)碼
      "content": [] or {} or "",  # 返回數(shù)據(jù)內(nèi)容，可以是[]、{} or str等
      "err_msg": ""               # 錯誤信息
  }
  

4. Django 代碼規(guī)范

最后的是 Django 代碼規(guī)范，也是 Python 代碼的規(guī)范。總結(jié)個人在看源碼以及在寫代碼之間盡量避免的一些問題：

• 不要重復(fù)代碼！不要重復(fù)代碼！不要重復(fù)代碼！重要的事情說三遍。在 Python 開發(fā)中，我們盡量不要寫重復(fù)代碼，將同一個功能的代碼盡可能封裝成函數(shù)以供調(diào)用；

• python 代碼中變量、函數(shù)、類的命名，盡量有含義，比如下面定義的 Connection 類：

  class Connection(BaseConnection):
      def __init__(self, host, port, user, passwd):
          ...
      
      # 遠(yuǎn)程執(zhí)行shell命令
      def run_command(cmd):
          ...
          
      # 上傳文件到遠(yuǎn)端服務(wù)器
      def upload_file(source_src, dest_src, mode):
          ...
          
      # 從遠(yuǎn)端服務(wù)器上下載文件    
      def download_file(remote_src, dest_src, mode):
          ...
          
      ...
  
  

  可以看到，這里 從 類名到參數(shù)，到函數(shù)名都能從名稱上推測出其作用。

• 不要盲目在一個函數(shù)中堆砌代碼。一個函數(shù)內(nèi)的代碼盡量控制在如 50 行內(nèi)，每行的代碼的長度也不要過長，容易引起視覺反感；

• 如果有能力，需要多學(xué)習(xí)一些設(shè)計模式相關(guān)知識，還有 Python 的各種高級用法。有時候不是為了酷炫，而是這樣使用能做到非常好的簡化代碼和封裝代碼；

• 此外，盡量使用一些做的比較好的第三方插件，比如 DRF 幫助我們快速實現(xiàn) Web API 接口，同時還提供了認(rèn)證相關(guān)功能，可以讓我們簡化開發(fā)難度，而且提供良好的代碼風(fēng)格。在一些情況下，盡量避免自己重復(fù)造輪子，而且造的是差輪子；

• 編寫函數(shù)測試用例。這個是很多開發(fā)工程師不愿意做的但是又十分重要的一點。對于一些重要函數(shù)，我們一定要記得給這個函數(shù)設(shè)計一個測試用例，避免后續(xù)有人接收是改動該函數(shù)能及時發(fā)現(xiàn)異常

以上是我在工作中的一些體會，主要是在開發(fā)中碰到的一些常見的規(guī)范問題。有些公司的代碼規(guī)范會詳細(xì)到如何定義好的變量名、對注釋的限制等等。養(yǎng)成良好的 Python 代碼規(guī)范是項目中的一個重要環(huán)節(jié)。一個非常好的途徑就是去學(xué)習(xí) Python 項目的相關(guān)源碼，這里推薦的有： Flask、Django、Ansible 等流行的開源項目，從中可以學(xué)到不少設(shè)計模式以及 Python 中的高級用法。

5. 小結(jié)

本小節(jié)中，我從自己的角度總結(jié)了一些 Django 項目開發(fā)過程中要注意的一些事項，當(dāng)然這里也只是一些個人見解。讀者可以參考部分覺的有益的建議，也可以使用符合本公司項目情況的相關(guān)規(guī)范。規(guī)范是為了讓更多的開發(fā)人員能很好的了解和完善項目。如果在進(jìn)行項目開發(fā)前，沒有相關(guān)的規(guī)范，隨著時間的推移，不同的開發(fā)人員有著各自的開發(fā)風(fēng)格，最后導(dǎo)致的結(jié)果就是大部分項目的風(fēng)格混亂，結(jié)構(gòu)不清，代碼也是慘不忍睹，最后被后續(xù)接手的人瘋狂吐槽。當(dāng)然，有好的規(guī)范不一定能做成好的項目，但是沒有好的規(guī)范的項目，往往是做不成功的。