前端開發(fā)規(guī)范—通用
規(guī)范的目的是為了編寫高質(zhì)量的代碼聂薪，提升協(xié)作效率坝橡，降低溝通成本。
一征字、編程規(guī)約
(一)命名規(guī)范
1.1 項(xiàng)目命名
全部采用小寫方式都弹， 以中劃線分隔。
正例：mall-management-system
反例：mall_management-system / mallManagementSystem
1.2 目錄命名
全部采用小寫方式匙姜， 以中劃線分隔畅厢，有復(fù)數(shù)結(jié)構(gòu)時(shí)，要采用復(fù)數(shù)命名法氮昧， 縮寫不用復(fù)數(shù)
正例：
scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts / img / doc
反例：
script / style / demo_scripts / demoStyles / imgs / docs
【特殊】VUE 的項(xiàng)目中的 components 中的組件目錄框杜，使用 kebab-case 命名
正例：
head-search / page-loading / authorized / notice-icon
反例：
HeadSearch / PageLoading
【特殊】VUE 的項(xiàng)目中的除 components 組件目錄外的所有目錄也使用 kebab-case 命名
正例：
page-one / shopping-car / user-management
反例：
ShoppingCar / UserManagement
1.3 JS浦楣、CSS、SCSS霸琴、HTML、PNG 文件命名
全部采用小寫方式昭伸， 以中劃線分隔
正例：
render-dom.js / signup.css / index.html / company-logo.png
反例：
renderDom.js / UserManagement.html
1.4 命名嚴(yán)謹(jǐn)性
代碼中的命名嚴(yán)禁使用拼音與英文混合的方式梧乘，更不允許直接使用中文的方式。 說(shuō)明：正確的英文拼寫和語(yǔ)法可以讓閱讀者易于理解庐杨，避免歧義选调。注意，即使純拼音命名方式也要避免采用
正例：
henan / luoyang / rmb 等國(guó)際通用的名稱灵份，可視同英文仁堪。
反例：
DaZhePromotion [打折] / getPingfenByName() [評(píng)分] / int 某變量 = 3
杜絕完全不規(guī)范的縮寫，避免望文不知義：
反例：
AbstractClass“縮寫”命名成 AbsClass填渠；condition“縮寫”命名成 condi弦聂，此類隨意縮寫嚴(yán)重降低了代碼的可閱讀性。
(二)HTML 規(guī)范 （Vue Template 同樣適用）
2.1 HTML 類型
推薦使用 HTML5 的文檔類型申明：
- 語(yǔ)言屬性
- 規(guī)定字符編碼
- IE 兼容模式
- 規(guī)定字符編碼
- doctype 大寫
<!DOCTYPE html>
<html lang="zh">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta charset="UTF-8" />
<title>Page title</title>
</head>
<body>
<img src="images/company-logo.png" />
</body>
</html>
2.2 注釋
注釋內(nèi)容前后各一個(gè)空格字符氛什，注釋位于要注釋代碼的上面莺葫，單獨(dú)占一行
正例：
<!-- Comment Text -->
<div>...</div>
反例：
<div>...</div><!-- Comment Text -->
<div><!-- Comment Text -->
...
</div>
2.3 語(yǔ)義化標(biāo)簽
HTML5 中新增很多語(yǔ)義化標(biāo)簽，所以優(yōu)先使用語(yǔ)義化標(biāo)簽枪眉，避免一個(gè)頁(yè)面都是 div 或者 p 標(biāo)簽捺檬，如header、footer贸铜、aside堡纬、main、article
[圖片上傳失敗...(image-959c4d-1660901163226)]
2.4 引號(hào)
使用雙引號(hào)(" ") 而不是單引號(hào)(' ') 蒿秦。
正例：
“xiaoming”
反例：
‘xiaoming’
(三) CSS 規(guī)范
3.1 命名 類型
- 類名使用小寫字母烤镐，以中劃線分隔，如：content-wrap
- id 采用駝峰式命名棍鳖，如：noticeChart 采用駝峰式命名职车，如：noticeValue
3.2 選擇器
- css 選擇器中避免使用標(biāo)簽名
從結(jié)構(gòu)、表現(xiàn)鹊杖、行為分離的原則來(lái)看悴灵，應(yīng)該盡量避免 css 中出現(xiàn) HTML 標(biāo)簽，并且在 css 選擇器中出現(xiàn)標(biāo)簽名會(huì)存在潛在的問題骂蓖。并且使用精確的直接子選擇器來(lái)代替后代選擇器：
正例
.content > .title
反例
.content .title
- 盡量使用縮寫屬性
正例：
padding: 0 1em 2em;
反例：
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
- 每個(gè)選擇器及屬性獨(dú)占一行
正例：
button {
width:100px;
height:50px;
color:#fff;
background:#00a0e9;
}
反例：
button{width:100px;height:50px;color:#fff;background:#00a0e9; }
- 省略0后面的單位积瞒，用0來(lái)代替0px
正例：
margin: 0;
反例：
margin: 0px;
- 避免使用ID選擇器及全局標(biāo)簽選擇器防止污染全局樣式
正例：
.header{ ..... }
反例：
#header {......}
(四) Javascript 規(guī)范
4.1命名
方法名、參數(shù)名登下、成員變量茫孔、局部變量都統(tǒng)一使用 lowerCamelCase 風(fēng)格叮喳，必須遵從駝峰形式
正例： localValue / getHttpMessage() / inputUserId
其中 method 方法命名必須是 動(dòng)詞 或者 動(dòng)詞+名詞 形式
正例：
saveShopCarData /openShopCarInfoDialog
反例：
save / open / show / go
附： 函數(shù)方法常用的動(dòng)詞:
get 獲取/set 設(shè)置,
add 增加/remove 刪除
create 創(chuàng)建/destory 移除
start 啟動(dòng)/stop 停止
open 打開/close 關(guān)閉,
read 讀取/write 寫入
load 載入/save 保存,
create 創(chuàng)建/destroy 銷毀
begin 開始/end 結(jié)束,
backup 備份/restore 恢復(fù)
import 導(dǎo)入/export 導(dǎo)出,
split 分割/merge 合并
inject 注入/extract 提取,
attach 附著/detach 脫離
bind 綁定/separate 分離,
view 查看/browse 瀏覽
edit 編輯/modify 修改,
select 選取/mark 標(biāo)記
copy 復(fù)制/paste 粘貼,
undo 撤銷/redo 重做
insert 插入/delete 移除,
add 加入/append 添加
clean 清理/clear 清除,
index 索引/sort 排序
find 查找/search 搜索,
increase 增加/decrease 減少
play 播放/pause 暫停,
launch 啟動(dòng)/run 運(yùn)行
compile 編譯/execute 執(zhí)行,
debug 調(diào)試/trace 跟蹤
observe 觀察/listen 監(jiān)聽,
build 構(gòu)建/publish 發(fā)布
input 輸入/output 輸出,
encode 編碼/decode 解碼
encrypt 加密/decrypt 解密,
compress 壓縮/decompress 解壓縮
pack 打包/unpack 解包,
parse 解析/emit 生成
connect 連接/disconnect 斷開,
send 發(fā)送/receive 接收
download 下載/upload 上傳,
refresh 刷新/synchronize 同步
update 更新/revert 復(fù)原,
lock 鎖定/unlock 解鎖
check out 簽出/check in 簽入,
submit 提交/commit 交付
push 推/pull 拉,
expand 展開/collapse 折疊
begin 起始/end 結(jié)束,
start 開始/finish 完成
enter 進(jìn)入/exit 退出,
abort 放棄/quit 離開
obsolete 廢棄/depreciate 廢舊,
collect 收集/aggregate 聚集
4.2常量命名全部大寫，單詞間用下劃線隔開缰贝，力求語(yǔ)義表達(dá)完整清楚馍悟，不要嫌名字長(zhǎng)
正例：
MAX_STOCK_COUNT
反例：
MAX_COUNT
4.3代碼格式
不同邏輯、不同語(yǔ)義剩晴、不同業(yè)務(wù)的代碼之間插入一個(gè)空行分隔開來(lái)以提升可讀性
[圖片上傳失敗...(image-3e800-1660901163226)]
4.4字符串
統(tǒng)一使用單引號(hào)(‘)锣咒，不使用雙引號(hào)(“)。這在創(chuàng)建 HTML 字符串非常有好處
4.5對(duì)象聲明
- 使用字面值創(chuàng)建對(duì)象
正例：
let user = {};
反例：
let user = new Object();
- 使用字面量來(lái)代替對(duì)象構(gòu)造器
正例：
var user = {
age: 0,
name: 1,
city: 3
};
反例：
var user = new Object();
user.age = 0;
user.city = 0;
4.6 使用 ES6,7
必須優(yōu)先使用 ES6,7 中新增的語(yǔ)法糖和函數(shù)赞弥。這將簡(jiǎn)化你的程序毅整，并讓你的代碼更加靈活和可復(fù)用。比如箭頭函數(shù)绽左、await/async 悼嫉， 解構(gòu)， let拼窥、const 戏蔑， for…of 等等
- let/const
let 聲明的變量只在 let 命令所在的代碼塊內(nèi)有效。
const 聲明一個(gè)只讀的常量鲁纠，一旦聲明辛臊，常量的值就不能改變。
- 箭頭函數(shù)
this.xxx(() => {
...
})
- await/async
async xxx() {
...
}
await xxx()
- 解構(gòu)
let { foo, bar } = { foo: 'aaa', bar: 'bbb' };
// foo = 'aaa'
// bar = 'bbb'
- for…of
var arr = ['nick','freddy','mike','james'];
for(var item of arr){
console.log(item);
}
4.7 括號(hào)
下列關(guān)鍵字后必須有大括號(hào)（即使代碼塊的內(nèi)容只有一行）：if, else, for, while, do, switch, try, catch, finally, with房交。方便他人閱讀
正例：
if (condition) {
doSomething();
}
反例：
if (condition) doSomething();
4.8 undefined 判斷
永遠(yuǎn)不要直接使用 undefined 進(jìn)行變量判斷彻舰；使用 typeof 和字符串’undefined’對(duì)變量進(jìn)行判斷。
正例：
if (typeof person === 'undefined') {
...
}
反例：
if (person === undefined) {
...
}
4.9 條件判斷和循環(huán)最多三層
條件判斷能使用三目運(yùn)算符和邏輯運(yùn)算符解決的候味，就不要使用條件判斷刃唤，但是謹(jǐn)記不要寫太長(zhǎng)的三目運(yùn)算符。如果超過 3 層請(qǐng)抽成函數(shù)白群，并寫清楚注釋尚胞。
4.10 this 的轉(zhuǎn)換命名
對(duì)上下文 this 的引用只能使用’self’來(lái)命名
let self = this
4.11 跳轉(zhuǎn)方法命名
統(tǒng)一叫 ***To，例：detailTo
二帜慢、Vue 項(xiàng)目規(guī)范
(一)Vue 編碼基礎(chǔ)
1.1 組件規(guī)范
1) 組件名為多個(gè)單詞笼裳。
組件名應(yīng)該始終是多個(gè)單詞組成（大于等于 2），且命名規(guī)范為KebabCase格式粱玲。
這樣做可以避免跟現(xiàn)有的以及未來(lái)的 HTML 元素相沖突躬柬，因?yàn)樗械?HTML 元素名稱都是單個(gè)單詞的。
正例：
export default {
name: 'TodoItem'
// ...
};
反例：
export default {
name: 'Todo',
// ...
}
export default {
name: 'todo-item',
// ...
}
2) 組件文件名為 pascal-case 格式
正例：
components/
|- my-component.vue
反例：
components/
|- myComponent.vue
|- MyComponent.vue
3) 基礎(chǔ)組件文件名為 base 開頭抽减，使用完整單詞而不是縮寫允青。
正例：
components/
|- base-button.vue
|- base-table.vue
|- base-icon.vue
反例：
components/
|- VueTable.vue
|- Icon.vue
4) 和父組件緊密耦合的子組件應(yīng)該以父組件名作為前綴命名
正例：
components/
|- todo-list.vue
|- todo-list-item.vue
|- todo-list-item-button.vue
|- user-profile-options.vue （完整單詞）
反例：
components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue
|- UProfOpts.vue （使用了縮寫）
5) 在 Template 模版中使用組件，應(yīng)使用 PascalCase 模式卵沉，并且使用自閉合組件
正例：
<!-- 在單文件組件颠锉、字符串模板和 JSX 中 -->
<MyComponent />
<Row><table :column="data"/></Row>
反例：
<my-component /> <row><table :column="data"/></row>
6) 組件的 data 必須是一個(gè)函數(shù)
當(dāng)在組件中使用 data 屬性的時(shí)候 (除了 new Vue 外的任何地方)法牲，它的值必須是返回一個(gè)對(duì)象的函數(shù)。 因?yàn)槿绻苯邮且粋€(gè)對(duì)象的話琼掠，子組件之間的屬性值會(huì)互相影響拒垃。
正例：
export default {
data () {
return {
name: 'jack'
}
}
}
反例：
export default {
data: {
name: 'jack'
}
}
7) Prop 定義應(yīng)該盡量詳細(xì)
- 必須使用 camelCase 駝峰命名
- 必須指定類型
- 必須加上注釋，表明其含義
- 必須加上 required 或者 default瓷蛙，兩者二選其一
- 如果有業(yè)務(wù)需要悼瓮，必須加上 validator 驗(yàn)證
正例：
props: {
// 組件狀態(tài)，用于控制組件的顏色
status: {
type: String,
required: true,
validator: function (value) {
return [
'succ',
'info',
'error'
].indexOf(value) !== -1
}
},
// 用戶級(jí)別速挑，用于顯示皇冠個(gè)數(shù)
userLevel：{
type: String,
required: true
}
}
8) 為組件樣式設(shè)置作用域
正例：
<template>
<button class="btn btn-close">X</button>
</template>
<!-- 使用 `scoped` 特性 -->
<style scoped>
.btn-close {
background-color: red;
}
</style>
9) 如果特性元素較多谤牡，應(yīng)該主動(dòng)換行副硅。
正例：
<MyComponent foo="a" bar="b" baz="c"
foo="a" bar="b" baz="c"
foo="a" bar="b" baz="c"
/>
反例：
<MyComponent foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c" foo="a" bar="b" baz="c"/>
1.2. 模板中使用簡(jiǎn)單的表達(dá)式
組件模板應(yīng)該只包含簡(jiǎn)單的表達(dá)式姥宝，復(fù)雜的表達(dá)式則應(yīng)該重構(gòu)為計(jì)算屬性或方法。復(fù)雜表達(dá)式會(huì)讓你的模板變得不那么聲明式恐疲。我們應(yīng)該盡量描述應(yīng)該出現(xiàn)的是什么腊满，而非如何計(jì)算那個(gè)值。而且計(jì)算屬性和方法使得代碼可以重用培己。
正例：
<template>
<p>{{ normalizedFullName }}</p>
</template>
// 復(fù)雜表達(dá)式已經(jīng)移入一個(gè)計(jì)算屬性
computed: {
normalizedFullName: function () {
return this.fullName.split(' ').map(function (word) {
return word[0].toUpperCase() + word.slice(1)
}).join(' ')
}
}
反例：
<template>
<p>
{{
fullName.split(' ').map(function (word) {
return word[0].toUpperCase() + word.slice(1)
}).join(' ')
}}
</p>
</template>
1.3 指令都使用縮寫形式
指令推薦都使用縮寫形式碳蛋，(用 : 表示 v-bind: 、用 @ 表示 v-on: 和用 # 表示 v-slot:)
正例：
<input
@input="onInput"
@focus="onFocus"
>
反例：
<input
v-on:input="onInput"
@focus="onFocus"
>
1.4 標(biāo)簽順序保持一致
單文件組件應(yīng)該總是讓標(biāo)簽順序保持為
正例：
<template>...</template>
<script>...</script>
<style>...</style>
反例：
<template>...</template>
<style>...</style>
<script>...</script>
1.5 必須為 v-for 設(shè)置鍵值 key
1.6 v-show 與 v-if 選擇
如果運(yùn)行時(shí)省咨，需要非常頻繁地切換肃弟，使用 v-show ；如果在運(yùn)行時(shí)零蓉，條件很少改變笤受，使用 v-if。
1.7 Vue Router 規(guī)范
1) 頁(yè)面跳轉(zhuǎn)數(shù)據(jù)傳遞使用路由參數(shù)
頁(yè)面跳轉(zhuǎn)敌蜂，例如 A 頁(yè)面跳轉(zhuǎn)到 B 頁(yè)面箩兽，需要將 A 頁(yè)面的數(shù)據(jù)傳遞到 B 頁(yè)面，推薦使用 路由參數(shù)進(jìn)行傳參章喉，而不是將需要傳遞的數(shù)據(jù)保存 vuex汗贫，然后在 B 頁(yè)面取出 vuex 的數(shù)據(jù)，因?yàn)槿绻?B 頁(yè)面刷新會(huì)導(dǎo)致 vuex 數(shù)據(jù)丟失秸脱，導(dǎo)致 B 頁(yè)面無(wú)法正常顯示數(shù)據(jù)
正例：
let id = ' 123';
this.$router.push({ name: 'userCenter', query: { id: id } });
2) 使用路由懶加載（延遲加載）機(jī)制
{
path: '/uploadAttachment',
name: 'uploadAttachment',
meta: {
title: '上傳附件'
},
component: () => import('@/view/components/uploadAttachment/index.vue')
},
3) router 中的命名規(guī)范
path落包、childrenPoints 命名規(guī)范采用kebab-case命名規(guī)范（盡量vue文件的目錄結(jié)構(gòu)保持一致，因?yàn)槟夸浱健⑽募际莐ebab-case妥色，這樣很方便找到對(duì)應(yīng)的文件）
name 命名規(guī)范采用KebabCase命名規(guī)范且和component組件名保持一致！（因?yàn)橐３謐eep-alive特性遏片，keep-alive按照component的name進(jìn)行緩存嘹害，所以兩者必須高度保持一致）
4) router 中的 path 命名規(guī)范
path除了采用kebab-case命名規(guī)范以外撮竿，必須以 / 開頭，即使是children里的path也要以 / 開頭笔呀。如下示例
目的：
經(jīng)常有這樣的場(chǎng)景：某個(gè)頁(yè)面有問題幢踏，要立刻找到這個(gè)vue文件，如果不用以/開頭许师，path為parent和children組成的房蝉，可能經(jīng)常需要在router文件里搜索多次才能找到，而如果以/開頭微渠，則能立刻搜索到對(duì)應(yīng)的組件
{
path: '/file',
name: 'file',
component: Main,
meta: {
title: '文件服務(wù)',
icon: 'ios-cloud-upload'
},
children: [
{
path: '/file/file-list',
name: 'fileList',
component: () => import('@/views/file/file-list.vue')
},
{
path: '/file/file-add',
name: 'fileAdd',
component: () => import('@/views/file/file-add.vue')
},
{
path: '/file/file-update',
name: 'fileUpdate',
component: () => import('@/views/file/file-update.vue')
}
]
}
(二) Vue 項(xiàng)目目錄規(guī)范
2.1 基礎(chǔ)
vue 項(xiàng)目中的所有命名一定要與后端命名統(tǒng)一搭幻。
比如權(quán)限：后端 privilege, 前端無(wú)論 router , store, api 等都必須使用 privielege 單詞！
2.2 使用 Vue-cli 腳手架
使用 vue-cli3 來(lái)初始化項(xiàng)目逞盆，項(xiàng)目名按照上面的命名規(guī)范檀蹋。
2.3 目錄說(shuō)明
視項(xiàng)目而定
1) api 目錄
- 文件、變量命名要與后端保持一致云芦。
- 此目錄對(duì)應(yīng)后端 API 接口俯逾，按照后端一個(gè) controller 一個(gè) api js 文件。若項(xiàng)目較大時(shí)舅逸，可以按照- 業(yè)務(wù)劃分子目錄桌肴，并與后端保持一致。
- api 中的方法名字要與后端 api url 盡量保持語(yǔ)義高度一致性琉历。
- 對(duì)于 api 中的每個(gè)方法要添加注釋坠七，注釋與后端 swagger 文檔保持一致。
正例：
后端 url： EmployeeController.java
/employee/add
/employee/delete/{id}
/employee/update
前端： employee.js
// 添加員工
addEmployee: (data) => {
return postAxios('/employee/add', data)
},
// 更新員工信息
updateEmployee: (data) => {
return postAxios('/employee/update', data)
},
// 刪除員工
deleteEmployee: (employeeId) => {
return postAxios('/employee/delete/' + employeeId)
},
2) assets 目錄
assets 為靜態(tài)資源旗笔，里面存放 images, styles, icons 等靜態(tài)資源彪置，靜態(tài)資源命名格式為 kebab-case
|assets
|-- icons
|-- images
| |-- background-color.png
| |-- upload-header.png
|-- styles
3) components 目錄
此目錄應(yīng)按照組件進(jìn)行目錄劃分，目錄命名為 KebabCase换团，組件命名規(guī)則也為 KebabCase
|components
|-- error-log
| |-- index.vue
| |-- index.less
|-- markdown-editor
| |-- index.vue
| |-- index.js
|-- kebab-case
4) constants 目錄
|constants
|-- index.js
|-- role.js
|-- employee.js
export const EMPLOYEE_STATUS = {
NORMAL: {
value: 1,
desc: '正常'
},
DISABLED: {
value: 1,
desc: '禁用'
},
DELETED: {
value: 2,
desc: '已刪除'
}
};
5) router 與 store 目錄
這兩個(gè)目錄一定要將業(yè)務(wù)進(jìn)行拆分悉稠，不能放到一個(gè) js 文件里。
router 盡量按照 views 中的結(jié)構(gòu)保持一致
[圖片上傳失敗...(image-61b5b1-1660901163226)]
store 按照業(yè)務(wù)進(jìn)行拆分不同的 js 文件
|store
|- modules
|-- cart
|--- index.js
|-- home
|--- index.js
|- index.js
6) views 目錄
- 命名要與后端艘包、router的猛、api 等保持一致
- components 中組件要使用 PascalCase 規(guī)則
|-- views 視圖目錄
| |-- role role模塊名
| | |-- role-list.vue role列表頁(yè)面
| | |-- role-add.vue role新建頁(yè)面
| | |-- role-update.vue role更新頁(yè)面
| | |-- index.less role模塊樣式
| | |-- components role模塊通用組件文件夾
| | | |-- role-header.vue role頭部組件
| | | |-- role-modal.vue role彈出框組件
| |-- employee employee模塊
| |-- behavior-log 行為日志log模塊
| |-- code-generator 代碼生成器模塊
2.4 注釋說(shuō)明
整理必須加注釋的地方
公共組件使用說(shuō)明
- api 目錄的接口 js 文件必須加注釋
- store 中的 state, mutation, action 等必須加注釋
- vue 文件中的 template 必須加注釋，若文件較大添加 start end 注釋
- vue 文件的 methods想虎，每個(gè) method 必須添加注釋
- vue 文件的 data, 非常見功能要加注釋
[圖片上傳失敗...(image-df5c97-1660901163226)]
2.5 其他
1) 盡量不要手動(dòng)操作 DOM
因使用 vue 框架卦尊，所以在項(xiàng)目開發(fā)中盡量使用 vue 的數(shù)據(jù)驅(qū)動(dòng)更新 DOM，盡量（不到萬(wàn)不得已）不要手動(dòng)操作 DOM舌厨，包括：增刪改 dom 元素岂却、以及更改樣式、添加事件等。
2) 刪除無(wú)用代碼
因使用了 git/svn 等代碼版本工具躏哩，對(duì)于無(wú)用代碼必須及時(shí)刪除署浩，例如：一些調(diào)試的 console 語(yǔ)句、無(wú)用的棄用功能代碼扫尺。
3) 拉取筋栋、提交代碼
- 不允許提交有報(bào)錯(cuò)糠溜、有沖突的代碼
- 未開發(fā)完成的代碼如影響其他頁(yè)面需注釋后提交
- 每次開發(fā)之前必須拉取代碼窖认，避免沖突，
- 開發(fā)中建議多次不定時(shí)拉取摔癣，保持最新代碼
- 提交代碼時(shí)寫清楚本次修改內(nèi)容
- 后期不要隨意格式化其他團(tuán)隊(duì)的文件姑曙，自己的可以
- 為了在本地調(diào)試進(jìn)行臨時(shí)修改的文件在提交時(shí)要丟棄襟交，不提交
