MeterSphere/frontend
2024-10-21 10:18:09 +08:00
..
.husky
config feat: 项目&组织模板联调 2024-08-01 14:15:32 +08:00
public style(字体): 字体调整 2024-08-08 11:22:32 +08:00
src fix(接口测试&测试计划): 修复接口测试报告&计划报告列表刷新icon不统一 2024-10-21 10:18:09 +08:00
types feat(系统设置): 飞书扫码登陆 2024-07-04 18:29:07 +08:00
.env.development feat(系统管理): 切换语言时后台用户信息进行记录 2024-08-16 16:27:31 +08:00
.env.production
.eslintignore feat(报告): 测试计划独立报告导出 pdf 终版 2024-09-10 15:14:31 +08:00
.eslintrc-auto-import.json
.eslintrc.cjs chore: 项目构建标准为 ESM,显式声明cjs文件 2024-07-09 18:31:05 +08:00
.gitignore
.prettierignore
.prettierrc.cjs chore: 项目构建标准为 ESM,显式声明cjs文件 2024-07-09 18:31:05 +08:00
.stylelintrc.cjs chore: 项目构建标准为 ESM,显式声明cjs文件 2024-07-09 18:31:05 +08:00
babel.config.cjs chore: 项目构建标准为 ESM,显式声明cjs文件 2024-07-09 18:31:05 +08:00
commitlint.config.cjs chore: 项目构建标准为 ESM,显式声明cjs文件 2024-07-09 18:31:05 +08:00
components.d.ts
Dockerfile
index.html fix: 解决firefox浏览器拖拽打开新标签页 2024-02-01 21:29:13 +08:00
nginx.conf
package.json feat(jsonPath): jsonPath组件升级 2024-10-15 12:25:15 +08:00
pom.xml
postcss.config.cjs chore: 项目构建标准为 ESM,显式声明cjs文件 2024-07-09 18:31:05 +08:00
README.md chore: 浏览器兼容性配置 2024-07-05 16:09:42 +08:00
tailwind.config.mjs feat(报告): 测试计划独立报告导出 pdf 终版 2024-09-10 15:14:31 +08:00
tsconfig.json feat(报告): 测试计划独立报告导出 pdf 终版 2024-09-10 15:14:31 +08:00

提交规范

1. 提交消息格式

<Type>[optional Scope]: <Description>
[optional body]

[optional footer]

Type 提交的类型

表示提交的目的或影响的范围

  • feat: 新功能A new feature
  • fix: 修复 bugA bug fix
  • docs: 文档变更Documentation changes
  • style: 代码样式调整Code style changes
  • refactor: 代码重构Code refactoring
  • test: 测试相关的变更Test-related changes
  • chore: 构建过程或工具变动Build process or tooling changes
  • perf: 性能优化Performance optimization
  • ci: CI/CD 相关的变动Changes to the CI/CD configuration or scripts
  • revert: 撤销之前的提交Revert a previous commit

Scope 作用域

提交的作用域,表示本次提交影响的部分代码或模块,可以根据项目的需要选择性地添加。

Description 描述

简明扼要地描述本次提交的内容

body 正文

可选的详细描述,可以包含更多的信息和上下文

可选的脚注,通常用于引用相关的问题编号或关闭问题。

示例提交消息:

feat(user): add login functionality

- Add login form and authentication logic
- Implement user authentication API endpoints

Closes #123

在这个示例中,提交类型为 feat新功能作用域为 user描述了添加登录功能的内容。正文部分提供了更详细的说明并引用了问题编号。

架构总览

├── babel.config.js						// babel配置支持JSX
├── commitlint.config.js			// commitlint配置校验commit信息
├── components.d.ts						// 组件注册TS声明
├── config										// 项目构建配置
│   ├── plugin								// 构建插件
│   ├── utils									// 构建工具方法
│   ├── vite.config.base.ts		// vite基础配置
│   ├── vite.config.dev.ts		// vite开发环境配置
│   └── vite.config.prod.ts		// vite 生产配置
├── index.html								// 单页面html模板
├── src
│   ├── App.vue								// 应用入口vue
│   ├── api										// 项目请求api封装
│   │   ├── http							// axios封装
│   │   ├── modules						// 各业务模块的请求方法
│   │   ├── requrls						// 按业务模块划分的接口地址
│   ├── assets								// 全局静态资源
│   │   ├── font
│   │   ├── icon-font
│   │   ├── images
│   │   ├── style
│   │		├── svg
│   ├── components						// 组件
│   ├── config								// 全局配置常量类、JSON
│   ├── directive							// 自定义指令集
│   ├── enums									// 全局枚举定义
│   ├── hooks									// 全局hooks集
│   ├── layout								// 应用布局组件
│   ├── locale								// 国际化配置
│   ├── main.ts								// 项目主入口
│   ├── models								// 全局数据模型定义
│   ├── router								// 路由
│   ├── store									// pinia状态库
│   ├── types									// 全局TS声明
│   ├── utils									// 公共工具方法
│   └── views
│       ├── modules						// 页面模块
│       └── base							// 公共页面403、404等
│   ├── env.d.ts							// 环境信息TS类型声明
└── .env.development					// 开发环境变量声明
└── .env.production						// 生产环境变量声明
└── .eslintrc.js							// eslint配置
└── .prettierrc.js						// prettier配置
└── tsconfig.json							// 全局TS配置

-状态管理模块设计

Vue3 状态管理方案采用的是piniaAPI 风格与Redux类的状态管理库类似,也是通过模块化的方式注册模块store,每个store中包含数据仓库state、数据包装过滤getter、同步/异步操作action。与Vuex相比,pinia提供了compasition-API、完整支持 TS 以及可扩展的Plugin功能。
整体模块划分为业务模块modules/*、注册入口index以及插件plugins/*
首先,在store/index.ts中声明注册pinia并引入自定义的插件:

import { createPinia } from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
import { debouncePlugin } from './plugins';
import useXXStore from './modules/xx';

const pinia = createPinia();
// 插件会在实例创建后应用因此插件不能在pinia实例创建前使用
pinia.use(debouncePlugin).use(piniaPluginPersistedstate);
export { useXXStore }; // 导出模块store
export default pinia;

然后,在项目入口mian.ts中使用:

import { createApp } from 'vue';
import store from '@/store';
import app from '@/App.vue';

createApp(app).use(store).mount('#app');

plugins

在此文件内编写pinia插件,并在注册的时候引入使用即可:

import { debounce, isObject } from 'lodash-es';
// 首先得声明插件使用到的额外属性因为pinia的TS类型声明中每个store只有三个原生属性state、getters、actions若没有使用到额外属性则无需声明
declare module 'pinia' {
  export interface DefineStoreOptionsBase<S, Store> {
    cache?: Partial<CacheType<S, Store>>; // 缓存配置
    debounce?: Partial<Record<keyof StoreActions<Store>, number>>; // 节流配置
  }
}
// 基于lodash的防抖函数封装读取store中cache配置的属性针对已配置的属性更改操作进行防抖处理
export const debouncePlugin = ({ options, store }: PiniaPluginContext) => {
  if (options.debounce) {
    return Object.keys(options.debounce).reduce((debounceActions: debounceAction, action) => {
      debounceActions[action] = debounce(store[action], options.debounce![action]);
      return debounceActions;
    }, {});
  }
};

上述自定义插件,在 store 中如下配置:

export const useStore = defineStore('demo', {
  state: () => ({
    testDebounce: '',
  }),
  getters: {},
  actions: {},
  debounce: {
    // 防抖设置
    testDebounce: 500, // 值为防抖缓冲时间
  },
});

-网络模块设计

网络模块包含:请求 url 封装api/requrls/*、请求方法封装api/modules/*、请求工具封装api/http/*

requrls

将项目接口地址收敛至此文件夹下管理,避免出现一个项目多个重复接口 url、方便接口地址复用且方便统一处理

export const LoginUrl = '/api/user/login';
export const LogoutUrl = '/api/user/logout';
export const GetUserInfoUrl = '/api/user/info';
export const GetMenuListUrl = '/api/user/menu';

modules

将项目实际请求方法按业务模块划分,统一管理实际业务请求,将请求方法与接口地址解耦

import axios from 'axios';
import { LoginUrl, LogoutUrl, GetUserInfoUrl, GetMenuListUrl } from '@/api/requrls/user';
import type { RouteRecordNormalized } from 'vue-router';
import type { UserState } from '@/store/modules/user/types';
import type { LoginData, LoginRes } from '@/models/user';

export function login(data: LoginData) {
  return axios.post<LoginRes>(LoginUrl, data);
}

export function logout() {
  return axios.post<LoginRes>(LogoutUrl);
}

export function getUserInfo() {
  return axios.post<UserState>(GetUserInfoUrl);
}

export function getMenuList() {
  return axios.post<RouteRecordNormalized[]>(GetMenuListUrl);
}

最终通过index.ts将请求方法暴露出去

export * from './modules/user';
export * from './modules/dashboard';
export * from './modules/message';

请求工具封装

基于axios封装请求方法,提供form-data/json/urlencoded格式的数据处理、自定义头部处理、响应拦截错误处理、分级提示modal、message、none、get 请求防缓存。

// 分级错误信息提示none为静默模式即不提示、modal为对话框提示、message为tips消息提示
// ErrorMessageMode默认为message模式通过传入请求方法的options.errorMessageMode入参判断
export type ErrorMessageMode = 'none' | 'modal' | 'message' | undefined;

// 三种入参数据格式
export enum ContentTypeEnum {
  // json
  JSON = 'application/json;charset=UTF-8',
  // form-data qs序列化处理
  FORM_URLENCODED = 'application/x-www-form-urlencoded;charset=UTF-8',
  // form-data  upload文件流处理
  FORM_DATA = 'multipart/form-data;charset=UTF-8',
}

// 对上传文件请求入参格式额外定义
export interface UploadFileParams {
  // 除文件流外的参数
  data?: Recordable;
  // 文件流字段名
  name?: string;
  // 文件内容
  file: File | Blob;
  // 文件名
  filename?: string;
  // 其他parmas
  [key: string]: any;
}

// 基准返回数据格式
export interface Result<T = any> {
  code: number;
  type: 'success' | 'error' | 'warning';
  message: string;
  result: T;
}

-directive 指令集

指令入口index.ts导入并注册定义的全部指令

import { App } from 'vue';
import permission from './permission';

export default {
  install(Vue: App) {
    Vue.directive('permission', permission);
  },
};

权限指令(或其他自定义指令)在同级目录下创建,以指令名称命名文件夹,下面是示例:

import { DirectiveBinding } from 'vue';
import { useUserStore } from '@/store';

function checkPermission(el: HTMLElement, binding: DirectiveBinding) {
  const { value } = binding;
  const userStore = useUserStore();
  const { role } = userStore;

  if (Array.isArray(value)) {
    if (value.length > 0) {
      const permissionValues = value;
      const hasPermission = permissionValues.includes(role);
      if (!hasPermission && el.parentNode) {
        el.parentNode.removeChild(el);
      }
    }
  } else {
    throw new Error(`need roles! Like v-permission="['admin','user']"`);
  }
}

export default {
  mounted(el: HTMLElement, binding: DirectiveBinding) {
    checkPermission(el, binding);
  },
  updated(el: HTMLElement, binding: DirectiveBinding) {
    checkPermission(el, binding);
  },
};

-hooks

全局抽象钩子集(与 Vue2 的 mixins 类似),这里只写业务逻辑的钩子!!!通过@vueuse/core我们已经可以得到非常多实用的钩子函数,没必要重复造轮子,在编写钩子功能前先去Function List查看是否已经有相同功能的钩子了,没有再自己写。导出钩子export default function useXxx,以权限钩子示例:

import { RouteLocationNormalized, RouteRecordRaw } from 'vue-router';
import { useUserStore } from '@/store';

export default function usePermission() {
  const userStore = useUserStore();
  return {
    accessRouter(route: RouteLocationNormalized | RouteRecordRaw) {
      // do something
    },
    findFirstPermissionRoute(_routers: any, role = 'admin') {
      // do something
    },
    // You can add any rules you want
  };
}

-layout

项目布局设计模块,将最上层布局组件放置此文件夹内,统一管理项目各类上层布局(若存在,例如左侧菜单-右侧内容布局、顶层菜单-中间内容-底部页脚布局等等),示例:

<template>
  <!-- router-view内为实际路由切换变化的内容视为路由页面容器 -->
  <router-view v-slot="{ Component, route }">
    <!-- transition为页面录音切换时提供进出动画平滑过渡页面渲染 -->
    <transition name="fade" mode="out-in" appear>
      <component :is="Component" v-if="!route.meta.isCache" :key="route.fullPath" />
      <!-- keep-alive提供组件状态缓存以便快速渲染组件内容 -->
      <keep-alive v-else>
        <component :is="Component" :key="route.fullPath" />
      </keep-alive>
    </transition>
  </router-view>
</template>

-models

全局数据模型,将涉及请求、组件 props、状态库的公共属性抽象为数据模型在此文件夹内声明保证全局数据的类型统一、方便维护。下面是请求模型示例

export interface HttpResponse<T = unknown> {
  status: number;
  msg: string;
  code: number;
  data: T;
}

也可以是业务相关模型:

export interface LoginData {
  username: string;
  password: string;
}

export interface LoginRes {
  token: string;
}

-router

项目路由管理模块,入口文件index.ts注册并暴露全部路由,以模块命名文件夹划分模块路由放置在routes/*下;guard/*下放置路由导航控制,包含权限、登录重定向等;app-menus/index.ts为菜单相关的路由信息;constants.ts定义路由常量,包括路由白名单、重定向路由名、默认主页路由信息等

-enums

全局的枚举类型声明模块,将可枚举的类型统一管理,以类型+Enum命名,方便维护。示例如下:

/**
 * @description: Request result set
 */
export enum ResultEnum {
  SUCCESS = 0,
  ERROR = 1,
  TIMEOUT = 401,
  TYPE = 'success',
}

/**
 * @description: request method
 */
export enum RequestEnum {
  GET = 'GET',
  POST = 'POST',
  PUT = 'PUT',
  DELETE = 'DELETE',
}

/**
 * @description:  contentTyp
 */
export enum ContentTypeEnum {
  // json
  JSON = 'application/json;charset=UTF-8',
  // form-data qs
  FORM_URLENCODED = 'application/x-www-form-urlencoded;charset=UTF-8',
  // form-data  upload
  FORM_DATA = 'multipart/form-data;charset=UTF-8',
}

-locale

国际化模块,存放项目声明的国际化配置,按语种划分模块。模块入口文件为index.ts,负责定义菜单、导航栏等公共的国际化配置,其他的按系统功能声明并导入index.ts,还有项目内页面组件的国际化配置也需要导入至index.ts,页面组件的国际化配置在页面的目录下声明,如:views/dashboard/workbench/locale

import { createI18n } from 'vue-i18n';
import en from './en-US';
import cn from './zh-CN';

export const LOCALE_OPTIONS = [
  { label: '中文', value: 'zh-CN' },
  { label: 'English', value: 'en-US' },
];
const defaultLocale = localStorage.getItem('MS-locale') || 'zh-CN';
const i18n = createI18n({
  locale: defaultLocale,
  fallbackLocale: 'en-US',
  legacy: false,
  allowComposition: true,
  messages: {
    'en-US': en,
    'zh-CN': cn,
  },
});

export default i18n;

-types

项目级别的类型声明,与业务无关的类型声明,与modelsenums不同的是,这里声明的是项目模块级别的类型,或者工具模块的类型声明,例如:axios的配置声明、第三方插件不提供 TS 支持但需要我们自定义的声明等

-utils

公共方法、工具,按功能类型命名文件,单个文件内工具方法的功能要对应命名

-views

页面模块,按功能模块划分,公共模块有loginbase,其中base模块内包含 404、403 页面等

-theme 主题配置

  1. 去 Design Lab 创建主题 https://arco.design/themes/home
  2. ms-theme- 命名为开头
  3. 点击页面的配置主题 “CSS 变量” + “Tailwind 配置变量” + “基于 css 变量自行计算混合色覆盖 arco-theme 变量”

-.env.*环境变量配置

vite中内置了环境变量配置功能,只需要在项目根目录下创建以.env.*开头的文件,在内部写入配置的变量即可,默认.env为生产环境、.env.development为开发环境、.env.XXX为自定义XXX环境(注意:自定义环境需要在package.json的项目运行命令后加入--mode XXX),各类环境变量配置示例如下( ⚠️ 注意!!环境变量文件内使用注释要用#,不能使用//:

# .env.production 为生产环境配置
NODE_ENV=production # 代码中通过import.meta.env.NODE_ENV访问
VITE_STG=1 # 自定义变量必须用VITE_开头代码中通过import.meta.env.VITE_XXX访问

# .env.development 为开发环境配置
NODE_ENV=development
VITE_APP_ENV = dev
VITE_APP_TITLE = 我是标题

# .env.XXX 为自定义环境配置
VITE_MYENV = 1 # 代码中通过import.meta.env.VITE_MYENV访问

⚠️ 上述环境变量在代码中正常都可以用import.meta.env.VITE_XXX访问,但是在vite.config.ts配置文件中无法使用此方法访问,原因是此访问链是 vite 在初始化后通过读取本地.env.XXX文件并注入到import.meta中的,但是在vite.config.ts中 vite 此时还未初始化,所以无法通过上述方法访问,应通过下面方法访问:

import { defineConfig, loadEnv } from 'vite'; // 导入loadEnv方法
loadEnv(mode, process.cwd()).VITE_XXX; // 在需要访问env里变量的地方使用此方法访问即可

-TailwindCSS 配置

module.exports = {
  content: ['./index.html', './src/**/*.{html,js,vue}', './src/*.{html,js,vue}'], // 需要解析的文件路径
  theme: {
    // 自定义主题配置
    backgroundColor: {
      // 自定义背景色
      menuHover: '#272D39',
      headerBg: '#191E29',
    },
    textColor: (theme) => ({
      // 自定义字体颜色
      ...theme('colors'), // 这里必须解构原本有的颜色不然会导致在页面style中使用@apply应用内部字体颜色类的时候报错找不到内部字体颜色类
      '40Gray': 'rgba(255,255,255,0.40)',
      '65Gray': 'rgba(255,255,255,0.65)',
    }),
    extend: {},
  },
  plugins: [],
};

-TS 配置-tsconfig.json

{
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "src/components.d.ts",
    "auto-imports.d.ts"
  ], // TS解析路径配置
  "exclude": ["node_modules"],
  "compilerOptions": {
    "allowJs": true, // 允许编译器编译JSJSX文件
    "noEmit": true,
    "target": "esnext", // 使用es最新语法
    "useDefineForClassFields": true,
    "allowSyntheticDefaultImports": true, // 允许异步导入模块,配合自动导入插件使用
    "module": "esnext", // 使用ES模块语法
    "moduleResolution": "node",
    "strict": true, // 严格模式
    "jsx": "preserve",
    "sourceMap": true, // 代码映射
    "resolveJsonModule": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "lib": ["esnext", "dom"],
    "skipLibCheck": true, // 跳过node依赖包语法检查
    "types": [
      // "vite-plugin-svg-icons/client"
    ], // 手动导入TS类型声明文件
    "baseUrl": ".",
    "paths": {
      // 路径映射
      "@/*": ["./src/*"],
      "#/*": ["types/*"]
    }
  }
}

-vite 配置-插件详解

vite构建生产资源使用rollup打包,所以可以在vite中使用rollup支持的所有插件。

  • 组件自动导入,使用unplugin-auto-import/vite插件实现自动导入组件、unplugin-vue-components/vite插件按需导入自定义组件,具体用法如下:
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ArcoResolver } from 'unplugin-vue-components/resolvers'
import { vitePluginForArco } from '@arco-plugins/vite-vue'

export default () => defineConfig({
  plugins: [
    // 自定义组件自动引入
    AutoImport({å
      dts: 'src/auto-import.d.ts', // 输出声明文件地址(在使用typescript时必须配置不然会导致页面使用未导入的组件时报错)
      resolvers: [ElementPlusResolver()], // ElementPlus自动导入
    }),
    // 自定义组件按需引入
    Components({
      dts: 'src/components.d.ts', // 输出声明文件地址(在使用typescript时必须配置不然会导致页面使用未导入的组件时报错)
      dirs: ['src/components'], // 按需加载的文件夹
      resolvers: [
        ArcoResolver(), // ArcoDesignVue按需加载
      ],
    }),
    // 样式自动导入
    vitePluginForArco({})
  ]
})
  • 使用vite-plugin-svg-icons插件实现自动加载 svg 图片,并通过封装 svg 组件的方式,一行代码使用 svg配置如下
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons';

export default () =>
  defineConfig({
    plugins: [
      createSvgIconsPlugin({
        // 指定svg读取的文件夹
        iconDirs: [resolve(process.cwd(), 'src/assets/icons/svg')],
        // 指定icon的读取名字使用svg文件名为icon名字
        symbolId: 'icon-[dir]-[name]',
      }),
    ],
  });
  • 使用vite自带插件loadEnv读取环境信息,可作环境判断,使用rollup-plugin-visualizer插件可分析打包后的文件体积,配置如下:
import { defineConfig, loadEnv } from 'vite';
import { visualizer } from 'rollup-plugin-visualizer';

// 这里的mode参数为package.json文件配置的环境参数使用`--mode XXX`,如"report: rimraf dist && vite build --mode analyze"
export default ({ mode }) =>
  defineConfig({
    plugins: [
      // 这里通过--mode analyze配置为分析模式使用visualizer插件分析方法输出report.html分析报告
      loadEnv(mode, process.cwd()).VITE_ANALYZE === 'Y'
        ? visualizer({ open: true, brotliSize: true, filename: 'report.html' })
        : null,
    ],
  });

-vite 配置-build 详解

上面讲述了插件应用,下面讲解除了插件外,在vite中的 build 构建生产资源时,rollupOptions的配置:

  • output为输出产物配置,我们可以通过manualChunks去配置分包策略(与webpack分包机制类似),配置如下:
import { mergeConfig } from 'vite';
import baseConfig from './vite.config.base';
import configCompressPlugin from './plugin/compress';
import configVisualizerPlugin from './plugin/visualizer';
import configArcoResolverPlugin from './plugin/arcoResolver';
import configImageminPlugin from './plugin/imagemin';

export default mergeConfig(
  {
    mode: 'production',
    plugins: [
      configCompressPlugin('gzip'),
      configVisualizerPlugin(),
      configArcoResolverPlugin(),
      configImageminPlugin(),
    ],
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            arco: ['@arco-design/web-vue'],
            chart: ['echarts', 'vue-echarts'],
            vue: ['vue', 'vue-router', 'pinia', '@vueuse/core', 'vue-i18n'],
          },
        },
      },
      chunkSizeWarningLimit: 2000,
    },
  },
  baseConfig
);

本地生产环境调试

需安装 docker https://www.docker.com/, 选择对应系统版本安装。

cd frontend/
pnpm run build:local
docker build -t metersphere/ms-v3 .
docker run -d -p 5100:5100 --name ms-v3 metersphere/ms-v3