目的

规范的目的是为了编写高质量的代码，让团队成员每天看代码的心情是愉悦的，大家在一起是快乐的。

一、通用规范

（一）命名规范

1.1.1 命名严谨性

尽量使用语义化的英文命名方式，严禁使用拼音与英文混合的方式，即使纯拼音命名方式也要避免采用。

1.1.2 项目命名

全部采用小写方式，以中划线分割

  • good：transport-management-system
  • bad：transport_management_system和transportManagementSystem

1.1.3 目录命名

全部采用小写方式，以中划线分隔，有复数结构时，要采用复数命名法，缩写不用复数

  • good：scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts / img / doc
  • bad：script / style / demo_scripts / demoStyles / imgs / docs

1.1.4 JS、CSS、SCSS、HTML、PNG 文件命名

  • good：render-dom.js / index.css / index.html / company-logo.png
  • bad：renderDom.js / UserManagement.html

CSS命名

  • class使用小写字母，以中划线分隔
  • id使用驼峰命名
  • less中的变量、函数、混合使用驼峰命名

JavaScript命名

  • 变量：使用驼峰命名，优先使用let、const、避免使用var
  1. let userName = 'luffy'
  2. const userInfo = {
  3.     name: 'luffy'
  4. }
  • 常量：字母全部大写，以下横线_划分
  1. const DEFAULT_CONFIG = {
  2.     apiKey: 'AIzaSyAGaARUnw9JZdo7SogXdU-J_aIyNQ1BcHs',
  3.     authDomain: 'push-9d0cc.firebaseapp.com'
  4. }
  • 函数：使用驼峰命名命名，并且是动词或者动词+名词形式，以阐明方法的用途

good：getHouseListData / openCarInfoDialog
bad：get / open / go

（二）HTML规范（Vue Template 同样适用）

1.2.1 语义化标签

优先使用header / footer / section / nav / main等语义化标签，避免满屏div

1.2.2 缩进

嵌套的节点应该缩进，使用4个缩进

1.2.3 单双引号

html中使用双引号""

  1. <div class="wrap"></div>

JavaScript中使用单引号''

  1. let username = 'luffy'
  3. import { minBy } from 'lodash'

1.2.4 重复代码

避免过多重复代码，如果超过三行类似的代码，配置数据再循环遍历

（三）CSS规范

1.3.1 选择器

  • 避免使用标签选择器
  • 避免使用important选择器
  • 推荐使用直接子选择器
  1. // good
  2. .content > .title{
  3.     color: red;
  4.     font-size: 16px;
  5. }
  7. // bad
  8. .content .title{
  9.     color: red;
  10.     font-size: 16px;
  11. }

1.3.2 less嵌套

避免大量的嵌套规则，最好在3级之内，对于超过4级的嵌套，给予重写评估

JavaScript规范

1.4.1 代码格式

不同逻辑、不同语义、不同业务的代码直接插入一个空行隔开

1.4.2 字符串

统一使用单引号，不使用双引号

  1. // good
  2. let str = 'foo';
  3. let testDiv = '<div id="test"></div>';
  5. // bad
  6. let str = 'foo';
  7. let testDiv = "<div id='test'></div>";

1.4.3 条件判断

优先考虑三目运算符，但谨记不要写超过3层的三目运算符

1.4.4 this的转换命名

对上下文this的引用使用’self’来命名

1.4.5 删除无用代码

对于无用代码必须及时删除，例如：一些调试的 console 语句、无用的弃用功能代码

二、Vue项目规范

（一）项目目录规范

2.1.1 目录结构

  1. src                               源码目录
  2. |-- api                              所有api接口
  3. |   |-- index.ts                     入口
  4. |   |-- market.ts                       market模块
  5. |   |-- user.ts                         user模块
  6. |-- assets                           静态资源，images, icons, styles等
  7. |   |-- images                       全局公用图片
  8. |   |-- svgs                         全局公用svg
  9. |   |-- styles                       全局公用样式
  10. |-- components                       公用组件
  11. |-- config                           配置信息
  12. |-- hooks                            公用方法封装
  13. |-- directives                       自定义指令
  14. |-- filters                          过滤器，全局工具
  15. |-- lib                              外部引用的插件存放及修改文件
  16. |-- plugins                          插件，全局使用
  17. |-- router                           路由，统一管理
  18. |-- |-- modules                      按照专题划分模块
  19. |-- |-- |-- education.js             教育专题
  20. |-- |-- index.js                     首页入口
  21. |-- store                            vuex, 统一管理
  22. |-- |-- modules                      按照专题划分模块
  23. |-- |-- |-- education
  24. |-- |-- index.js
  25. |-- views                            视图目录
  26. |   |-- monitoring                       market模块名
  27. |   |-- |-- index.vue                    market列表页面
  28. |   |-- |-- components                   market详情页面
  29. |   |-- |-- |--                market模块通用组件文件夹
  30. |   |-- decision                         employee模块

2.1.2 api目录规范

  • 文件、变量命名要尽量与后端保持一致
  • 此目录对应后端api接口，按照后端一个controller一个api.js文件
  • api中的方法名字要与后端api url尽量保持语义高度一致
  • 每个api添加注释，阐明接口用途

举个栗子：

  1. // 后端url：MarketController.java
  3. `/market/index`
  4. `/market/detail/{id}`
  5. // 前端 market.ts
  6. export const market: ApiList = {
  7.     index: '/market/index'
  8.     detail: '/market/detail'
  9. }

2.1.2 assets目录规范

里面存放 images, styles, icons 等静态资源，静态资源命名格式为小写+中划线

  1. |assets
  2. |-- icons
  3. |-- images
  4. |   |-- background-color.png
  5. |   |-- company-logo.png
  6. |-- styles

2.1.3 components 目录规范

按照业务组件进行目录划分，目录命名为小写+中划线，组件命名规则也为小写+中划线

  1. user-info
  2. layout-header

2.1.4 router、store 目录规范

  • 按业务进行拆分成不同的ts文件
  • router尽量按照 views 中的结构保持一致

（二）组件规范

2.2.1 组件引入

引入的组件注册名使用驼峰命名，template模板中使用小写+中划线。
原因：在js中更自然的是驼峰命名，而html中对大小写是不敏感。

  1. <template>
  2.     <user-info-panel></user-info-panel>
  3. </template>
  5. import UserInfoPanel from "./components/user-info-panel";
  7. export default {
  8.     components: {
  9.         UserInfoPanel
  10.     }
  11. }

2.2.2 组件传值

定义Prop的时候以驼峰命名，在父组件传值的时候使用小写+中划线，原因同上

  1. // 子组件 js
  2. props: {
  3.     activeIndex: { 
  4.         type: Number,
  5.         required: true, 
  6.         default: -1 
  7.     }
  8. }
  9. // 父组件 template
  10. <market-item :active-index="1"></market-item>

2.2.3 proxy代理

  • 所有请求都必须加上api-proxy前缀，开发环境通过vue.config.js 中的proxy代理
  • 后端的接口也必须加上api-proxy前缀，ng再配置转发，如果后端不以此前缀开头，必须拒绝，并让其修改

（三）其他规范

2.3.1 v-for

使用v-for时，必须写key

2.3.2 style

为组件样式设置作用域，每个组件style都需要加上scoped

2.3.3 适当换行和空行

  • 如果组件上元素较多，需要换行
  • 每个逻辑结束需要空一行
  1. // good
  2. li(
  3.     :item='item',
  4.     :index='index',
  5.     :key='item.id',
  6.     :active-index='activeIndex',
  7.     @mouseover='setActiveIndex(index)',
  8.     @mouseout='setActiveIndex(-1)',
  9.     @click='$emit("itemClick", item, "historyList")'
  10. )
  11. // bad
  12. li(:item='item', :index='index', :key='item.id', :active-index='activeIndex',  @mouseover='setActiveIndex(index)', @mouseout='setActiveIndex(-1)', @click='$emit("itemClick", item, "historyList")'
  13. )