项目结构

Tagtag Starter 项目采用前后端分离架构，包含后端 Java 模块化应用、前端 Vue 3 Monorepo 应用以及完善的文档系统。这种结构设计旨在实现高内聚、低耦合的系统架构，便于维护和扩展。

目录概览

tagtag-starter
├── docs                      # 文档项目 (Nuxt Content)
│   ├── app                   # 文档应用源码
│   ├── content               # 文档内容
│   ├── public                # 静态资源
│   └── nuxt.config.ts        # Nuxt 配置
├── backend                   # 后端项目
│   ├── tagtag-common         # 通用工具层（纯 Java 工具，无 Spring 依赖）
│   ├── tagtag-framework      # 基础设施层（Spring Boot, Security, MyBatis Plus）
│   ├── tagtag-kernel         # 核心业务支持（注解, 枚举, 常量, 上下文）
│   ├── tagtag-contract       # API 定义与契约
│   │   ├── tagtag-contract-auth  # 认证契约
│   │   ├── tagtag-contract-iam   # 身份与访问管理契约
│   │   ├── tagtag-contract-storage # 存储契约
│   │   └── tagtag-contract-system # 系统契约
│   ├── tagtag-module         # 业务实现
│   │   ├── tagtag-module-auth    # 认证模块实现
│   │   ├── tagtag-module-iam     # 身份与访问管理模块实现
│   │   ├── tagtag-module-storage # 存储模块实现
│   │   └── tagtag-module-system  # 系统模块实现
│   ├── tagtag-start          # 应用启动入口与配置
│   └── pom.xml              # 根 Maven POM 文件
└── frontend                 # 前端项目 (Vue 3 + Vite, Monorepo)
    ├── apps                  # 应用入口
    │   └── tagtag           # 主应用
    ├── packages              # 核心包与 UI 组件库
    └── internal              # 构建与工具脚本

后端模块依赖关系

┌─────────────────────────────────────────────────────────────────────────┐
│                           tagtag-start                                 │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼─────────────────────────────────────────────────┐
│  tagtag-module-auth   tagtag-module-iam  tagtag-module-storage  tagtag-module-system │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼─────────────────────────────────────────────────┐
│ tagtag-contract-auth tagtag-contract-iam tagtag-contract-storage tagtag-contract-system │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼─────────────────────────────────────────────────┐
│                           tagtag-kernel                                 │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼─────────────────────────────────────────────────┐
│                           tagtag-framework                              │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼─────────────────────────────────────────────────┐
│                           tagtag-common                                 │
└─────────────────────────────────────────────────────────────────────────┘

后端模块详解

1. 通用工具层 (tagtag-common)

纯 Java 工具类库，不依赖 Spring 框架，提供最基础的工具支持。

主要职责：

• 提供通用工具类（字符串处理、日期处理、Bean 转换等）
• 定义基础数据模型（PageResult, Result, Exception 等）
• 提供基础常量定义
• 提供验证分组定义

核心组件：

• constant/: 基础常量（GlobalConstants）
• enums/: 基础枚举（CodeEnum）
• exception/: 异常类定义（BusinessException, ErrorCode, AssertUtils）
• model/: 基础数据模型（PageQuery, PageRequest, PageResult, Result 等）
• util/: 工具类（DateTimeUtil, EnumUtil, PageUtil, TreeUtil）
• validation/: 验证分组（CreateGroup, UpdateGroup）

2. 框架层 (tagtag-framework)

基础设施集成层，依赖 Spring Boot 和其他第三方库，为上层提供技术支持。

主要职责：

• 集成 Spring Boot 生态组件
• 配置数据库、缓存、安全等基础设施
• 提供全局异常处理和响应封装
• 实现 AOP 切面（日志、限流、操作日志等）

核心组件：

• aop/: 切面实现（RateLimitAspect）
• config/: 配置类（CacheConfig, JacksonConfig, RedisConfig, SecurityConfig 等）
• mapstruct/: MapStruct 配置
• mybatis/: MyBatis Plus 配置和字段自动填充
• security/: Spring Security 配置和 JWT 实现
  • config/: JWT 认证配置
  • context/: 认证上下文管理
  • filter/: 自定义过滤器
  • guard/: 权限守卫（PermissionGuard, RoleGuard）
  • handler/: 自定义认证和授权处理器
  • model/: 安全相关模型
  • service/: JWT 服务和 Token 版本服务
  • strategy/: JWT 解码和签名策略
  • util/: JWT 工具类
• util/: 工具类（PageResults, Pages, WebUtil）
• web/: 全局异常处理、CORS 配置、TraceId 过滤器
  • exception/: 各种异常处理器
  • CorsConfig.java: CORS 配置
  • FilterConfig.java: 过滤器配置
  • TraceIdFilter.java: TraceId 过滤器

3. 核心层 (tagtag-kernel)

核心业务支持层，提供业务开发所需的通用支持和扩展点。

主要职责：

• 定义自定义注解（限流等）
• 提供业务常量和枚举类
• 实现用户上下文管理
• 提供业务 AOP 切面
• 实现安全相关的模型和工具

核心组件：

• annotation/: 自定义注解（@RateLimit, @RequirePerm, @RequireRole）
• constant/: 业务常量（AppMessages, CacheConstants, Permissions, Roles, SecurityClaims, SecurityConstants）
• enums/: 业务枚举（GenderEnum, StatusEnum）

4. 契约层 (tagtag-contract)

API 定义与契约层，采用契约优先设计，将 API 定义与实现分离。

主要职责：

• 定义 API 接口和数据传输对象（DTO）
• 定义视图对象（VO）
• 定义业务枚举和常量
• 定义服务接口

子模块：

tagtag-contract-auth

• 认证相关 API 定义
• 登录、登出、刷新令牌等接口
• 认证相关 DTO 和 VO

tagtag-contract-iam

• 身份与访问管理 API 定义
• 用户、角色、菜单、部门管理接口
• IAM 相关 DTO 和 VO

tagtag-contract-storage

• 存储服务 API 定义
• 文件上传、下载、删除等接口
• 存储相关 DTO 和 VO

tagtag-contract-system

• 系统管理 API 定义
• 字典、消息、系统配置等接口
• 系统相关 DTO 和 VO

5. 模块层 (tagtag-module)

业务实现层，每个模块对应一个具体的业务域，实现契约层定义的接口。

主要职责：

• 实现业务逻辑
• 访问数据库
• 调用其他服务
• 实现控制器

子模块：

tagtag-module-auth

• 认证业务逻辑实现
• 登录、登出、刷新令牌等功能
• JWT 令牌生成和验证

tagtag-module-iam

• 身份与访问管理业务逻辑
• 用户、角色、菜单、部门管理实现
• 权限校验和数据权限控制

tagtag-module-storage

• 存储业务逻辑实现
• 文件上传、下载、删除等功能
• 支持本地存储和云存储

tagtag-module-system

• 系统管理业务逻辑
• 字典、消息、系统配置等功能
• 系统监控和统计

6. 启动层 (tagtag-start)

应用启动入口，聚合所有模块并提供配置文件。

主要职责：

• Spring Boot 主应用类
• 应用配置文件管理
• 环境变量配置
• 依赖管理

核心组件：

• TagtagApplication.java: 主应用类
• resources/application.yml: 主配置文件
• resources/application-dev.yml: 开发环境配置
• resources/application-prod.yml: 生产环境配置
• resources/logback-spring.xml: 日志配置

前端模块详解

tagtag-ui 采用 Monorepo 结构管理，使用 pnpm 作为包管理器，实现代码共享和依赖管理的优化。

Monorepo 设计理念

Monorepo 是一种将多个项目代码存储在单个仓库中的软件架构策略。Tagtag 采用 Monorepo 结构的主要优势包括：

1. 代码共享：多个应用可以共享组件、工具类和配置
2. 统一依赖管理：所有应用使用相同版本的依赖，避免版本冲突
3. 统一构建工具：共享构建配置和脚本，提高开发效率
4. 更好的协作：团队成员可以更方便地共享和复用代码
5. 简化版本管理：统一版本号管理，简化发布流程

1. 应用层 (apps)

包含具体的应用实现，每个子目录对应一个独立的前端应用。

apps/tagtag - 主应用

核心组件：

• src/api/: API 请求定义和封装
  • core/: 核心 API（认证、用户、菜单）
  • modules/: 模块 API（IAM、系统、存储）
• src/views/: 页面视图组件
  • _core/: 核心页面（登录、个人中心、404 等）
  • dashboard/: 仪表盘页面
  • modules/: 模块页面（IAM、系统、存储）
• src/router/: 路由配置
  • routes/: 路由定义
  • access.ts: 路由守卫
  • guard.ts: 权限守卫
• src/store/: Pinia 状态管理
• src/layouts/: 布局组件
• src/components/: 业务组件
• src/locales/: 国际化配置

2. 核心包层 (packages)

提供可复用的核心功能和组件，供应用层使用。

packages/@core - 核心共享库

子模块：

• base: 基础设计系统、图标和共享工具
  • design/: 设计系统和设计令牌
  • icons/: 图标库
  • shared/: 共享工具类
• ui-kit: 封装的 UI 组件库
  • shadcn-ui: 基于 Shadcn UI 的基础组件
  • form-ui: 表单组件封装
  • layout-ui: 布局组件封装
  • popup-ui: 弹窗、抽屉等组件封装
  • tabs-ui: 标签页组件封装
  • menu-ui: 菜单组件封装
• effects: 业务副作用与逻辑封装
  • access: 权限控制逻辑
  • hooks: 通用 Hooks（useTabs, useRefresh, usePagination）
  • request: 请求库封装
  • plugins: 第三方插件集成（Echarts, Motion, Vxe-table）
• preferences: 应用偏好设置管理

packages/effects - 业务副作用与逻辑

• access/: 权限控制实现
• common-ui/: 通用 UI 组件
• hooks/: 业务 Hooks
• layouts/: 布局组件
• plugins/: 插件集成

3. 内部工具层 (internal)

提供构建、开发和维护所需的工具和配置。

核心组件：

• lint-configs/: ESLint, Prettier, Stylelint 等代码规范配置
• vite-config/: Vite 构建配置封装
• tailwind-config/: Tailwind CSS 配置封装
• tsconfig/: TypeScript 配置文件
• node-utils/: Node.js 工具函数

配置文件详解

后端配置

主配置文件 (tagtag-start/src/main/resources/application.yml)

spring:
  application:
    name: tagtag-admin  # 应用名称
    version: 1.0.0      # 应用版本
  profiles:
    active: dev         # 激活的配置文件
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss  # 日期格式
    time-zone: GMT+8    # 时区
  servlet:
    multipart:
      max-file-size: 50MB  # 单个文件最大大小
      max-request-size: 50MB  # 请求最大大小

server:
  port: 8080           # 服务端口
  servlet:
    context-path: /    # 上下文路径

logging:
  config: classpath:logback-spring.xml  # 日志配置文件

mybatis-plus:
  global-config:
    banner: false      # 关闭 MyBatis Plus  banner

# 存储配置
storage:
  local:
    base-path: uploads  # 本地存储基础路径

前端配置

应用配置 (tagtag-ui/apps/tagtag/vite.config.mts)

基于内部封装的 Vite 配置，提供统一的构建配置。

环境配置 (tagtag-ui/apps/tagtag/.env)

# 开发环境
VITE_APP_API_BASE_URL=http://localhost:8080
VITE_APP_TITLE=Tagtag Admin
VITE_APP_SHORT_NAME=Tagtag

Tailwind 配置 (tagtag-ui/internal/tailwind-config/src/index.ts)

统一的 Tailwind CSS 配置，包含主题、插件和自定义工具类。

文档系统

文档系统基于 Nuxt Content 构建，提供现代化的文档阅读体验。

核心组件：

• docs/app/: Nuxt 应用源码
• docs/content/: 文档内容（Markdown 文件）
• docs/nuxt.config.ts: Nuxt 配置

文档结构：

• 1.getting-started/: 入门指南
• 2.architecture/: 架构文档
• 3.developer-guide/: 开发者指南
• 3.modules/: 模块文档
• en/: 英文文档

最佳实践

后端开发最佳实践

1. 遵循分层设计：严格按照通用层、框架层、核心层、契约层、模块层的顺序依赖
2. 契约优先：先定义 API 契约，再实现业务逻辑
3. 使用自定义注解：利用 @OperationLog, @DataPermission 等注解简化开发
4. 统一响应格式：使用 Result 封装 API 响应
5. 异常处理：统一使用自定义异常，由全局异常处理器处理

前端开发最佳实践

1. 组件化开发：将 UI 拆分为可复用的组件
2. 类型安全：充分利用 TypeScript 提供的类型检查
3. 状态管理：合理使用 Pinia 管理应用状态
4. API 封装：统一封装 API 请求，处理错误和认证
5. 国际化：支持多语言切换，使用 locales 目录管理翻译
6. 代码规范：遵循 ESLint、Prettier 等代码规范

目录结构最佳实践

1. 按功能组织代码：将相关功能放在同一个目录下
2. 命名规范：使用清晰、一致的命名约定
3. 避免深层嵌套：目录层级不宜过深，建议不超过 4 层
4. 保持代码精简：避免不必要的文件和代码
5. 文档化：为重要组件和功能编写文档

扩展建议

后端扩展

1. 添加新模块：
   • 在 tagtag-contract 下创建新的契约模块
   • 在 tagtag-module 下创建对应的实现模块
   • 在 tagtag-start 中添加依赖
2. 集成新功能：
   • 在 tagtag-framework 中集成新的基础设施
   • 在 tagtag-kernel 中添加对应的支持
   • 在 tagtag-contract 中定义 API 契约
   • 在 tagtag-module 中实现业务逻辑

前端扩展

1. 添加新组件：
   • 在 packages/@core/ui-kit 中添加新组件
   • 在应用中导入使用
2. 添加新页面：
   • 在 apps/tagtag/src/views 中添加新页面
   • 在 apps/tagtag/src/router 中配置路由
   • 在 apps/tagtag/src/api 中添加 API 定义
3. 添加新功能：
   • 在 packages/effects 中添加新的副作用逻辑
   • 在 packages/@core/hooks 中添加新的 Hooks
   • 在应用中使用新功能