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

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

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

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

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

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

2. Django 文件規(guī)范

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

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

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

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

來(lái)看看 Django 框架的源代碼示意圖，如下：

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

3. Django 接口規(guī)范

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

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

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

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

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

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

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

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

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

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

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

4. Django 代碼規(guī)范

最后的是 Django 代碼規(guī)范，也是 Python 代碼的規(guī)范?？偨Y(jié)個(gè)人在看源碼以及在寫代碼之間盡量避免的一些問(wèn)題：

• 不要重復(fù)代碼！不要重復(fù)代碼！不要重復(fù)代碼！重要的事情說(shuō)三遍。在 Python 開發(fā)中，我們盡量不要寫重復(fù)代碼，將同一個(gè)功能的代碼盡可能封裝成函數(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ù)名都能從名稱上推測(cè)出其作用。

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

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

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

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

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

5. 小結(jié)

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