马士兵管理平台模板

技术架构

• vite

  新兴主流项目编译构建工具，与 webpack 相比构建速度极快

• vue3

  vue 最新版本，声明式 API，组件内各功能点代码耦合性低，易扩展维护

• vue-router

  SPA 路由系统

• vuex

  数据状态管理，规范组件之间数据传递，更好得监测数据状态变化

• axios

  AJAX 请求封装库，用于调用 API 接口

• element-plus

  基础组件库

插件

• jsx

  javascript & react 语法，封装组件时编码更加灵活方便，功能开发时不推荐使用

• svg-icon

  根据自定义 svg 文件生成 icon

• auto-import

  编译时自动引入依赖

• components

  编译时自动局部注册 ElementPlus 组件和 src/components 目录下的自定义组件

• style-import

  编译时按需引用 ElementPlus 样式文件

• global-style

  编译时自动注入全局样式和变量

• remove-console

  打包时自动移除 console 语句

• vuex-persistedstate

  vuex 数据持久化

• legacy

  浏览器兼容处理

• eslint

  不影响 HMR 编译速度的情况下异步进行 eslint 代码校验

• husky

  git hooks 管理

• lint-staged

  git commit 时仅对提交部分代码进行 eslint 校验

• commitlint

  git commit 时对提交信息进行规范校验

规范约束

• 使用 VS Code 进行开发，并安装项目推荐的插件
• 不允许修改 src 目录以外的（项目配置）文件
• 有需要优化解决的问题记录到 TODO.md 文件中，包括技术方面的踩坑记录和业务方面的 BUG 记录
• 按照当前项目结构进行功能开发，不允许随意改变项目文件结构

项目结构

SRC 目录	用途描述
api	API 接口定义
assets	资源文件，按功能模块分文件夹
components	自定义通用组件
configs	项目框架配置
icons	图标库，svg 图标文件
layouts	页面框架布局
plugins	全局插件模块
router	本地路由模块
store	数据状态模块
styles	全局样式模块
utils	工具类库模块
views	SFC 模块，页面文件

开发须知

通用组件

• 文件规范命名，使用简单易懂的单词概括组件的功能
• 写好 Props 参数注释
• 具有良好的扩展性和通用性
• 优化、修复问题时考虑向下兼容，尽可能不影响已有代码
• 使用 setup script 语法糖和 jsx 语法
• 有数据绑定功能的必须支持 v-mdoel 语法

路由页面

• 严格遵循既定的项目模块结构
• 单个功能页面之间通用组件应单独在页面目录创建 components 文件夹，而不是全部都放进 src/components
• 必须使用 defineComponent 包裹组件定义，并定义好具有唯一性的 name
• 不允许使用 this，严禁滥用 getCurrentInstance()，proxy 对象只用于访问全局方法
• 规范使用 ref、reactive、toRefs、unref 等响应式 API，访问响应式数据时应使用 unref 包裹而不是访问 .value
• 各个功能点应区分代码块并写好注释，不允许延续 vue2 编码思想将各个功能点代码耦合在一起，特别复杂逻辑应代码分块并单独创建文件引入使用
• 不允许以任何形式直接修改 props 传入的值，包括对象中的属性和数组中的元素，如需双向绑定应使用触发事件 update:propsName 的方式
• 页面根元素应包含 *-container 的 class，无特殊情况使用单根元素，多根元素会影响动画过渡效果

工具类库

• 项目已集成 lodash、dayjs，不要重复造轮子
• 全局方法应在 plugins/global-api.js 中注册，而不是写成工具类到处引用
• 注释中应有完善的功能说明、入参出参说明、注意事项等
• 新增工具类后应及时通知所有项目开发者知悉
• 优化修复工具类应向下兼容确保不会影响已有代码，改动较大应召集相关人员商讨解决方案
• 应进行完善的逻辑测试和性能测试，确保不会影响项目稳定性，谨慎使用 setTimeout、setInterval 等循环\递归操作

状态管理

• 每个功能模块都要对应一个数据状态管理模块
• 必须通过 mutations 修改 state 中的数据
• 字典数据应全部存放在 state 中统一管理
• 接口调用及后续数据逻辑处理应在 actions 中进行，保证多处调用时行为统一

样式相关

• 参考 src/styles/gobalVariables.module.less，颜色、字号、边距、圆角尽可能复用已有的变量
• 没有特殊需求不允许写全局样式，stlye 标签必须加 scoped
• 深度选择器使用 :deep(<selector>){} 语法，>>> 、/deep/、v-deep:都已弃用
• 没有特殊需求不允许定义或使用 ID 选择器、属性选择器

分支管理

• 分支命名：父分支-功能描述-创建日期-创建人；例如：beta-userManagement-0323-xwk
• 紧急修复应基于 dev 分支创建，功能分支应基于 beta 分支创建
• 提测前先将 beta 分支合并到功能分支解决冲突，再将功能分支合并到 test 分支，严禁将 test 分支合并进其他任何分支
• 测试通过后先将 beta 分支合并到功能分支解决冲突，再通过提 push request 通知负责人进行代码审查，审查通过后由负责人合并代码
• 预发通过后先将 dev 分支合并到 beta 分支解决冲突，再将 beta 分支合并到 dev 分支，此操作只能由负责人进行
• 解决冲突时如涉及其他开发者代码，应跟当事人确认无误后再合并

提交代码

• 提交前确认项目能正常运行，改动部分功能正常
• 严格遵循 eslint、prettier 代码规范
• 严禁使用 git commit --no-verify -m "xxx" 强制提交代码
• 规范提交信息

  前缀	使用场景	示例
  feat	新增功能点、模块	feat: 用户管理
  fix	修复 BUG	fix: 用户管理分页异常
  doc	文档、注释更新	doc: README
  style	样式、不影响逻辑的代码格式更新	style: 用户管理标题字号
  refactor	重构功能点、模块	refactor: 路由模块逻辑重构
  test	测试	test: 测试工具类
  revert	撤回提交	revert: 有文件漏提交
  build	编译打包	build: 编译用户管理
  merge	合并分支	merge: beta into dev
  perf	性能、体验、逻辑优化	pref: 路由模块解析性能
  conf	配置更新	conf: 项目 base 路径
  chore	其他	chore: 其他

全局方法

使用示例

import { copy } from '@/plugins/global-api.js';
copy('hello world');

const { proxy } = getCurrentInstance();
proxy.$copy('hello world');

名称	功能介绍
copy	复制文本
download	下载指定地址文件
excel	导出 excel 文件并下载
dict	字典查询
name	昵称和姓名拼接显示

全局组件

名称	功能介绍
ElEditor	富文本编辑器
ElUploadImage	图片上传
TableList	通用列表组件

心得总结

prettier

统一代码格式

安装依赖

npm install --save-dev prettier

安装 VS Code 插件 prettier

新建工作区设置文件 .vscode/settings.json
设置保存代码时自动格式化
自动解决 eslint 代码格式问题
设置个文件类型默认格式化工具

{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll": true,
        "source.organizeImports": true
    },
    "[vue]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[json]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[jsx]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[jsonc]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[html]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "vetur.format.defaultFormatter.html": "prettier",
}

commitlint

提供 commit message 校验功能

安装依赖

npm install --save-dev @commitlint/config-conventional @commitlint/cli

编写配置

在项目根目录下创建 commitlint.config.js 或者 .commitlintrc.js
并在其中定义好可以使用前缀，如果格式不符将报错并导致提交失败

module.exports = {
    extends: ['@commitlint/config-conventional'],
    rules: {
        'type-enum': [
            2,
            'always',
            ['feat', 'fix', 'doc', 'style', 'refactor', 'test', 'revert', 'build', 'merge', 'perf', 'conf', 'chore'],
        ],
        'type-case': [0],
        'type-empty': [0],
        'scope-empty': [0],
        'scope-case': [0],
        'subject-full-stop': [0, 'never'],
        'subject-case': [0, 'never'],
        'header-max-length': [0, 'always', 72],
    },
};

提交代码

git commit -m "feat: xxx"

注意要使用英文冒号，冒号后面跟空格

HUSKY

可以对 git hooks 进行管理

安装依赖

npm install -D husky

在 package.json 中添加脚本

{
    //...
    "scripts": {
        //...
        "prepare": "husky install"
    }
    //...
}

prepare 脚本会在 npm install（不带参数）之后自动执行。也就是说当我们执行 npm install 安装完项目依赖后会执行 husky install 命令，该命令会创建.husky/目录并指定该目录为 git hooks 所在的目录。

添加 git hooks

npx husky add .husky/pre-commit "npx lint-staged"

运行完该命令后我们会看到 .husky/ 目录下新增了一个名为 pre-commit 的 shell 脚本。
也就是说在在执行 git commit 命令时会先执行 pre-commit 这个脚本。
这个脚本的功能是运行 lint-staged 检查待提交的代码规范约束。
不能直接写 lint-staged，会报错找不到命令，npm run lint-staged 也可以不过需要在 package.json 中添加 lint-staged 这个命令，所以使用 npx lint-staged。

npx husky add .husky/commit-msg 'npx commitlint --edit "$1"'

运行完该命令后我们会看到 .husky/ 目录下新增了一个名为 commit-msg 的 shell 脚本。
也就是说在在执行 git commit 命令时会执行 commit-msg 这个脚本。
这个脚本的功能是运行 commitlint 检查 git commit 的 message 格式规范。
同 lint-staged 需要使用 npx 来运行命令，$1 代表开发者提交代码时输入的 commit message，老版本husky中使用$HUSKY_GIT_PARAMS 来表示，已弃用