# start-admin-boot

**Repository Path**: liiayy/start-admin-boot

## Basic Information

- **Project Name**: start-admin-boot
- **Description**: Start-Admin-Boot 是一款面向企业级的现代化后台管理脚手架。项目采用业界最前沿的技术栈，基于 Spring Boot 3.x、MyBatis-Flex 和 Sa-Token 构建，旨在为开发者提供一个开箱即用、高内聚低耦合、规范统一的微服务基础设施。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Start-Admin-Boot 单体后台管理框架

<p align="center">
  <b>基于 Spring Boot 3.x + MyBatis-Flex + Sa-Token 打造的现代化极简单体开发脚手架</b>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/JDK-25-green.svg" alt="JDK 25">
  <img src="https://img.shields.io/badge/Spring%20Boot-3.5.9-blue.svg" alt="Spring Boot">
  <img src="https://img.shields.io/badge/MyBatis--Flex-1.11.6-red.svg" alt="MyBatis-Flex">
  <img src="https://img.shields.io/badge/Sa--Token-1.44.0-orange.svg" alt="Sa-Token">
  <img src="https://img.shields.io/badge/License-Apache--2.0-blue.svg" alt="License">
</p>

---

## 📖 项目简介

**Start-Admin-Boot** 是一款面向企业级的现代化**单体架构后台管理脚手架**。项目采用最新的 `Java 25` 与 `Spring Boot 3.5.9` 构建，由微服务版本平滑改造而来。我们保留了其极致解耦的公共组件设计，剔除了 Nacos、Seata、Sentinel、Gateway 等繁琐的分布式组件，全面转向更加纯粹的**单体架构**。

项目通过底座式 `start-common` 模块将缓存、数据权限、日志审计、OSS、Excel、WebSocket、Sa-Token 安全框架等核心组件开箱即用集成，业务逻辑由 `start-admin` 独立模块承载。大幅降低了系统的部署复杂度和开发心智负担，非常适合中小企业快速迭代与极速上云。

## ✨ 核心特性

- 💡 **顶尖技术栈**：基于 Java 25 虚拟线程技术与 Spring Boot 3.5.9，享受现代化 JDK 新语法与底层并发带来的极致性能。
- 🛡️ **极简安全拦截**：集成 `Sa-Token` 认证框架，配置单进程本地 `StpInterface` 权限解析器，支持角色/菜单权限精确拦截。
- ⚡ **优雅持久化操作**：采用主流的 `MyBatis-Flex` ORM 框架，内置雪花算法 ID 自动分配与极致优雅的链式 SQL 链查询。
- 🧩 **平滑单体依赖**：包含 `start-common`（提供通用包，含 DB、Cache、WebSocket、OSS 等）与 `start-admin`（主程序模块，含 Controller、Service、Manager 层），职责分明。
- 🔌 **全双工即时推送**：提供原生 WebSocket 支持，集成全局连接会话治理与 Redis 推送总线。
- 📝 **极客级架构规范约束**：推行 `Service`（业务编排）+ `Manager`（数据访问层封装）的二层治理结构，保证代码的高度可维护性。

## 🛠️ 技术栈清单

| 技术分类 | 框架与组件 | 说明 |
| --- | --- | --- |
| **主脚手架** | Spring Boot 3.5.9 | 后端核心底座，开启虚拟线程支持 |
| **持久化层** | MyBatis-Flex 1.11.6, Druid 1.2.27 | 优雅 ORM 框架、连接池（支持 PostgreSQL） |
| **认证授权** | Sa-Token 1.44.0 | 本地登录认证、角色权限校验 |
| **缓存模块** | Redis, Redisson 3.52.0, Caffeine 3.2.3 | 分布式缓存、一二级本地缓存架构、防重分布式锁 |
| **文件存储** | MinIO / 阿里云 OSS | 统一抽象的本地及云端对象存储（MinIO 默认） |
| **工具映射** | Hutool 5.8.43, MapStruct 1.6.3 | 常用工具类库、Entity/VO 属性类型映射 |

## 🏗️ 模块架构

```text
start-admin (单体根目录)
├── start-common               # 公共基础底座 (提供共享底座与组件库)
│   ├── src/main/java          # 包含缓存管理、MyBatis-Flex分页/数据权限、RedisUtils工具类
│   ├── src/main/resources     # 内置共通 YAML 配置（common-db.yml、common-redis.yml、common-satoken.yml等）
│   └── org.springframework.boot.autoconfigure.AutoConfiguration.imports  # 自动注入公共配置声明
└── start-admin                # 业务启动模块 (包含系统级业务逻辑，作为唯一应用启动)
    ├── src/main/java          # 系统核心业务：Auth（鉴权）、Monitor（日志/时光机）、Notice（公告）、System（菜单/参数/字典）
    └── src/main/resources     # application.yaml / application-dev.yaml 运行时配置文件
```

## 🚀 快速开始

### 1. 环境准备
- **JDK**: 25 (推荐使用 GraalVM JDK 或 Oracle OpenJDK 25.0.2)
- **PostgreSQL**: 14+ (数据库：`start-admin-system`，密码：`root`)
- **Redis**: 6.0+ (密码：`WeEvBhLapEHJMG4JFfFG`)

### 2. 构建与运行
在单体项目根目录下：
```bash
# 1. 快速编译项目
mvn clean compile

# 2. 启动后端单体服务 (运行在 48080 端口，且上下文路径为 /api)
mvn spring-boot:run -pl start-admin -am
```

### 3. 前端启动
进入前端项目 `start-admin-web-ui-new`：
```bash
# 1. 安装依赖
pnpm install

# 2. 启动开发服务器
pnpm dev2
```
前端开发服务器启动在 `9000` 端口，通过自带反向代理直接与 `48080` 端口的单体后端进行交互。

## 📐 开发规范

为保持架构的一致性与整洁，请遵守如下规范：
1. **数据持久化位置**：所有表的实体类 `Entity`、持久化 `Mapper` 必须在 `start-common` 模块下定义，以便全局共享。
2. **业务分层结构**：在主服务模块 `start-admin` 下进行业务开发，严格遵循以下三层职责分工：
   - `Controller`：接收请求，执行注解权限判定（如 `@SaCheckPermission("system:config:query")`）及入参校验。
   - `Service`：负责复杂的核心业务逻辑编排和事务管理。
   - `Manager`：直接调用 Mapper 封装细粒度查询、构建复杂 MyBatis-Flex 语句、整合 Redis 缓存、并负责 VO / Entity 转换。
3. **数据变更审计**：重要数据变更建议使用本地 Spring 事件发布 `DataTracerEvent`，系统将自动异步入库保存。

## 📄 许可证

本项目开源协议基于 [Apache-2.0 License](LICENSE)。您可以自由地使用、修改并分发，请保留作者版权信息。