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

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

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

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

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

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

2. Django 文件規(guī)范

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

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

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

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

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

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

3. Django 接口規(guī)范

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

• 開發(fā)之前，先要詳細設計項目的 API 接口，包括輸入參數以及響應數據的格式，最好能形成相關的接口文檔；

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

• 對于 URL 接口本身，傾向于使用 Restful 風格的 API 接口設計，比如接口：

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

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

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

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

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

  還有設計響應數據的格式，也要簡單明了。比如可以簡單使用如下的 JSON 數據表示響應結果：

  {
      "code": 200,                # 響應碼
      "content": [] or {} or "",  # 返回數據內容，可以是[]、{} or str等
      "err_msg": ""               # 錯誤信息
  }
  

4. Django 代碼規(guī)范

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

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

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

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

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

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

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

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

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

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

5. 小結

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