V8程序

Appearance

VUE3 项目最佳实践 ​

VUE3 项目最佳实践

待完善...

一、技术栈 ​

  • VUE3:

    使用 Vue 3 框架进行前端开发，利用其更强大的响应式系统和性能优化特性。

  • Typescript:

    使用 TypeScript 进行静态类型检查，提高代码的可维护性和安全性。

  • axios:

    使用 axios 进行 HTTP 请求，处理数据的获取和发送。

  • Pinia:

    使用 Pinia 进行状态管理，充分利用 Composition API 提供的状态管理特性。

  • VUE-router:

    利用 Vue Router 进行路由管理，实现单页面应用（SPA）的导航控制。

  • Element-plus:

    使用 Element Plus 作为 UI 框架，提供丰富的组件库，美化用户界面。

  • ESLint:

    使用 ESLint 进行代码规范检查，确保代码风格一致性。

  • Prettier:

    利用 Prettier 进行代码格式化，提高代码的可读性。

  • Jest 或其他测试框架:

    选择 Jest 或其他测试框架进行单元测试和端到端测试，确保代码质量和可维护性。

二、项目结构和组织 ​

1）Composition API（Hooks 形式） ​

项目采用 Composition API 的形式组织代码，将逻辑按照功能划分为不同的模块，每个模块包含其相关的状态、计算属性、方法等。

src
|-- components            # 公共组件
|-- hooks                 # 自定义 hooks
|-- views                 # 页面视图组件
|-- services              # 服务层，处理业务逻辑和数据请求
|-- store                 # Pinia 状态管理相关文件
|-- utils                 # 工具函数
|-- App.vue               # 根组件
|-- main.ts               # 入口文件
|-- router.ts             # 路由配置文件
|-- ...

2）文件命名与命名规范 ​

为了保持项目的一致性和可维护性，采用以下文件命名规范：

  • 组件文件： 采用 PascalCase 命名规范，例如 MyComponent.vue。

  • 自定义 hooks 文件： 采用 camelCase 命名规范，例如 useSomeFeature.ts。

  • 服务层文件： 采用 PascalCase 命名规范，例如 DataService.ts。

  • 状态管理文件： 采用 PascalCase 命名规范，例如 UserStore.ts。

  • 工具函数文件： 采用 camelCase 命名规范，例如 utils.ts。

  • 入口文件： main.ts 作为项目的入口文件。

3）模块化开发 ​

通过模块化开发，将相关的组件、视图、服务、状态管理等文件组织在一起，提高代码的可读性和可维护性。

src
|-- modules
|   |-- feature1          # 某个功能模块
|   |   |-- components    # 该模块的组件
|   |   |-- views         # 该模块的页面视图组件
|   |   |-- services      # 该模块的服务层
|   |   |-- store         # 该模块的状态管理
|   |   |-- ...
|   |
|   |-- feature2          # 另一个功能模块
|       |-- components    # 该模块的组件
|       |-- views         # 该模块的页面视图组件
|       |-- services      # 该模块的服务层
|       |-- store         # 该模块的状态管理
|       |-- ...
|
|-- App.vue               # 根组件
|-- main.ts               # 入口文件
|-- router.ts             # 路由配置文件
|-- ...

4）统一配置管理 ​

将项目的配置信息集中管理，例如接口地址、常量等，以便于统一修改和维护。可以创建一个 config 目录，包含不同环境下的配置文件。

src
|-- config
|   |-- index.ts         # 配置文件的入口，根据环境引入相应配置
|   |-- dev.ts           # 开发环境配置
|   |-- prod.ts          # 生产环境配置
|   |-- ...
|
|-- ...

5）测试 ​

在项目中引入测试，保证代码的质量和稳定性。使用 Jest 或其他适合项目的测试框架进行单元测试、集成测试等。

tests
|-- unit                 # 单元测试
|   |-- components       # 组件测试
|   |-- utils            # 工具函数测试
|   |-- ...
|
|-- e2e                  # 端到端测试
|   |-- scenarios        # 测试场景
|   |-- ...
|
|-- ...

6）静态资源 ​

将项目中使用的静态资源（如图片、字体等）放置在统一的目录，便于管理和引用。

public
|-- assets
|   |-- images
|   |-- fonts
|   |-- ...
|
|-- ...

7）样式管理 ​

采用一致的样式管理方式，可以使用预处理器（例如 Sass、Less）来组织样式文件。

src
|-- styles
|   |-- variables.scss    # 全局样式变量
|   |-- mixins.scss       # 样式混合
|   |-- ...
|
|-- ...

8）文档 ​

为项目编写文档，包括组件文档、使用说明等，以提高代码的可理解性和可维护性。

docs
|-- components           # 组件文档
|-- usage                # 使用说明
|-- ...

三、全局配置 ​

1）全局配置文件： ​

  • tsconfig.json: TypeScript 配置文件，定义编译选项和类型检查规则。
  • vue.config.js: Vue CLI 配置文件，用于配置构建、开发服务器等相关选项。
  • .eslintrc.js: ESLint 配置文件，定义代码规范和检查规则。
  • .prettierrc: Prettier 配置文件，定义代码格式化规则。
  • jest.config.js: Jest 配置文件，用于配置测试环境和测试脚本。

2）配置 setup 语法糖模版 ​

3）TypeScript 配置 ​

4）ESLint 配置 ​

5）Prettier 配置 ​

6）全局样式文件 ​

7）vue3+vite ＜ script setup ＞ 配置 name 属性 ​

jsx
// 首先安装插件
npm i vite-plugin-vue-setup-extend -D

// vite.config.ts 引入
import vueSetupExtend from 'vite-plugin-vue-setup-extend'


export default {
    plugins: [vue(), vueSetupExtend()],
}

// vue组件
<script setup  lang="ts" name="simpleTemp"> 直接使用

四、最佳实践清单 ​

1）响应式与状态管理 ​

  • 使用 ref 和 reactive 进行响应式数据的定义，确保数据的双向绑定和自动更新。
  • 避免在模板中直接修改响应式数据，使用计算属性或方法进行修改。
  • 利用 Pinia 进行状态管理，将状态和相关操作封装在 store 中，使用 defineStore 创建 store。

2）组件通信 ​

  • 使用 @emit 或自定义事件进行父子组件通信，确保组件解耦。
  • 采用事件总线或其他状态管理工具进行兄弟组件通信。
  • 避免在模板中直接编写复杂的逻辑，将逻辑封装为方法或计算属性。
  • 统一事件处理函数的命名规范，使用清晰且语义化的命名方式。
  • 使用对象或事件对象来传递多个参数，提高代码的可读性。
  • 根据实际情况选择合适的组件通信模式，如使用 Vuex 进行全局状态管理，或者采用事件总线来简化组件之间的通信。

3）代码组织与可维护性 ​

  • 将大型组件拆分成更小、更可维护的子组件，利用插槽（slots）来实现更灵活的组件组合。
  • 提取可复用的逻辑部分，将其封装成函数或自定义 hooks，以便在不同组件中共享。
  • 对于复杂逻辑或关键算法，添加清晰的注释，解释代码的用途、实现细节和可能的边界情况。
  • 为重要的组件、模块和公共方法编写文档，包括使用示例、参数说明和返回值等。

4）错误处理与日志记录 ​

  • 在合适的地方进行错误处理，确保程序在发生异常时有适当的反馈或降级策略。
  • 集成前端错误监控工具，及时捕获并报告前端错误，以便快速修复。
  • 在关键逻辑、重要操作或异常处理中添加日志记录，以便在出现问题时能够更好地进行排查和调试。

5）性能优化 ​

  • 对于大型应用，考虑采用懒加载（lazy loading）和异步加载来减少初始加载时间。
  • 在处理大量数据时，考虑使用虚拟列表来提高列表性能，只渲染当前可见区域的数据。

6）路由管理 ​

  • 统一采用语义化的路由命名，便于理解和维护。
  • 使用路由参数来传递动态数据，而不是直接从组件中访问 $route 对象。
  • 合理使用路由守卫进行导航控制，确保用户在访问需要登录权限的页面时已登录，或者在离开页面时进行必要的数据保存。

7）国际化与安全性 ​

  • 集成国际化插件，以支持多语言切换，使用统一的翻译管理机制。
  • 避免直接在模板中插入不受信任的内容，使用 v-html 时谨慎处理用户输入。
  • 对于涉及到用户敏感操作的请求，采用合适的 CSRF 防范措施，例如在请求头中添加 token。

8）UI/UX 设计一致性 ​

  • 遵循设计系统，保持应用的整体 UI 风格一致，包括颜色、字体、间距等。
  • 确保应用在不同屏幕尺寸下具有良好的响应式布局，提供流畅的用户体验。

9）版本管理与发布流程 ​

  • 采用合适的 Git 分支策略，例如主分支（main）、开发分支（develop）、特性分支等，规范团队的代码协作流程。
  • 遵循语义化版本号规范，明确版本号的意义，方便团队和用户理解版本迭代的含义。
  • 配置持续集成和持续交付流程，确保代码的自动化构建、测试和部署，降低发布过程中的错误风险。

10）监控与性能优化 ​

  • 集成性能监控工具，定期分析和优化应用的性能，确保用户体验良好。
  • 使用错误监控工具捕获前端错误，及时发现并修复潜在问题。

11）异步流程管理与状态持久化 ​

  • 使用 async/await 或 Promise 等机制管理异步流程，提高代码的可读性和维护性。
  • 在异步操作中适当处理错误，确保不会因为异步操作而导致应用崩溃或出现不可预料的问题。
  • 考虑使用持久化存储（如 localStorage 或 sessionStorage）来保存一些需要在页面刷新后保持的状态，以提升用户体验。

12）前后端接口规范与数据格式规范 ​

  • 遵循 RESTful API 设计原则，使后端接口具有良好的结构和规范。
  • 统一前后端错误码和错误信息，便于前端进行错误处理和用户提示。
  • 规定前后端之间的数据交互格式，例如统一使用 JSON 格式，确保数据的一致性。

13）打包优化与移动端适配 ​

  • 使用代码分割（Code Splitting）来拆分大型应用，按需加载模块，减小首屏加载时间。
  • 利用 Tree-shaking 特性，消除未使用的代码，减小打包体积。
  • 针对不同移动设备的屏幕尺寸和分辨率，采用响应式设计，确保在各种设备上都能正常展现。
  • 在移动端开发中使用合适的触摸事件，提高用户交互体验。

14）代码安全性与环境配置 ​

  • 使用安全库来防范常见的安全漏洞，例如防止 XSS 攻击。
  • 在前端进行基本的权限控制，防止未授权用户访问敏感数据或执行敏感操作。
  • 配置不同环境下的参数，例如开发、测试、生产环境的接口地址、域名等。
  • 避免将敏感信息（如密钥、密码）硬编码在代码中，使用安全的方式进行配置和管理。

15）用户体验优化 ​

  • 在数据加载或操作耗时时，使用加载动画提升用户等待体验。
  • 对于频繁访问的页面，考虑使用页面缓存策略，提高页面访问速度。