這裡會簡單介紹下基於 Django 框架開發 Web 專案中要遵守的一些基本開發規範。

1. Django 開發規範

對於 Django 的開發規範，我個人的總結如下：

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

這些初始的規範在其他 Web 專案開發中也是合適的，最重要也是最難的一件事情就是堅持做好上面這些，同時堅持良好的程式碼規範。

2. Django 檔案規範

首先針對 Django 的檔案規範，其實和其他 Web 開發差不多，需要做到如下幾點：

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

• 專案中新增加的程式碼檔案命名儘量準確並體現裡面程式碼功能，比如新增一個處理路徑相關的程式碼，檔案可以命名為 path.py；

• Django 中給我們新建的 models.py，views.py，我們要儘量按照它定義的功能編寫程式碼，比如 models.py 是用來定義所在應用的資料庫模型的，views.py 是用來編寫本應用的檢視函式。我們在該應用中新增的模組程式碼也要命名清晰，比如後面我們在每個應用中會新增 urls.py

  檔案，該檔案中定義了本應用的所有 URL 和對應的檢視；

來看看 Django 框架的原始碼示意圖，如下：

從這裡我們是不是能夠感受到一個流行框架的專案是不是具備我們上面描述的規範呢？在 Django 的框架原始碼中，每一個模組的程式碼都在對應的目錄中，每個目錄下的程式碼檔案命名十分清晰明瞭，比如 request.py 和 response.py 直接從檔名就能看出這個檔案的功能。

3. Django 介面規範

對於 Django 的 URL 介面規範，遵循如下幾點規則：

• 開發之前，先要詳細設計專案的 API 介面，包括輸入引數以及響應資料的格式，最好能形成相關的介面文件；

• URL 介面要按照應用劃分，每個 App 目錄裡面要有自己的 urls.py 檔案。裡面是本應用中的所有 url 和 檢視的對映關係。總的 url 入口在 settings.py 檔案中配置，預設是和 settings.py 檔案同目錄下的 urls.py；

• 對於 URL 介面本身，傾向於使用 Restful 風格的 API 介面設計，比如介面：

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

  這樣的規範只是一種廣泛使用的 API 介面設計風格，並不是必須的。因此在 Django 中的 各種 View 類來輔助我們設計這樣的 API 介面。

• 在專案中實現 Django 的 Web API 介面時，往往是使用 DFR （Django Rest Framework）來輔助構建專案的 API 介面。DRF 在 Django 的基礎上迅速實現 API ，並且自身還帶有 Web 的測試頁面，可以方便的測試自己的 API 介面；

• 最後就是關於公司內部介面設計人的喜好了，比如有人喜歡講第一版本和第二版本介面設計用這樣的 URL區分：

  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 程式碼規範

最後的是 Django 程式碼規範，也是 Python 程式碼的規範。總結個人在看原始碼以及在寫程式碼之間儘量避免的一些問題：

• 不要重複程式碼！不要重複程式碼！不要重複程式碼！重要的事情說三遍。在 Python 開發中，我們儘量不要寫重複程式碼，將同一個功能的程式碼儘可能封裝成函式以供呼叫；

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

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

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

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

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

• 此外，儘量使用一些做的比較好的第三方外掛，比如 DRF 幫助我們快速實現 Web API 介面，同時還提供了認證相關功能，可以讓我們簡化開發難度，而且提供良好的程式碼風格。在一些情況下，儘量避免自己重複造輪子，而且造的是差輪子；

• 編寫函式測試用例。這個是很多開發工程師不願意做的但是又十分重要的一點。對於一些重要函式，我們一定要記得給這個函式設計一個測試用例，避免後續有人接收是改動該函式能及時發現異常

以上是我在工作中的一些體會，主要是在開發中碰到的一些常見的規範問題。有些公司的程式碼規範會詳細到如何定義好的變數名、對註釋的限制等等。養成良好的 Python 程式碼規範是專案中的一個重要環節。一個非常好的途徑就是去學習 Python 專案的相關原始碼，這裡推薦的有： Flask、Django、Ansible 等流行的開源專案，從中可以學到不少設計模式以及 Python 中的高階用法。

5. 小結

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