ShuYou Framework

ShuYou Framework 是一套面向 Spring Cloud 微服务场景的 公共基础组件库。项目采用 Maven 多模块结构，将通用能力封装为可独立引入的 Starter，帮助开发者快速搭建简洁、高效、可扩展的企业级应用。

---

目录

• 特性概览
• 技术栈
• 项目结构
• 模块说明
• 模块依赖关系
• 快速开始
• 本地构建
• 相关链接
• 开源协议
• 联系我们

---

特性概览

• 模块化 Starter 设计：按需引入，避免冗余依赖
• Spring Boot 自动配置：开箱即用，零样板代码
• 统一响应与异常处理：标准化 API 返回格式与全局异常拦截
• 多级缓存方案：Redis + Caffeine 二级缓存，支持分布式缓存同步
• 认证鉴权集成：基于 Sa-Token 的登录态、权限、角色管理
• 数据访问增强：MyBatis-Plus 扩展、MongoDB / Elasticsearch / Milvus 工具封装
• Web 层增强：限流、防重复提交、分布式锁、链路追踪等切面能力
• 高性能异步处理：基于 LMAX Disruptor 的无锁队列事件驱动
• 丰富工具集：JSON、加密、脱敏、IP 定位、Excel、HTTP 等 30+ 工具类

---

技术栈

名称	版本	说明
Java	25	运行环境
Spring Boot	4.1.0	基础框架
Spring Cloud	2025.1.2	微服务框架
Spring Cloud Alibaba	2025.1.0.0	阿里云微服务组件
MyBatis-Plus	3.5.16	ORM 增强
Sa-Token	1.45.0	认证鉴权
Redisson	4.5.0	分布式锁 / Redis 客户端
LMAX Disruptor	4.0.0	高性能队列
Milvus SDK	2.6.16	向量数据库
Hutool	5.8.46	Java 工具库
MapStruct-Plus	1.5.0	对象映射

完整依赖版本由根 pom.xml 与 shuyou-bom 统一管理。

---

项目结构

shuyou-framework/
├── pom.xml                          # 父 POM，统一版本与依赖管理
├── LICENSE                          # 开源协议
├── README.md                        # 项目说明文档
│
├── shuyou-bom/                      # BOM 模块，对外发布版本清单
│
├── shuyou-core/                     # 核心基础模块（无 Spring Web 依赖）
│   └── src/main/java/com/shuyoutech/common/core/
│       ├── constant/                # 通用常量（CommonConstants、EntityConstants 等）
│       ├── enums/                   # 通用枚举（StatusEnum、ErrorCodeEnum 等）
│       ├── exception/               # 业务异常（BusinessException、AuthException）
│       ├── model/                   # 通用模型（R 统一响应、校验分组）
│       ├── service/                 # 通用服务接口（BatchHandler、SimpleConverter）
│       └── util/                    # 工具类（JsonUtils、SmUtils、HttpClientUtils 等）
│
├── shuyou-redis-starter/            # Redis 缓存 Starter
│   └── src/main/java/com/shuyoutech/common/redis/
│       ├── config/                  # Redis / Cache 自动配置
│       ├── manager/                 # Redis + Caffeine 二级缓存管理器
│       ├── message/                 # 缓存消息广播监听
│       ├── serializer/              # FastJson2 Redis 序列化器
│       └── util/                    # RedisUtils、RedissonUtils、SequenceUtils
│
├── shuyou-mongodb-starter/          # MongoDB Starter
│   └── src/main/java/com/shuyoutech/common/mongodb/
│       ├── config/                  # MongoDB 自动配置
│       ├── model/                   # BaseEntity、TreeEntity、BaseVo
│       └── MongoUtils.java          # MongoDB 操作工具类
│
├── shuyou-disruptor-starter/        # Disruptor 高性能队列 Starter
│   └── src/main/java/com/shuyoutech/common/disruptor/
│       ├── event/                   # 事件定义
│       ├── handler/                 # 事件处理器与生产者
│       ├── init/                    # 启动初始化（DisruptorRunner）
│       ├── process/                 # 事件处理流程
│       └── service/                 # DisruptorService 接口
│
├── shuyou-satoken-starter/          # Sa-Token 认证鉴权 Starter
│   └── src/main/java/com/shuyoutech/common/satoken/
│       ├── config/                  # Sa-Token 自动配置
│       ├── constant/                # 认证常量
│       ├── handler/                 # 认证异常处理
│       ├── model/                   # LoginUser、LoginUserPost
│       ├── service/                 # 权限接口实现（StpInterfaceImpl）
│       └── util/                    # AuthUtils 认证工具
│
├── shuyou-mybatis-starter/          # MyBatis-Plus Starter
│   └── src/main/java/com/shuyoutech/common/mybatis/
│       ├── config/                  # MyBatis-Plus 自动配置
│       ├── handler/                 # 字段自动填充（InjectionMetaObjectHandler）
│       └── mapper/                  # SuperMapper 扩展接口
│
├── shuyou-elasticsearch-starter/    # Elasticsearch Starter
│   └── src/main/java/com/shuyoutech/common/elasticsearch/
│       └── ElasticSearchUtils.java  # ES 操作工具类
│
├── shuyou-milvus-starter/           # Milvus 向量数据库 Starter
│   └── src/main/java/com/shuyoutech/common/milvus/
│       ├── config/                  # Milvus 自动配置
│       ├── config/properties/       # MilvusProperties 配置项
│       └── MilvusUtils.java         # Milvus 操作工具类
│
└── shuyou-web-starter/              # Web 层聚合 Starter（推荐 Web 项目引入）
    └── src/main/java/com/shuyoutech/common/web/
        ├── annotation/              # @RateLimit、@RepeatSubmit、@DistributedLock
        ├── aspect/                  # 限流 / 防重复提交 / 分布式锁切面
        ├── config/                  # WebMvc、异步、校验、限流器配置
        ├── handler/                 # GlobalExceptionHandler 全局异常处理
        ├── interceptor/             # TraceIdInterceptor 链路追踪
        ├── model/                   # PageQuery、PageResult、Options 等
        ├── service/                 # SuperService / SuperTreeService 通用 CRUD
        └── util/                    # TreeUtils、JakartaServletUtils 等

---

模块说明

模块	ArtifactId	说明
BOM	shuyou-bom	统一管理所有 ShuYou 模块版本，业务项目通过 BOM 引入可避免版本冲突
核心	shuyou-core	通用常量、枚举、异常、统一响应 R<T>、校验分组及 30+ 工具类，是所有 Starter 的基础
Redis	shuyou-redis-starter	Redis 连接配置、FastJson2 序列化、Redisson 分布式锁、Redis + Caffeine 二级缓存
MongoDB	shuyou-mongodb-starter	MongoDB 自动配置、基础实体模型、MongoUtils 文档操作工具
Disruptor	shuyou-disruptor-starter	基于 LMAX Disruptor 的高性能无锁队列，支持事件驱动异步处理
Sa-Token	shuyou-satoken-starter	登录认证、JWT、权限角色校验，集成 Redis 会话存储
MyBatis	shuyou-mybatis-starter	MyBatis-Plus 增强、SuperMapper、字段自动填充、P6Spy SQL 监控
Elasticsearch	shuyou-elasticsearch-starter	Spring Data Elasticsearch 集成与 ElasticSearchUtils 工具
Milvus	shuyou-milvus-starter	向量数据库 Milvus 连接配置与 MilvusUtils 工具，适用于 AI / RAG 场景
Web	shuyou-web-starter	Web 层一站式 Starter，聚合 Redis、MongoDB、Sa-Token、Disruptor，提供全局异常处理、限流、防重复提交、分布式锁等能力

核心能力详解

shuyou-core

• 统一响应 R<T>：标准化 API 返回结构（code / data / msg / traceId）
• 校验分组：SaveGroup、UpdateGroup、QueryGroup、StatusGroup 支持分组校验
• 工具类：JSON、日期、加密（含国密 SM2/SM3/SM4）、脱敏、IP 定位、Excel、HTTP 等
• 异常体系：BusinessException、AuthException 配合 Web 层全局异常处理

shuyou-web-starter

• 注解驱动：
  • @RateLimit — 接口限流（支持 IP / 用户 / 全局维度）
  • @RepeatSubmit — 防表单重复提交
  • @DistributedLock — 基于 Redisson 的分布式锁
• 通用 Service：SuperService / SuperTreeService 提供标准 CRUD 与树形结构操作
• 全局异常处理：统一拦截校验、权限、业务、SQL 等异常并返回 R<T>

shuyou-redis-starter

• 二级缓存：RedisCaffeineCacheManager 实现本地 + 远程缓存
• 缓存同步：通过 Redis Pub/Sub 广播缓存失效消息
• 分布式能力：RedissonUtils 分布式锁、SequenceUtils 分布式 ID 序列

---

模块依赖关系

graph TD
    BOM[shuyou-bom]
    CORE[shuyou-core]
    REDIS[shuyou-redis-starter]
    MONGO[shuyou-mongodb-starter]
    DISRUPTOR[shuyou-disruptor-starter]
    SATOKEN[shuyou-satoken-starter]
    MYBATIS[shuyou-mybatis-starter]
    ES[shuyou-elasticsearch-starter]
    MILVUS[shuyou-milvus-starter]
    WEB[shuyou-web-starter]

    BOM -.-> CORE & REDIS & MONGO & DISRUPTOR & SATOKEN & MYBATIS & ES & MILVUS & WEB

    REDIS --> CORE
    MONGO --> CORE
    DISRUPTOR --> CORE
    ES --> CORE

    SATOKEN --> REDIS
    MYBATIS --> SATOKEN
    MILVUS --> SATOKEN

    WEB --> REDIS
    WEB --> MONGO
    WEB --> SATOKEN
    WEB --> DISRUPTOR

Loading

---

快速开始

环境要求

• JDK 25+
• Maven 3.9+
• （按需）Redis、MySQL、MongoDB、Elasticsearch、Milvus

引入 BOM（推荐）

在业务项目的 pom.xml 中引入 BOM 统一管理版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.shuyoutech</groupId>
            <artifactId>shuyou-bom</artifactId>
            <version>2026.4.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

按需引入 Starter

<!-- Web 项目（推荐，包含 Redis / MongoDB / Sa-Token / Disruptor） -->
<dependency>
    <groupId>com.shuyoutech</groupId>
    <artifactId>shuyou-web-starter</artifactId>
</dependency>

<!-- 仅需 MyBatis-Plus 增强 -->
<dependency>
    <groupId>com.shuyoutech</groupId>
    <artifactId>shuyou-mybatis-starter</artifactId>
</dependency>

<!-- 仅需 Redis 缓存 -->
<dependency>
    <groupId>com.shuyoutech</groupId>
    <artifactId>shuyou-redis-starter</artifactId>
</dependency>

<!-- 向量数据库 Milvus -->
<dependency>
    <groupId>com.shuyoutech</groupId>
    <artifactId>shuyou-milvus-starter</artifactId>
</dependency>

配置示例

# Redis
spring:
  data:
    redis:
      host: localhost
      port: 6379

# Milvus
spring:
  data:
    milvus:
      uri: http://localhost:19530
      username: root
      password: Milvus
      database: default

使用示例

@RestController
@RequestMapping("/api/demo")
public class DemoController {

    @RateLimit(time = 60, count = 10)
    @RepeatSubmit(interval = 3000)
    @PostMapping("/submit")
    public R<Void> submit(@RequestBody @Validated(SaveGroup.class) DemoDto dto) {
        return R.success();
    }
}

Milvus 部署与图形化管理工具 Attu 的使用说明，请参阅 shuyou-milvus-starter/README.md。

---

本地构建

# 克隆项目
git clone https://github.com/shuyou-ai/shuyou-framework.git
cd ShuYou-Framework

# 编译全部模块
mvn clean install -DskipTests

# 发布到 Maven Central（维护者）
mvn clean deploy -Prelease

---

相关链接

项目	地址
GitHub	https://github.com/shuyou-ai/shuyou-framework
数游官网	https://www.shuyoutech.com
AI 应用系统	https://shuyou.ai
AI API 聚合平台	https://api.shuyou.ai

---

开源协议

本项目基于 MIT License 开源。

---

联系我们

微信（备注说明来意）

如有问题或建议，欢迎通过 GitHub Issues 提交反馈。