前端代码规范

可乐罐头
143 阅读5分钟

开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第 6 天，点击查看活动详情

前端开发指南

一些公共约束说明。

引导性：快速上手项目。

可读性：命名、顺序。

质量性：规避性能问题、规避语言缺陷。

快速开始

// 安装依赖
npm i
// 启动项目
npm run serve
// 提交代码
npm run commit
// 打包
npm run build:prod

文件格式

├── CHANGELOG.md 更新日志
├── LICENSE 协议
├── README.md 初始化说明文档
├── babel.config.js babel 配置
├── build 打包配置
├── commitlint.config.js 提交格式化配置
├── jest.config.js 测试配置
├── jsconfig.json 编译器配置
├── mock 模拟数据
├── package-lock.json
├── package.json
├── postcss.config.js
├── public 公共可配置资源
├── src
│ ├── api api 模块
│ ├── assets 公共资源
│ ├── components 全局组件
│ ├── icons 图标
│ ├── layout 布局
│ ├── locales 国际化
│ ├── main.js 入口
│ ├── permission.js 权限控制
│ ├── register 注册文件
│ │ ├── registerComponent.js 全局组件注册
│ │ ├── registerProperty.js 全局属性注册
│ │ ├── registerDirective.js 全局指令注册
│ │ ├── directives 全局指令文件夹
│ ├── router
│ │ ├── routes 路由模块化
│ ├── store
│ │ ├── modules store 模块化
│ ├── styles 全局样式
│ ├── utils 全局工具
│ └── views 页面模块
├── tests 测试集
└── vue.config.js

代码规范

命名规范、书写顺序规范等

命名分类
  • camelCase（驼峰式）
  • kebab-case（短横线连接式）
  • PascalCase（帕斯卡命名式）
  • snake_case（下划线连接式）
  • XX_YY_ZZ（常量命名规范）
文件命名
  • 工程命名
    kebab-case 规范
  • 目录命名
    • 1、components
      PascalCase，并采用特殊前缀标识全局组件，比如 GlobalSvgIcon
    • 2、views
      PascalCase，尽量目录名称和路由名称一一对应，这里提一下路由命名规范： path 采用 kebab-case 规范，name 采用 PascalCase 规范，一级路由 path 需以 / 开头
  • 文件命名
    • 1、JavaScript 文件
      类文件采用 PascalCase，其他采用 camelCase
    • 2、CSS\SCSS 文件
      kebab-case 规范
    • 3、Vue 文件
      路由组件采用 kebab-case 规范，其他采用 PascalCase 规范，组件最好使用 index.js 进行暴露
    • 4、其他资源文件
      kebab-case 规范
HTML
  • 使用语义化标签，例如每一节采用 <section>，标题采用 <h1>等
  • html 自定义元素或者组件命名采用 kebab-case 规范
  • 元素保持闭合状态，错误示例：<div />
  • 减少样式内联
  • 尽量分块注释
JavaScript
  • 函数采用单一原则，需添加注释(ctrl+win+t)
  • 重构和优化部分需添加 TODO 注释
  • 必须采用 ES6 语法。var -> let; promise -> async...await 等
  • if...else 采用 switch...case 替代
  • 无用代码需要去除或者单独存于另一文件
  • 复杂数据处理采用社区成熟工具库，如 lodash，避免在项目内造轮子
  • 全局公共函数放置 utils 目录，函数命名以 snake_case 规范，类命令以 PascalCase
  • 避免往 window 对象挂载全局属性，采用 vuex 等方式
CSS
  • 采用 scoped 语法，避免在组件内书写全局样式
  • 类命名采用 kebab-case，组件内取组件名作为根类名
  • z-index 取值建议在 1 - 100
  • 使用 border-box 模型，元素间距离采用 margin，元素和内容间距采用 padding，注意 margin 边距折叠情景
  • 优先使用flex、grid布局，减少传统正常流、定位流、浮动流等布局方式
  • 考虑使用 inherit、initial、unset、revert使用场景，减少重复 CSS 规则
  • 全局样式覆盖组件库对应组件样式在 style/components/${component}.scss 对应组件内进行覆盖
  • 避免使用 id 和 标签选择器
  • 尽量使用子选择器
  • 尽量使用缩写属性
  • 避免使用!important，尽量根据选择器优先级来设置权重
  • 兼容处理采用 postcss 插件
  • 系统全局样式在 style/global.scss 中书写
  • 组件内采用 scoped + ::v-deep (dart-sass 用 >>> )深度选择器方案，覆盖组件库默认样式
  • px 作为单位，必要采用 postcss-px-to-viewport 插件转换
  • theme\theme.scss 进行 UI 组件库主题定制，style\variables.scss 进行额外主题定制
Vue
  • 组件抽象原则: 业务原子化、可复用、松耦合、可测试
  • 组件必须声明 name 字段，命名采用 PascalCase
  • props、data、computed、watch、methods 采用 camelCase 方式，保持语义化和多单词组合
  • 避免组件内使用 document.querySelector 等方式操作节点，尽量根据状态和 $refs 来驱动 DOM
  • 组件定时器、非 vue 元素事件监听器、data 里面 DOM 等在组件销毁都需要记得重置
  • 大数据量的数据尽量使用 Object.freeze 进行冻结
  • props 显示声明类型和默认值，使用时采用 kebab-case 方式，保持原子化
  • mixins 中私有属性采用 $ 前缀
  • methods 采用动宾短语。
    • 1、主动触发（用户 UI 事件） handleXxx
    • 2、接口请求 getXxx、postXxx、putXxx、delXxx
    • 3、数据处理 processXxx
  • 组件间事件（emit），命名采用 kebab-case，尽量采用 on-前缀，标识组件事件
  • created 发起 ajax 请求、mounted 获取 dom 节点
  • 递归较多采用 render 方式
  • 命名顺序：name -> mixins -> directives -> components -> props -> data -> computed -> watch -> lifecycle -> methods
  • 避免使用 $parent 和 $children 等非常规通信方式
  • vue-router 非首屏路由采用动态加载方式，并注以 webpackChunkName:'ChunkName'
  • vue-store state、mutations、actions、getters 聚合在一个文件的一个对象内，采用命名空间模式，同步commit，异步 dispatch
其他
  • 国际化采用文件目录作为命名空间，支持嵌套文件目录
  • 工具函数添加，尽量加上对应单元测试，每次提交运行所以单元测试
  • 代码组织尽量按照模块组织，全局命名尽量在 base、common、index中选择
  • 非全局代码，组织在对应模块utils、components、views、mixins目录下面
  • 全局代码抽出需通知相应组员，防止重复造轮子，后期该全局代码由创建者或其他共建者维护，其他组员负责code review

必须功能特性

  • 提交规范化
  • 代码格式和规范化
  • 单元测试集

项目实践

ESLint

我们一般采用 ESLint 来检测 JavaScript、Vue文件的代码质量。通过工具，当我们写出不合规则的代码，则出现相应警告。

Prettier

我们一般采用 Prettier 来检测 JSON、Vue、JavaScript的代码风格。通过工具，当我们代码风格和规则不符时，则会出现相应的警告，保存即可修复。

StyleLint

我们一般采用 StyleLint 来检测 CSS、SCSS的代码质量。通过工具，当我们写出不合规则的代码，则出现相应警告。

EditorConfig

我们一般使用 EditorConfig 来设置统一的项目代码风格和解决一些跨平台的代码风格问题。

Husky + LintStaged + CommitLint

我们一般采用这套工具，达成代码提交时的代码风格和质量校验、提交格式规范化、单元测试等操作，只有经过一系列操作，代码才能正式提交到远程仓库，保证远程仓库的质量性。

avatar
文章
阅读
粉丝