Architecture

架构概览

Tagtag Starter 架构的高层概览。

Tagtag Starter 采用现代化的前后端分离架构，前端负责用户交互与界面展示，后端负责业务逻辑与数据处理。系统设计遵循模块化、高内聚、低耦合的原则，便于扩展和维护。简单来说，就是把事情分清楚，各司其职，别乱来。

总体架构

架构图

┌─────────────────────────────────────────────────────────────────────────┐
│                           客户端 (Browser)                              │
└─────────────────────────────────────────────────────────────────────────┘
                                    │ HTTPS/HTTP
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           前端应用 (frontend)               │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐ │
│  │  路由层 │  │  视图层 │  │  组件层 │  │  状态层 │  │  API 客户端层    │ │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
                                    │ RESTful API (JSON)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           后端应用 (Spring Boot)                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐ │
│  │  控制层 │  │  服务层 │  │  业务层 │  │  数据层 │  │  基础设施层      │ │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           数据存储层                                    │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │  MySQL  │  │  Redis  │  │  MinIO  │  │ 其他存储 │                     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘                     │
└─────────────────────────────────────────────────────────────────────────┘

Tagtag Starter 系统由以下两个主要部分组成：

前端 (Frontend): 位于 frontend 目录。基于 Vue 3 + Vite + TypeScript 构建的现代化单页应用 (SPA)，采用了 Vben Admin 5 框架，使用 Tailwind CSS 和 Shadcn UI 进行界面开发。界面美观，交互流畅，用户体验一级棒。
后端 (Backend): 位于 backend 目录下的多个 Java 模块。基于 Spring Boot 构建的模块化应用，负责提供 RESTful API 和数据持久化服务。稳定可靠，性能卓越，就像老黄牛一样任劳任怨。

交互方式

通信协议: 前后端通过 HTTP/HTTPS 协议进行通信，采用 RESTful API 风格。简单、标准、易理解。
数据格式: 统一使用 JSON 格式进行数据交换。轻量、易读、易解析。
认证机制: 使用 JWT (JSON Web Token) 进行无状态身份验证。安全、高效、无状态。

前后端交互流程

用户认证流程：
- 用户访问前端应用，输入用户名和密码
- 前端调用登录 API，发送认证请求
- 后端验证用户名和密码，生成 JWT 令牌
- 前端存储 JWT 令牌，后续请求携带令牌
这个过程就像去银行取钱，先验证身份，拿到凭证，然后就可以凭凭证办理业务了。
API 请求流程：
- 前端发起 API 请求，携带 JWT 令牌
- 后端过滤器验证令牌有效性
- 控制器接收请求，调用服务层处理业务逻辑
- 服务层调用数据层访问数据库
- 数据层返回结果，服务层封装业务响应
- 控制器返回 JSON 响应给前端
- 前端处理响应，更新界面
这个流程就像点外卖，您下单（前端请求），商家接单（控制器），厨师做饭（服务层），打包（数据层），配送（返回响应），最后您收到外卖（前端处理）。
WebSocket 实时通信（可选）：
- 前端建立 WebSocket 连接，携带认证信息
- 后端验证并建立连接
- 双方通过 WebSocket 进行实时数据交换
这就像打电话，建立连接后，双方可以随时说话，不用每次都重新拨号。

技术选型理由

后端技术栈

技术	版本	选型理由
Spring Boot	3.x	现代化 Java 应用开发框架，提供自动配置、内嵌服务器等特性，简化开发流程。让开发者专注于业务逻辑，而不是配置文件。
Java JDK	17	LTS 版本，提供更好的性能、安全性和新特性支持。用最新的技术，写最稳的代码。
MyBatis Plus	3.x	简化 MyBatis 开发，提供代码生成、分页插件、逻辑删除等功能。少写代码，多摸鱼（开玩笑的）。
Redis	6.x	用于缓存、会话管理和分布式锁，提高系统性能。让系统飞起来。
Spring Security	6.x	强大的安全框架，支持 JWT 认证和权限控制。安全第一，别让黑客有机可乘。
MySQL	8.x	稳定可靠的关系型数据库，适合存储结构化数据。数据存储的基石，数据都靠它。

前端技术栈

技术	版本	选型理由
Vue 3	3.x	响应式前端框架，提供 Composition API，更好的类型支持和性能。用最新的框架，写最优雅的代码。
TypeScript	5.x	静态类型检查，提高代码质量和开发效率。让 bug 无处遁形。
Vite	5.x	现代化前端构建工具，提供快速的开发体验和优化的生产构建。开发体验一级棒，启动速度嗖嗖的。
Pinia	2.x	Vue 3 官方状态管理库，简洁易用，支持 TypeScript。状态管理，就这么简单。
Vue Router	4.x	Vue 官方路由管理库，支持组件级路由和嵌套路由。页面跳转，轻轻松松。
Tailwind CSS	3.x	实用优先的 CSS 框架，提高样式开发效率，支持响应式设计。不用写一堆 CSS 文件了。
Shadcn UI	最新	可定制的 UI 组件库，基于 Tailwind CSS，提供现代化的设计风格。界面美观，交互流畅。
pnpm	10.x	高效的包管理器，支持 Monorepo 结构，节省磁盘空间和安装时间。比 npm 更快，用过都说好。

后端架构

Tagtag Starter 后端遵循严格的多模块架构，以分离基础设施、业务逻辑和 API 定义。这种设计使得系统各部分职责清晰，便于维护和扩展。简单来说，就是把事情分清楚，各司其职，别乱来。

注意：以下描述均在 cd backend 后的目录结构基础上进行说明。

后端模块依赖关系

┌─────────────────────────────────────────────────────────────────────────┐
│                           启动层 (tagtag-start)                          │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           模块层 (tagtag-module-*)                       │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           契约层 (tagtag-contract-*)                     │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────┼─────────────────────────────────────────────────┐
│                           核心层 (tagtag-kernel)                         │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────┼─────────────────────────────────────────────────┐
│                           框架层 (tagtag-framework)                      │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────┼─────────────────────────────────────────────────┐
│                           通用层 (tagtag-common)                         │
└─────────────────────────────────────────────────────────────────────────┘

后端分层设计

后端项目组织为以下几个层级：

1. 通用层 (`tagtag-common`)

纯工具类，无 Spring 依赖，可独立于 Spring 框架使用。

常量定义
异常类
基础模型 (PageResult, Result)
工具类 (BeanUtils, StringUtils, DateUtils)
这一层就像工具箱，里面装着各种工具，谁都可以拿来用，不用担心依赖问题。

2. 框架层 (`tagtag-framework`)

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

MyBatis Plus 配置与扩展
Redis 配置与工具类
Spring Security & JWT 认证机制
- JWT 服务与策略
- 权限守卫
- 认证上下文管理
全局异常处理
切面定义 (RateLimit)
全局响应封装
MapStruct 配置
Web 配置 (CORS, TraceId)
这一层就像地基，为上层提供稳定的技术支持。没有这一层，上层就建不起来。

3. 核心层 (`tagtag-kernel`)

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

自定义注解 (@RateLimit, @RequirePerm, @RequireRole)
枚举定义 (Status, Gender)
业务常量与错误码
安全相关常量和声明
这一层就像核心业务规则，定义了业务开发的基本规范和约束。

4. 契约层 (`tagtag-contract`)

定义模块间的接口和数据结构，采用契约优先设计。

DTOs: 用于 API 输入/输出的数据传输对象。
API 接口: 定义服务契约的 Java 接口。
VO: 视图对象，用于前端展示的数据封装。
枚举: 业务相关的枚举定义。
这一层就像合同，定义了各方（模块）之间的接口和数据结构。有了合同，大家就知道该怎么合作了。

5. 模块层 (`tagtag-module`)

实际的业务实现，每个模块对应一个具体的业务域。

控制器 (Controllers): 处理 HTTP 请求，调用服务层。
服务实现 (Service Implementations): 实现业务逻辑。
实体类 (Entities): 映射到数据库表的实体。
映射器 (Mappers): 数据库操作接口。
业务模型: 领域模型和业务规则。
这一层就像各个部门，每个部门负责自己的业务，各司其职。

6. 启动层 (`tagtag-start`)

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

Spring Boot 主应用类
配置文件 (application.yml)
环境变量配置
依赖管理
这一层就像公司大门，所有模块都从这里进出。

后端模块设计原则

高内聚，低耦合：每个模块只负责一个业务域，模块间通过契约层通信。就像各个部门，各司其职，通过合同（契约层）合作。
依赖倒置：高层模块依赖于抽象，不依赖于具体实现。就像老板依赖合同，而不是依赖具体的员工。
开闭原则：对扩展开放，对修改关闭。就像软件升级，可以加新功能，但不能改旧功能。
单一职责：每个类和方法只负责一个功能。就像一个人只负责一件事，不会什么都干。
分层设计：严格遵循分层架构，不跨层调用。就像公司层级，不能越级汇报。

前端架构

Tagtag Starter 前端采用现代化的 Monorepo 结构，基于 Vben Admin 5 框架构建，旨在提供高效、可扩展的前端开发体验。简单来说，就是把前端代码组织得井井有条，方便管理和维护。

注意：以下描述均在 cd frontend 后的目录结构基础上进行说明。

前端架构图

┌─────────────────────────────────────────────────────────────────────────┐
│                           应用层 (apps)                                 │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │  路由层 │  │  视图层 │  │  组件层 │  │  状态层 │                     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘                     │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           核心包层 (packages)                           │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │  UI组件 │  │  Hooks  │  │  工具类 │  │  服务层 │                     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘                     │
└─────────────────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           内部工具层 (internal)                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │  构建工具│  │  代码规范│  │  配置文件│  │  脚本工具│                     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘                     │
└─────────────────────────────────────────────────────────────────────────┘

核心技术栈

技术	版本	用途
Vue 3	3.x	响应式前端框架，提供 Composition API。用最新的框架，写最优雅的代码。
TypeScript	5.x	静态类型检查，提高代码质量。让 bug 无处遁形。
Vite	5.x	现代化前端构建工具，提供快速的开发体验。开发体验一级棒，启动速度嗖嗖的。
Pinia	2.x	Vue 3 官方状态管理库。状态管理，就这么简单。
Vue Router	4.x	Vue 官方路由管理库。页面跳转，轻轻松松。
Tailwind CSS	3.x	实用优先的 CSS 框架，提高样式开发效率。不用写一堆 CSS 文件了。
Shadcn UI	最新	可定制的 UI 组件库，基于 Tailwind CSS。界面美观，交互流畅。
pnpm	10.x	高效的包管理器，支持 Monorepo 结构。比 npm 更快，用过都说好。

模块划分

前端项目主要分为三个层级：

1. 应用层 (`apps`)

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

apps/tagtag: 主应用程序，包含完整的业务逻辑和界面。
- src/api: API 请求定义和封装。
- src/views: 页面视图组件。
- src/router: 路由配置和守卫。
- src/store: Pinia 状态管理。
- src/layouts: 布局组件。
- src/components: 业务组件。
这一层就像具体的业务部门，负责实现具体的业务功能。

2. 核心包层 (`packages`)

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

packages/@core: 核心共享库。
- base: 基础设计系统、图标和共享工具。
- ui-kit: 封装的 UI 组件库。
  - shadcn-ui: 基于 Shadcn UI 的基础组件。
  - form-ui: 表单组件封装。
  - layout-ui: 布局组件封装。
  - popup-ui: 弹窗、抽屉等组件封装。
- effects: 业务副作用与逻辑封装。
  - access: 权限控制逻辑。
  - hooks: 通用 Hooks (如 useTabs, useRefresh)。
  - request: 请求库封装。
  - plugins: 第三方插件集成 (Echarts, Motion, Vxe-table)。
- preferences: 应用偏好设置管理。
这一层就像公共设施，各个业务部门都可以使用，提高代码复用率。

3. 内部工具层 (`internal`)

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

internal/lint-configs: ESLint, Prettier, Stylelint 等代码规范配置。
internal/vite-config: Vite 构建配置封装。
internal/tailwind-config: Tailwind CSS 配置封装。
internal/tsconfig: TypeScript 配置文件。
这一层就像后勤部门，为开发提供各种工具和配置支持。

前端设计原则

组件化设计: 将 UI 拆分为可复用的组件，提高代码复用率。就像乐高积木，想怎么搭就怎么搭。
关注点分离: 业务逻辑、UI 展示和状态管理分离。各司其职，互不干扰。
类型安全: 充分利用 TypeScript 提供的类型检查。让 bug 无处遁形。
响应式设计: 适配不同屏幕尺寸的设备。手机、平板、电脑，都能用。
性能优化: 代码分割、懒加载、虚拟滚动等优化手段。让应用跑得飞快。
可访问性: 确保应用对所有用户可访问，包括残障用户。人人都能用，才是好应用。
国际化支持: 支持多语言切换。中文、英文、日文，想用什么语言就用什么语言。

Monorepo 优势

代码共享: 多个应用可以共享组件、工具类和配置。不用重复造轮子。
统一依赖管理: 所有应用使用相同版本的依赖，避免版本冲突。版本统一，少出问题。
统一构建工具: 共享构建配置和脚本，提高开发效率。一套工具，多个项目。
更好的协作: 团队成员可以更方便地共享和复用代码。协作更顺畅。
简化版本管理: 统一版本号管理，简化发布流程。版本管理，轻松搞定。

快速上手

在几分钟内搭建并运行 Tagtag Starter。

项目结构

Tagtag Starter 仓库的详细文件结构。