图片文件命名

使用小写，多个单词使用下划线连接

  • 例如：add_enterprise.png，component_authorization.png。

解释：文件系统兼容性：某些文件系统对大小写敏感，而有些不敏感。使用下划线（asd_dsd）可能减少潜在的兼容性问题。

vue 文件 template 注释

  • 根据内容分部分注释

  • 示例：

<template>
  <div class="enterprise-member">
    <!-- 头部 -->
    <div class="header"></div>
    <!-- 搜索 -->
    <div class="search-bar"></div>
    <!-- 内容 -->
    <div class="content"></div>
  </div>
</template>

hooks

功能区分

  • 根据功能使用 region 分割区域注释

  • 示例：

//#region 跳转
...
//#endregion

//#region 表格操作 - 包含删除和数据加载逻辑
...
//#endregion

函数注释 ：：：待定

  • 每个函数上方添加注释，描述函数功能、参数、返回值等信息。

  • 示例：

/**
 * @description: 获取企业列表
 * @param {string} name - 企业名称
 * @return {Promise<any>}
 */
const getEnterpriseList = (name: string) => {
  ...
}

utils 工具函数

函数注释

  • 每个函数上方添加注释，描述函数功能、参数、返回值等信息。

  • 示例：

/**
 * @description: 获取企业列表
 * @param {string} name - 企业名称
 * @return {Promise<any>}
 */
const getEnterpriseList = (name: string) => {
  ...
}

多个工具函数文件

  • 当在 utils 文件夹下创建多个文件时，创建一个 index.ts 文件，将所有工具函数导出。

  • 示例：

// 在 utils/index.ts 文件中引入并导出
export * from "./date";
export * from "./download";
export * from "./form_rules";
export * from "./image";
export * from "./storage";
export * from "./validate";
  • 文件目录示例：
utils/
├── index.ts
├── date.ts
├── download.ts
├── form_rules.ts
├── image.ts
├── storage.ts
└── validate.ts

  • 在其他文件中导入时，使用相对路径导入。

  • 示例：

import { index引入其它文件的方法名 } from "@/utils";

  • 优点：

    • 方便管理：将相关功能集中在一个文件夹中，便于管理和维护。

    • 减少冗余：通过 index.ts 文件集中导出，减少重复代码。

    • 提高可读性：通过相对路径导入，更容易理解代码的依赖关系。

    • 引入方法时：减少了文件路径的书写，提高了代码的可读性和可维护性。

  • 缺点：

    • 需要手动维护 index.ts 文件，当新增或删除文件时，需要手动更新。

Class 工具函数

  • 使用 class 封装工具函数，方便管理，使用静态方法。

  • 示例：

export class Download {
  static exportExcelData(filename: string, data: Blob) {
    ...
  }

  static exportExcelDataTwo(filename: string, data: Blob) {
    ...
  }

  static exportExcelDataThree(filename: string, data: Blob) {
    ...
  }
}
  • 使用时：
Download.exportExcelData("test.xlsx", new Blob());

使用对象

  • 使用对象封装工具函数，方便管理，使用对象方法。

  • 示例：

export const download = {
  exportExcelData: (filename: string, data: Blob) => {
    ...
  },

  exportExcelDataTwo: (filename: string, data: Blob) => {
    ...
  },

  exportExcelDataThree: (filename: string, data: Blob) => {
    ...
  }
}
  • 使用时：
download.exportExcelData("test.xlsx", new Blob());

api 请求

函数注释

  • 每个 api 请求文件上方添加注释，描述 api 请求功能、参数、返回值等信息。

  • 示例：

/**
 * @description: 获取企业列表
 * @param {string} name 企业名称
 * @param {string} region 地区
 * @return {Promise<any>}
 */
const getEnterpriseList = (name: string,region:string) => {
  ...
}

文件区分

  • 根据功能区分文件，例如：enterprise.ts，enterpriseMember.ts。

  • 针对于单个模块 api 很多时，使用文件区分。

  • 示例：

api/
├── enterprise.ts
├── enterpriseMember.ts

使用对象分类

  • 使用对象分类，将每个 api 请求文件分类，不同模块的 api 让如不同对象中。

  • 针对于单个模块 api 不多时，使用对象分类。

  • 示例：

export const enterpriseMember = {
  /**
   * @description: 企业成员列表
   * @param {string} name 企业名称
   * @return {Promise<any>}
   */
  getList: (name: string) => {
    ...
  },
  /**
   * @description: 企业成员详情
   * @param {string} id 企业成员 id
   * @return {Promise<any>}
   */
  detail: (id: string) => {
    ...
  },
  /**
   * @description: 企业成员添加
   * @param {any} data 企业成员数据
   * @return {Promise<any>}
   */
  add: (data: any) => {
    ...
  },
  /**
   * @description: 企业成员编辑
   * @param {any} data 企业成员数据
   * @return {Promise<any>}
   */
  edit: (data: any) => {
    ...
  }
}

文件引入顺序

  • 示例：
// 1. 第三方库和工具函数
import { debounce } from "@/utils";

// 2. 类型定义和枚举
import { PathType, RouteInfo } from "./types";
import { InstallCompType } from "@/enums";

// 3. API 相关导入
import { getEnterpriseList } from "@/service/api/enterprise";
import { getCustomerAcquisition } from "@/service/api/huokeAndQiwei";

// 4. Hooks
import useTable from "@/hooks/common/useTable";

// 5. 组件
import MyMessageBox from "@/components/MyMessageBox";

常见的引入顺序规范

  1. 第三方库导入（包括工具函数）

  2. 类型定义导入

  3. API/服务相关导入

  4. 自定义 hooks 导入

  5. 组件导入

  6. 样式导入（如果有的话）

优点

  1. 依赖关系清晰

  • 从基础依赖到业务代码，层次分明

  • 避免循环依赖问题

  • 容易理解代码的依赖链路

  1. 代码维护性

  • 当需要删除某个功能时，相关的导入很容易找到

  • 添加新功能时，知道应该将导入语句放在哪里

  • 多人协作时，遵循同样的规范，减少代码冲突

  1. 性能优化
// 样式放在最后导入
import "./styles.scss";

  • 有利于打包优化

  • 便于代码分割（Code Splitting）

  • 有助于树摇（Tree Shaking）

  1. 代码评审

  • 评审人员容易理解代码结构

  • 快速发现不合理的依赖关系

  • 保持团队代码风格统一

  1. 问题排查

  • 依赖问题容易定位

  • 版本冲突容易发现

  • 导入路径问题容易解决

  1. 可读性提升
// 相似的导入可以分组
import { ref, reactive } from "vue";
import { watch, computed } from "vue";

// 而不是
import { ref } from "vue";
import { watch } from "vue";
import { computed } from "vue";
import { reactive } from "vue";

  • 代码结构更清晰

  • 相关导入集中管理

  • 减少重复导入

  1. 项目规范化

  • 有助于建立团队代码规范

  • 提高代码质量

  • 便于自动化工具检查（如 ESLint）

最后更新时间:
贡献者: 何风顺