You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
shop-admin/README.md

11 KiB

马士兵管理平台模板

技术架构

  • 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 来表示,已弃用