腾龙开发底座

主题

项目架构概览 ​

简介 ​

在本项目中，我们采用了一个多应用的架构，旨在促进模块化开发和资源复用。项目根目录下包含若干公共配置文件和工具，如 config 目录下的 vite 和 eslint 配置文件， 这些都可供所有应用共同使用。这样的架构设计不仅方便了项目的管理和维护，而且使得各应用能够以最简化的方式复用项目内的资源和组件。随着框架的持续完善，应用间将实现 更紧密的互相引用和融合，甚至可将其他项目内的应用引入当前项目中复用。

模块划分概述

  • apps 应用目录，包含各独立应用的文件
  • packages 公共配置目录，存放可跨应用共用的组件和工具
  • scripts 脚本工具目录，涵盖项目构建或维护过程中需要的脚本
  • configs 配置文件目录，提供vite、eslint等工具的配置文件，便于统一管理

项目目录详细介绍 ​

项目的文件结构如下所示，为开发者提供了一个清晰、易于管理的工作环境：

bash
.
├── CHANGELOG.md          #更新日志
├── README.md             #README说明文件
├── apps                  #应用目录
│   └── admin             #应用
├── changelog.config.ts   #changelog 配置文件
├── configs               #公用配置文件
│   ├── eslint-config     #eslint公用配置
│   ├── stylelint         #stylelint配置
│   ├── tsconfig          #tsconfig配置
│   └── vite              #vite配置
├── eslint.config.js      #eslint配置
├── package.json          #项目配置文件
├── packages              #公用目录
│   ├── components        #公用组件
│   ├── composables       #公用hooks(vue称为composable)
│   ├── directives        #公用指令
│   └── utils             #公用工具
├── pnpm-lock.yaml        #pnpm依赖锁
├── pnpm-workspace.yaml   #pnpm工作区配置
├── scripts               #脚本工具
│   ├── cmd               #命令行工具
│   └── script            #脚本工具
├── stylelint.config.js   #stylelint配置
├── turbo.json            #turbo配置
└── vitest.config.ts      #vite配置

项目模块具体说明 ​

提示

如果需要创建新的模块，可以查看 工作区/创建工作区

apps ​

应用复用待上线

应用内的业务页面整体通过微前端 的形式在其他应用直接引用

  • 主要的工作目录，包含项目内的所有应用。
  • 应用模板及其他由研发云提供的模板工程也位于此目录下，如“权限管理系统”等。
  • 应用间可通过工程插件进行资源共享和功能复用。

基础应用 ​

一个全面的基础应用框架，整合了用户认证体系，并配备了登录界面、404错误页面、403访问受限页面等核心功能页面。它不仅提供了一系列基本功能，如动态主题切换、多语言支持、综合的全局配置选项以及精细的权限控制机制，而且旨在为业务代码的开发提供一个坚实的起点。该框架设计为一个可直接应用的业务模板，允许开发者在此基础上快速扩展，无缝衔接自身的业务需求，极大地加速了项目的初始开发过程，同时保证了代码的可维护性和扩展性。

提示

你可以将基础应用当做一个主应用，通过微前端的形式引入其他应用的页面组，实现多应用的聚合。

权限管理系统 beta ​

权限管理系统是一个完整的权限管理系统模板，包含了用户管理、角色管理、权限管理、资源管理等功能，这套模板不仅可以直接应用于现有的项目中，实现高效且灵活的权限控制策略，还可以作为开发的基础，支持二次开发以满足更加个性化的需求。无论是直接使用还是基于此进行扩展，它都能大幅度缩短开发周期，同时确保系统的安全性和可维护性。

packages ​

  • 包含项目内可复用的资源，如 components、composables、 directives 、utils。
  • components 和 composables 可直接在应用中使用，而 directives 和 utils 则需要在应用中显式引入。

自动导入机制介绍

在Vue项目中，我们经常使用两个非常有用的插件来简化开发流程：unplugin-auto-import 和 unplugin-vue-components。虽然这两个插件的功能看起来相似，它们实际上服务于不同的目的：

  • unplugin-auto-import 主要用于自动导入Vue单文件组件(SFC)的<template>标签内使用的组件。它通过扫描SFC文件并利用内部的resolvers规则，自动识别并导入需要的组件，从而减少手动导入组件的需求。
  • unplugin-vue-components 则关注于SFC的 <script> 部分，特别是那些在脚本中使用的Vue函数或组合式API。通过同样的机制，它能自动侦测并导入这些函数，简化开发者的导入流程。

为了实现上述功能，我们需要为这两个插件配置相应的 resolvers 规则。这样做能够确保位于 composables 和 components 目录下的资源都能被智能地、自动地导入到我们的项目中，进一步提高开发效率和体验。

@pubinfo/components ​

组件导出按照统一前缀 Pub 导出，应用内会通过 vite 插件 unplugin-vue-components 自动注册为应用全局组件

ts
// 按照如下 PubTestDemo 方式导出, 组件名称必须已Pub开头
export { default as PubTestDemo } from './TestDemo/index.vue'

// 全局组件导出
export { default as PubSvgIcon } from './SvgIcon/index.vue'
export { default as PubFixedActionBar } from './FixedActionBar/index.vue'
export { default as PubListLayout } from './LayoutContainer/index.vue'
export { default as PubPageHeader } from './PageHeader/index.vue'
export { default as PubPageMain } from './PageMain/index.vue'
export { default as PubSearchBar } from './SearchBar/index.vue'
export { default as PubTrend } from './Trend/index.vue'

注意事项

此处仅用于全局组件，避免包含任何业务逻辑或全局状态。若组件涉及特定业务逻辑， 请在应用的components目录中创建。对于与业务逻辑紧密相关且复用频率极高的组件， 应当将其与应用一同导出。例如，涉及获取用户信息的弹窗组件，应从rbac（权限管理系统）中导出以便在其他应用中复用。 这种做法是因为高度耦合的业务组件往往与接口和全局状态密切相关，将其与特定应用绑定更加合理明晰

@pubinfo/composables ​

在composables目录下的按照约定定义的hook会被 unplugin-auto-import 自动导入到应用内，无需手动引入，直接使用即可

ts
// TestDemo/index.ts
// 取名需要以 usePub开头,会被vite自动抓取，导入apps/*

export function usePubTestDemo1() {
  console.log('usePubTestDemo1')
}
export function usePubTestDemo2() {
  console.log('usePubTestDemo2')
}
ts
// index.ts
export * from './TestDemo'
vue
<route lang="yaml">
meta:
  title: 导航1
</route>

<script  setup lang="ts">
usePubTestDemo1() // usePubTestDemo1
usePubTestDemo2() // usePubTestDemo2
</script>

<template>
  <div>
    <PubPageMain>
      多级导航1
    </PubPageMain>
  </div>
</template>

@pubinfo/directives ​

指令导出按照统一前缀 Pub 导出，应用内自动引入

ts
import type { ObjectDirective } from 'vue'
import mediumZoom from 'medium-zoom'

const zoomable: ObjectDirective = {
  mounted: (el) => {
    mediumZoom(el, {
      background: 'rgba(0, 0, 0, 0.5)',
      scrollOffset: 0,
      margin: 80,
    })
  },
}

export { zoomable }
ts
export { zoomable as PubZoomable } from './ZoomAble'

提示

因为是用的自动引入，没有使用vue插件的方式，没有使用 install 注册，所以指令我们写的都是 ObjectDirective类型

configs ​

存放项目的公共配置文件，如vite、eslint、stylelint、tsconfig，使各应用能够共享同一套配置，确保代码风格和构建配置的一致性。

@pubinfo/eslint ​

ESLint 是一个开源的代码静态代码分析工具，主要用于发现代码中的问题，统一代码风格，以及避免一些常见的错误。它允许开发者定义一系列可扩展的规则，这些规则可以帮助维持代码的质量和一致性，从而提升整个团队的开发效率。

通过对代码进行静态分析，ESLint能够在代码执行前就识别出潜在的逻辑错误、不符合规范的代码风格、未使用的变量等问题，极大地减少了调试和维护的工作量，虽然 ESLint 的强大功能使其成为了现代Web开发不可或缺的一部分，但其配置的复杂性和学习曲线却经常成为开发者的挑战，@pubinfo/eslint-config 集成了一套完善的 ESLint 配置，旨在为开发者提供一套高效、规范的代码质量保障方案。

在本项目中，ESLint 被配置为一个核心的质量保障工具，覆盖了从基础的 JavaScript 和 TypeScript 语法规范，到 Vue 特定代码风格的各个方面。这一策略旨在确保代码不仅在逻辑上正确无误，同时也拥有良好的可读性和一致的风格。此外，ESLint 还扩展到了更细节的层面，如 jsdoc 注释的标准化，以确保代码文档的质量；imports 的管理，以优化模块之间的依赖关系；还有对markdown、node 环境、以及yaml 配置文件的规范，保证了项目文档和配置的整洁和一致性。

项目中的 ESLint 配置不仅仅采用了业界公认的最佳实践，还根据项目的具体需求进行了定制化的扩展。这包括对Vue 组件和 TypeScript 特性的深入整合，确保了框架和语言的特性能被充分利用，同时也保留了开发过程中的灵活性。例如，通过自定义的规则优化了组件导入路径的解析，使得项目结构更为清晰，依赖管理更加高效。此外，还强化了对代码注释和文档编写的规范，不仅提升了代码的自述性，也便于团队成员之间的沟通和协作。

为了进一步提升代码质量和开发效率，项目还采纳了创新性的编码规则，如 unicorn 规则集，这些规则代表了前沿的编程实践，旨在通过严格的代码标准推动代码质量的持续提升。

在根目录下 eslint.config.ts 引用了 @pubinfo/eslint-config 配置，具体规范细节请查看 前端开发规范

ts
import pubinfo from '@pubinfo/eslint-config'

export default pubinfo()

@pubinfo/stylelint ​

在确保项目中 CSS/SCSS 代码质量和风格一致性方面，引入了 Stylelint 作为关键工具。Stylelint，与 ESLint 在 JavaScript 领域的作用相似，是一个强大的样式表静态分析工具，旨在帮助开发者发现样式代码中的问题，统一代码风格，提高代码的可维护性和可读性。Stylelint 的配置灵活性允许它通过一系列可扩展的规则集来适应不同的项目需求，但正因为其高度的可配置性，配置 Stylelint 成为了一项技术挑战，尤其是在追求细致的代码风格一致性和高质量标准的项目中。

本项目采用了一系列行业公认的 Stylelint 配置，如 stylelint-config-standard-scss、stylelint-config-standard-vue/scss、以及 stylelint-config-recess-order，这些配置为 SCSS和 Vue 项目中的样式代码提供了基础的规范和排序规则。这样的配置集成了多个社区认可的最佳实践，为项目样式代码的编写提供了坚实的基础。

然而，仅仅依靠预设的规则集往往无法完全满足项目的具体需求和团队的独特编码习惯。因此，除了采用上述标准配置之外，还进行了精细的自定义配置。这些自定义配置包括针对项目特定的样式指南的规则定义，如颜色值、字体定义、边距和填充的使用规范等，以及对 SCSS 混合宏和函数的命名和使用方式的约束。

在根目录下 stylelint.config.js 继承了 @pubinfo/stylelint 配置

js
export default {
  extends: [
    '@pubinfo/stylelint',
  ],
}

@pubinfo/vite ​

在 @pubinfo/vite 中封装了基本常用的配置，让应用无语配置开箱即用，同时也可以根据项目需求进行个性化配置。

配置文件会和应用的配置文件进行深度合并，以保证应用的配置文件不会被覆盖。

ts
import { defineConfig } from '@pubinfo/vite'

// 配置文件将会深度合并
export default defineConfig({
  build: {
    outDir: 'rbac',
  },
})

scripts ​

包含各种辅助项目构建和维护的脚本工具，如命令行工具 cmd、其他脚本 script等，以提升开发效率。

应用目录介绍 ​

提示

应用的各个模块功能会再后面的文档中详细介绍

bash
.
├── index.html
├── openapi.config.ts                   #openapi配置文件
├── package.json                        #应用配置文件
├── postcss.config.js                   #postcss配置文件
├── public                              #静态资源目录
├── src
│   ├── App.vue                         #根组件
│   ├── api                             #api目录
│   ├── assets                          #资源目录
│   │   ├── fonts                       #字体目录
│   │   ├── icons                       #图标目录
│   │   ├── images                      #图片目录
│   │   └── styles                      #样式目录
│   ├── components                      #组件目录，会自动注册为全局组件
│   ├── composables                     #hooks目录，会在使用的时候自动引入
│   ├── directive                       #指令目录
│   ├── layouts                         #主布局组件
│   ├── locales                         #国际化目录
│   ├── main.ts                         #入口文件
│   ├── mock                            #mock目录
│   ├── router                          #路由目录
│   │   ├── constant.ts                 #固定路由，例如登录、404等系统路由
│   │   ├── guard                       #路由守卫
│   │   │   ├── afterEach.ts            #全局后置守卫
│   │   │   ├── beforeEach.ts           #全局前置守卫
│   │   │   └── index.ts                #路由守卫入口
│   │   ├── index.ts                    #路由入口
│   │   ├── modules                     #路由模块，页面路由再此处维护
│   │   ├── plugins                     #路由插件，例如进度条等
│   │   │   └── nprogress.ts            #进度条插件
│   │   ├── routes.ts                   #路由配置
│   │   └── utils                       #路由工具
│   │       └── createRouter.ts
│   ├── settings.default.ts             #应用默认设置
│   ├── settings.ts                     #应用设置，会和默认设置合并
│   ├── store                           #Pinia目录
│   │   ├── enum                        #Pinia模块枚举目录
│   │   │   └── index.ts                #Pinia模块名称枚举
│   │   ├── index.ts                    #Pinia入口
│   │   └── modules
│   │       ├── favorites.ts            #收藏模块
│   │       ├── iframe.ts               #iframe模块
│   │       ├── keepAlive.ts            #keepAlive模块
│   │       ├── menu.ts                 #菜单模块
│   │       ├── notification.ts         #通知模块
│   │       ├── route.ts                #路由模块
│   │       ├── settings.ts             #设置模块
│   │       ├── tabbar.ts               #标签栏模块
│   │       └── user.ts                 #用户模块
│   ├── utils                           #工具目录
│   └── views                           #页面目录
├── themes                              #主题目录
│   ├── antDesign                       #antDesign主题
│   │   └── token.ts                    #antDesign主题配置文件
│   ├── index.ts                        #主题入口
│   ├── presetThemes.ts                 #Unocss预设主题
│   ├── system                          #系统主题
│   │   ├── dark                        #暗黑主题
│   │   │   ├── dark.ts
│   │   │   ├── dracula.ts
│   │   │   ├── luxury.ts
│   │   │   ├── night.ts
│   │   │   ├── stone.ts
│   │   │   └── synthwave.ts
│   │   └── light                       #亮色主题
│   │       ├── barbie.ts
│   │       ├── classic.ts
│   │       ├── cyberpunk.ts
│   │       ├── light.ts
│   │       ├── naive.ts
│   │       └── winter.ts
│   └── utils.ts
├── tsconfig.json                       #tsconfig配置文件
├── tsconfig.node.json                  #tsconfig配置文件
├── types                               #类型目录
├── uno.config.ts                       #uno配置文件
└── vite.config.ts                      #vite配置文件