Python編碼規範

阿新 • • 發佈：2021-06-22

程式碼編碼：

python編碼

1、國際慣例，檔案編碼和 Python 編碼格式全部為 utf-8 ，例如：在 Python 程式碼的開頭，要統一加上 # -- coding: utf-8 --。
2、Python 程式碼中，非 ascii 字元的字串，請需新增u字首
3、若出現 Python編碼問題，可按照以下操作嘗試解決：

import sys
reload(sys)
sys.setdefaultencoding('utf-8')

命名規範:

包名、模組名、區域性變數名、函式名

全小寫+下劃線式駝峰 示例：this_is_var

全域性變數

全大寫+下劃線式駝峰 示例：GLOBAL_VAR

類名

首字母大寫式駝峰 示例：ClassName()

變數名命名

儘量體現變數的資料型別和具體意義

注：

變數名、類名取名必須有意義，嚴禁用單字母
變數名不要用系統關鍵字，如 dir type str等等

建議：

bool變數一般加上字首 is_ 如：is_success

import 順序:

1、標準庫
2、第三方庫
3、專案本身
(之間用空行分隔)

models 內部定義順序:

All database fields
Custom manager attributes
class Meta
def (str)
def save()
def get_absolute_url()
Any custom methods

異常捕獲處理原則:

1.儘量只包含容易出錯的位置，不要把整個函式 try catch
2.對於不會出現問題的程式碼，就不要再用 try catch了
3.只捕獲有意義，能顯示處理的異常
4.能通過程式碼邏輯處理的部分，就不要用 try catch
5.異常忽略，一般情況下異常需要被捕獲並處理，但有些情況下異常可被忽略，只需要用 log 記錄即可，可參考一下程式碼：

def ignored():
    try:
        yield
    except Exceptions as e:
        logger.warning(e)
        pass

return early原則

提前判斷並 return，減少程式碼層級，增強程式碼可讀性(簡單邏輯往前放)

if not condition:
    return
# a lot if code

Fat model， thin view

邏輯程式碼和業務程式碼解耦分離，功能性函式以及對資料庫的操作定義寫在 models 裡面，業務邏輯寫在 view 裡面。

許可權校驗裝飾器異常丟擲問題

建議許可權不足時直接丟擲異常，可以使用 django 自帶的：

from django.core.exceptions import PermissionDenied

許可權不足時丟擲異常 PermissionDenied，之後應該返回什麼樣的頁面由 handler 或者中介軟體去處理

分 method 獲取 request 引數問題

一般可以分method 獲取request引數，這樣能夠使程式碼更可讀，且之後修改 method 時不必每個引數都修改

args = request.GET if request.method == "GET" else request.POST
business_name = args.get('business_name', '')
template_name = args.get('template_name', '')

使用數字、常量表示狀態

兩種的話改為 true/false，多種改為 enum 可讀性更好

def enum(**enums):
    return type("Enum", (), enums)

StatusEnum = enum(
    SUCCESS=True,
    FAIL=False,
)

其他注意問題

1、【必須】去除程式碼中的 print，否則導致正式和測試環境 uwsgi 輸出大量資訊
2、邏輯塊空行分隔
3、變數和其使用盡量放到一起
4、【必須】 import過長，要放在多行的時候，使用 from xxx import（a, b, c）,不要用 \ 換行
5、Django Model 定義的 choices 直接在定義在類裡面

前端編碼規範：

命名規則

1、類的基礎命名方式：“專案英文簡寫-當前頁-頁面內容塊”如 .ijobs-index-box。
2、Id 的基礎命名方式：語義化，並使用下滑槓連線，如步驟名稱可命名為 #step_name
3、Javascript 變數命名方式：按照變數型別的首個字母為字首，使用駝峰命名法；

例子：

var aName = ['zhangsan','lizi','zhaowu'];  //Array 陣列
var oBtn = window.document.getElementById('btn');  //Object 物件
function fnName(){};  //Function 函式
var nAge = 25;  //Integer(int) 整型
var sWebURL="www.wangyingran.com";  //String 字串

日誌規範：

日誌輸出級別:

1、Error：系統異常，影響使用者使用，必須通知到開發者及時修復。
2、Warning：系統異常，不影響使用者使用，但有異常需要跟進修復。
3、Info：系統流水日誌或日常記錄,不做通知配置。

日誌輸出格式：

1、日誌需要包含當前函式名，方便查詢和定位。
2、重要操作流水直接記錄資料庫，可以儲存較長時間。
3、錯誤日誌要方便定位問題，建議記錄當前引數以及上下文變數。

程式碼提交規範

每次程式碼提交必須有備註說明，註明本次提交做了哪些修改
commit 分類：

bugfix: -------- 線上功能 bug
sprintfix: ----- 未上線程式碼修改 （功能模組未上線部分bug）
minor: --------- 不重要的修改（換行，拼寫錯誤等）
feature: ----- 新功能說明

介面規範

Api 的 method：
1.Api 的 method，要根據實際請求的型別，查詢一定要用 get，不能隨意指定 method。
2.具體可以參考文件《RESTful Web Services Cookbook-cn.pdf》。

介面返回內容
介面返回內容開發建議直接參考藍鯨 apigateway 規範，返回的內容中包含 result code data message request_id 這幾個欄位

介面返回Status Code
**建議充分利用 HTTP Status Code 作為響應結果的基本狀態碼，基本狀態碼不能區分的 status，
再用響應 body 中"約定"的 code 進行補充

http狀態碼詳細說明請參考：https://zh.wikipedia.org/wiki/HTTP狀態碼**

介面資料驗證
資料檢驗邏輯"應當"和業務邏輯分離，這樣做的好處：
程式碼邏輯更加清晰
資料校驗邏輯（可能）可以複用

分離方案：

1）form-data/url-params：Django-Form 
2）Json：Json-schema

程式碼註釋

Python 程式碼註釋

方法必須使用標註註釋，如果是公有方法或對外提供的 API 相關方法，則最好給出使用樣例。如：

Module註釋：在開頭要加入對該模組的註釋。如：

普通程式碼註釋應該以‘#’和單個空格開始。

如果有需要調整或者需要優化的地方，可以使用 #TODO 這裡是註釋內容”進行註釋，

格式：'#'+單個空格+'TODO'+單個空格+註釋內容。

方法的返回，如果資料結構比較複雜，則必須要對返回結果的每個屬性做解釋。

前端程式碼註釋

Html 註釋:

<!-- 容器 -->
<div class=“container”>
...
<!-- 使用者名稱 -->
<div id=“user_name”>
...
</div>
<!-- /使用者名稱 -->
...
</div>
<!-- /容器 -->

css 註釋

內容比較少是可以只在頂部加註釋，內容比較多時在尾部加結束標籤/* 註釋內容 end */

/* 新建任務 start */
.new-task{}
/* 新建任務名 */
.task-name{color:#333;}
/* 新建任務時間 */
.task-created-time{background:url(img/clock.png) no-repeat;}
/* 新建任務 end */

Js 註釋

Js註釋同上，函式如果有引數，建議簡單備註一下引數的內容和型別。

檔案或包的引用

Python 程式碼：

模組或包的引入最好使用完整路徑，即使是同一個包下的相互引用，也建議使用完整路徑。
這樣比較方便程式碼閱讀，同時若後續需修改為相對路徑也很簡單。

前端頁面：

在頁面中引用 css 和 js、或配置 url 路徑時，必須使用“絕對路徑”，而不要使用‘…/’，‘./’等相對路徑的引用方式