# wgq-sheep

**Repository Path**: xiaowang990925/wgq-sheep

## Basic Information

- **Project Name**: wgq-sheep
- **Description**: 封装多个项目的公共依赖
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2023-06-06
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wgq-sheep

## 项目介绍

wgq-sheep 是一个基于 Spring Boot 的企业级 Java 开发框架，提供了一套完整的微服务开发解决方案。框架遵循领域驱动设计（DDD）思想，集成了认证授权、缓存、消息队列、对象存储、日志记录、限流、分布式锁等常用功能，帮助开发者快速构建稳定、高效的企业级应用。

### 核心特性

- **模块化设计**：采用模块化架构，各功能模块独立可插拔
- **开箱即用**：基于 Spring Boot 自动配置，快速集成各种中间件
- **分布式支持**：内置分布式会话、分布式锁、分布式限流等能力
- **安全认证**：提供完整的认证授权框架，支持 JWT 和 Session 两种模式
- **多数据源**：支持 MySQL、Redis、Elasticsearch 等多种数据存储
- **代码生成**：提供 SQL DDL 自动生成工具，支持分库分表
- **协议统一**：统一的 DTO/VO/BO/PO/Query/Param 数据对象分层
- **监控告警**：内置应用监控、日志记录、异常处理等机制

## 项目架构

### 整体架构

```
wgq-sheep
├── sheep                          # 核心工具模块
├── sheep-json                     # JSON 扩展模块
├── sheep-protocol                 # 协议层模块（DTO/VO/BO/PO/Query/Param）
├── sheep-protocol-dao             # DAO 协议模块
├── sheep-protocol-mq              # MQ 协议模块
├── sheep-oss-starter              # 对象存储启动器
├── sheep-redis-starter            # Redis 启动器（含限流、消息队列）
├── sheep-redisson-starter         # Redisson 分布式锁启动器
├── sheep-rocketmq-starter         # RocketMQ 启动器
├── sheep-log                      # 日志模块
├── sheep-secure-starter           # 安全启动器
├── sheep-starter                  # Spring Boot 启动器
├── sheep-test                     # 测试模块
├── sql-generate                   # SQL 代码生成器
└── sheep-authenticator            # 认证授权模块
    ├── authenticator-core         # 认证核心
    ├── authenticator-gateway-api   # 网关 API
    ├── authenticator-microservice-starter  # 微服务启动器
    ├── authenticator-monolithic-starter   # 单体应用启动器
    └── authenticator-passport-starter     # Passport 启动器
```

### 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 2.2.1.RELEASE | 应用框架 |
| Spring Cloud | - | 微服务框架 |
| JDK | 8+ | Java 开发工具包 |
| Maven | 3.6+ | 项目构建工具 |
| Redis | 5.0+ | 缓存/分布式锁/消息队列 |
| Redisson | 3.x | Redis 客户端 |
| RocketMQ | 4.x | 消息队列 |
| MinIO | Latest | 对象存储 |
| Elasticsearch | 7.x | 搜索引擎 |
| FastJSON | 1.2.x | JSON 处理 |
| MyBatis | 3.x | ORM 框架 |

## 模块说明

### 1. sheep - 核心工具模块

提供项目开发所需的基础工具类和通用功能。

**核心功能**：
- 工具类集合：字符串、日期、集合、文件、网络等
- 加密算法：Base64、RSA、HMAC、3DES 等
- 缓存抽象：支持 Caffeine、Redis 等多种缓存实现
- 邮件发送：SMTP 邮件发送功能
- IP 地址解析：支持多种 IP 获取方式
- 上下文管理：Session 和 Spring 上下文工具

**依赖**：无

**文档**：[sheep/README.md](sheep/README.md)

### 2. sheep-json - JSON 扩展模块

基于 FastJSON 的 JSON 扩展实现。

**核心功能**：
- JSON 序列化/反序列化
- 扩展的 JSON 处理能力

**依赖**：sheep, FastJSON

**文档**：[sheep-json/README.md](sheep-json/README.md)

### 3. sheep-protocol - 协议层模块

定义统一的数据对象协议，实现 DTO/VO/BO/PO/Query/Param 分层。

**核心功能**：
- DTO (Data Transfer Object) - 数据传输对象
- VO (View Object) - 视图对象
- BO (Business Object) - 业务对象
- PO (Persistent Object) - 持久化对象
- Query - 查询对象
- Param - 参数对象
- DDD 支持：Entity、ValueObject、CopyableValueObject
- 分页支持：PagerResult、SimplePager
- 异常处理：BusinessException、SheepError
- 枚举支持：AuditStatus、DeviceType、Platform 等

**依赖**：无

**文档**：[sheep-protocol/README.md](sheep-protocol/README.md)

### 4. sheep-protocol-dao - DAO 协议模块

DAO 层协议定义，支持数据库分页查询。

**核心功能**：
- PO (Persistent Object) - 持久化对象
- DatabasePagerQuery - 数据库分页查询
- CursorDatabasePagerQuery - 游标分页查询
- FieldOrder - 字段排序
- MethodOrder - 方法排序

**依赖**：sheep-protocol

**文档**：[sheep-protocol-dao/README.md](sheep-protocol-dao/README.md)

### 5. sheep-protocol-mq - MQ 协议模块

消息队列协议定义，统一消息发送接口。

**核心功能**：
- AbstractMQProducer - 消息生产者抽象
- MQEvent - 消息事件
- BaseQueueDTO - 基础队列 DTO
- BaseDelayQueueDTO - 延迟队列 DTO
- AbstractLocalQueue - 本地队列抽象
- AbstractArrayBlockQueue - 数组阻塞队列

**依赖**：sheep-protocol

**文档**：[sheep-protocol-mq/README.md](sheep-protocol-mq/README.md)

### 6. sheep-oss-starter - 对象存储启动器

统一的对象存储服务，支持多种云存储提供商。

**核心功能**：
- 支持的存储服务：
  - MinIO - 自建对象存储
  - 腾讯云 COS - 腾讯云对象存储
  - 阿里云 OSS - 阿里云对象存储
  - 华为云 OBS - 华为云对象存储
- 统一的 OssTemplate 接口
- 文件上传/下载/删除
- 分片上传支持
- 签名 URL 生成

**依赖**：sheep-protocol, Spring Boot Starter

**配置示例**：
```yaml
sheep:
  oss:
    type: minio
    endpoint: http://127.0.0.1:9000
    access-key: minioadmin
    secret-key: minioadmin
    bucket-name: sheep
```

**文档**：[sheep-oss-starter/README.md](sheep-oss-starter/README.md)

### 7. sheep-redis-starter - Redis 启动器

Redis 功能集成，包含缓存、限流、消息队列等功能。

**核心功能**：

#### 7.1 Redis 缓存
- 抽象的 Redis 缓存接口
- 支持 String、Hash、List、Set、ZSet 等数据结构
- 批量操作支持

#### 7.2 限流功能
- 固定窗口限流 (Fixed Window)
- 滑动窗口限流 (Sliding Window)
- 令牌桶限流 (Token Bucket)
- @RateLimiter 注解支持
- 分布式限流客户端

#### 7.3 消息队列
- 基于 Redis 的消息队列实现
- 支持延迟队列
- AbstractRedisQueueConsumer - 队列消费者抽象
- SheepRedisMQProducer - 消息生产者

#### 7.4 Redis 工具
- RedisUtils - Redis 工具类
- RedisService - Redis 服务封装
- RedisServiceV2 - Redis 服务 V2 版本

**依赖**：sheep-protocol, Redisson

**配置示例**：
```yaml
spring:
  redis:
    host: 127.0.0.1
    port: 6379
    password: 
    database: 0
```

**文档**：[sheep-redis-starter/README.md](sheep-redis-starter/README.md)

### 8. sheep-redisson-starter - Redisson 分布式锁启动器

基于 Redisson 的分布式锁实现。

**核心功能**：
- @RedissonLock 注解支持
- RedissonLockClient - 分布式锁客户端
- 支持多种锁类型：
  - 可重入锁 (Reentrant Lock)
  - 公平锁 (Fair Lock)
  - 读写锁 (ReadWrite Lock)
  - 红锁 (Red Lock)
- 自动锁释放
- 锁超时控制

**依赖**：sheep-protocol, Redisson

**配置示例**：
```yaml
sheep:
  redisson:
    address: redis://127.0.0.1:6379
    database: 0
```

**使用示例**：
```java
@RedissonLock(key = "user:#{#userId}", leaseTime = 10, waitTime = 3)
public void updateUser(Long userId, UserDTO userDTO) {
    // 业务逻辑
}
```

**文档**：[sheep-redisson-starter/README.md](sheep-redisson-starter/README.md)

### 9. sheep-rocketmq-starter - RocketMQ 启动器

RocketMQ 消息队列集成。

**核心功能**：
- SheepRocketMQProducer - 消息生产者
- 支持 Topic 和 Tag 配置
- 异步消息发送
- 消息重试机制

**依赖**：sheep-protocol-mq, RocketMQ

**配置示例**：
```yaml
sheep:
  rocketmq:
    name-server: 127.0.0.1:9876
    producer-group: sheep-producer
```

**文档**：[sheep-rocketmq-starter/README.md](sheep-rocketmq-starter/README.md)

### 10. sheep-log - 日志模块

统一的日志记录功能，支持 API 日志和请求日志。

**核心功能**：
- @ApiLog 注解 - API 日志记录
- RequestLogAspect - 请求日志切面
- ApiLogAspect - API 日志切面
- ApiLogEvent - API 日志事件
- ApiLogPublisher - 日志发布器
- 支持日志类型：API、REQUEST、ERROR
- 异步日志记录

**依赖**：sheep-protocol, Spring AOP

**配置示例**：
```yaml
sheep:
  log:
    enabled: true
    async: true
```

**使用示例**：
```java
@ApiLog(description = "用户登录", logType = LogTypeEnum.API)
public Result<LoginUserVO> login(LoginParam param) {
    // 业务逻辑
}
```

**文档**：[sheep-log/README.md](sheep-log/README.md)

### 11. sheep-secure-starter - 安全启动器

基于 Spring Security 的安全控制。

**核心功能**：
- @PreAuthorize 注解 - 权限控制
- 支持 SpEL 表达式
- 方法级权限控制

**依赖**：Spring Security

**使用示例**：
```java
@PreAuthorize("hasRole('ADMIN')")
public void deleteUser(Long userId) {
    // 业务逻辑
}
```

**文档**：[sheep-secure-starter/README.md](sheep-secure-starter/README.md)

### 12. sheep-starter - Spring Boot 启动器

框架的核心启动器，整合所有功能模块。

**核心功能**：
- 自动配置：SheepAutoConfiguration
- 全局异常处理：GlobalExceptionHandler
- 统一响应封装：ControllerResponseAdvice
- 客户端信息过滤器：ClientInformationFilter
- 登录用户参数解析器：LoginUserArgumentResolvers
- 客户端信息参数解析器：ClientInfoArgumentResolvers
- MyBatis 拦截器：MybatisInterceptor
- MVC 配置适配器：MvcConfigurationAdapter
- 监控功能：Monitor
- 验证码生成：ValidateCode
- SpEL 工具：SpElUtils
- 本地缓存：AbstractLocalCache

**依赖**：所有功能模块

**文档**：[sheep-starter/README.md](sheep-starter/README.md)

### 13. sheep-test - 测试模块

框架功能演示和测试模块。

**核心功能**：
- Redis MQ 测试
- HelloSyncRedisMQConsumer - 同步消息消费者
- HelloSyncRedisMQDTO - 消息 DTO
- RedisMQProducerController - 消息生产控制器
- Knife4j Swagger 配置

**依赖**：所有功能模块

**文档**：[sheep-test/README.md](sheep-test/README.md)

### 14. sql-generate - SQL 代码生成器

根据 Java POJO 类自动生成数据库 DDL 语句。

**核心功能**：
- DDL 自动生成
- 支持多数据库：MySQL、SQL Server、Elasticsearch
- 分库分表支持
- Hash 和原始值分表策略
- 表后缀动态生成
- 字段映射：Java 类型到数据库类型

**依赖**：sheep, sheep-starter

**使用示例**：
```java
@SplitTable(tablePrefix = "user", bucketCount = 10)
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "username", length = 50, nullable = false)
    private String username;
}

// 生成 DDL
CodeGenerator.generaCreateDDL(User.class);
```

**文档**：[sql-generate/README.md](sql-generate/README.md)

### 15. sheep-authenticator - 认证授权模块

完整的认证授权框架，支持微服务和单体应用。

#### 15.1 authenticator-core - 认证核心

**核心功能**：
- Authenticator - 认证器接口
- DefaultSecurityManager - 默认安全管理器
- SessionManager - 会话管理器
- SessionDao - 会话数据访问（支持 Redis）
- Realm - 认证数据源抽象
- Filter - 认证过滤器
- JWT RSA 签名
- 事件通知：登录/登出事件

**会话管理**：
- DefaultSession - 默认会话实现
- DefaultSessionParser - 会话解析器
- RedisSessionDao - Redis 会话存储
- EmptySessionDao - 空会话存储

**过滤器**：
- MicroServiceFilter - 微服务认证过滤器
- MonolithicBearerFilter - 单体应用 Bearer Token 过滤器

#### 15.2 authenticator-microservice-starter - 微服务启动器

适用于微服务架构的认证启动器。

#### 15.3 authenticator-monolithic-starter - 单体应用启动器

适用于单体应用的认证启动器。

#### 15.4 authenticator-passport-starter - Passport 启动器

适用于 Passport 认证模式的启动器。

**依赖**：sheep-protocol, sheep-redis-starter

**文档**：[sheep-authenticator/README.md](sheep-authenticator/README.md)

## 快速开始

### 1. 环境要求

- JDK 8+
- Maven 3.6+
- Redis 5.0+
- MySQL 5.7+ (可选)

### 2. 添加依赖

```xml
<dependency>
    <groupId>com.sheep</groupId>
    <artifactId>sheep-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

### 3. 配置文件

```yaml
spring:
  application:
    name: sheep-demo
  redis:
    host: 127.0.0.1
    port: 6379
    
sheep:
  oss:
    type: minio
    endpoint: http://127.0.0.1:9000
    access-key: minioadmin
    secret-key: minioadmin
```

### 4. 启动类

```java
@SpringBootApplication
public class SheepDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SheepDemoApplication.class, args);
    }
}
```

### 5. 使用示例

#### 5.1 对象存储

```java
@RestController
@RequestMapping("/file")
public class FileController {
    
    @Autowired
    private OssTemplate ossTemplate;
    
    @PostMapping("/upload")
    public Result<String> upload(MultipartFile file) {
        String url = ossTemplate.upload(file);
        return Result.success(url);
    }
}
```

#### 5.2 限流

```java
@RestController
@RequestMapping("/api")
public class ApiController {
    
    @RateLimiter(
        key = "api:test",
        count = 10,
        period = 60,
        timeUnit = TimeUnit.SECONDS
    )
    @GetMapping("/test")
    public Result<String> test() {
        return Result.success("success");
    }
}
```

#### 5.3 分布式锁

```java
@Service
public class OrderService {
    
    @RedissonLock(key = "order:#{#orderId}", leaseTime = 30, waitTime = 5)
    public void updateOrder(Long orderId, OrderDTO orderDTO) {
        // 业务逻辑
    }
}
```

#### 5.4 日志记录

```java
@RestController
@RequestMapping("/user")
public class UserController {
    
    @ApiLog(description = "创建用户")
    @PostMapping
    public Result<Long> createUser(@RequestBody UserDTO userDTO) {
        // 业务逻辑
        return Result.success(userId);
    }
}
```

#### 5.5 消息队列

```java
@Service
public class OrderService {
    
    @Autowired
    private SheepRedisMQProducer mqProducer;
    
    public void createOrder(OrderDTO orderDTO) {
        // 创建订单
        // 发送消息
        mqProducer.send("order-topic", orderDTO);
    }
}

@Component
public class OrderConsumer extends AbstractRedisQueueConsumer<OrderDTO> {
    
    @Override
    public void consume(OrderDTO orderDTO) {
        // 处理订单消息
    }
}
```

## 依赖说明

### 核心依赖

| 依赖 | 版本 | 用途 |
|------|------|------|
| spring-boot-starter-web | 2.2.1.RELEASE | Web 开发 |
| spring-boot-starter-data-redis | 2.2.1.RELEASE | Redis 集成 |
| redisson | 3.x | Redis 客户端 |
| fastjson | 1.2.x | JSON 处理 |
| mybatis-spring-boot-starter | 2.x | ORM 框架 |
| rocketmq-spring-boot-starter | 2.x | 消息队列 |
| minio | Latest | 对象存储 |

### 可选依赖

| 依赖 | 用途 |
|------|------|
| spring-security | 安全认证 |
| elasticsearch-rest-high-level-client | 搜索引擎 |
| mysql-connector-java | MySQL 数据库 |

## 最佳实践

### 1. 模块选择

根据项目需求选择合适的模块：

- **单体应用**：sheep-starter + sheep-authenticator(authenticator-monolithic-starter)
- **微服务**：sheep-starter + sheep-authenticator(authenticator-microservice-starter) + sheep-redis-starter
- **需要对象存储**：添加 sheep-oss-starter
- **需要消息队列**：添加 sheep-rocketmq-starter 或使用 sheep-redis-starter 的 MQ 功能
- **需要分布式锁**：添加 sheep-redisson-starter

### 2. 配置管理

- 使用 Spring Boot 配置文件（application.yml）
- 敏感信息使用环境变量或配置中心
- 不同环境使用不同的 profile

### 3. 异常处理

框架提供全局异常处理，自定义异常需继承 `BusinessException`：

```java
public class UserException extends BusinessException {
    public UserException(String message) {
        super(message);
    }
}
```

### 4. 日志记录

- 使用 `@ApiLog` 注解记录 API 日志
- 使用 Slf4j 记录业务日志
- 重要操作使用 INFO 级别
- 异常使用 ERROR 级别

### 5. 性能优化

- 合理使用缓存
- 避免过度使用分布式锁
- 批量操作代替循环操作
- 异步处理耗时操作

### 6. 安全建议

- 使用 HTTPS 传输
- 敏感数据加密存储
- 定期更新依赖版本
- 启用安全审计日志

## 相关资源


### 子模块文档

- [sheep 核心模块](sheep/README.md)
- [sheep-authenticator 认证授权](sheep-authenticator/README.md)
- [sheep-oss-starter 对象存储](sheep-oss-starter/README.md)
- [sheep-protocol 协议层](sheep-protocol/README.md)
- [sheep-protocol-dao DAO 协议](sheep-protocol-dao/README.md)
- [sheep-protocol-mq MQ 协议](sheep-protocol-mq/README.md)
- [sheep-redis-starter Redis 启动器](sheep-redis-starter/README.md)
- [sheep-redisson-starter Redisson 分布式锁](sheep-redisson-starter/README.md)
- [sheep-rocketmq-starter RocketMQ 启动器](sheep-rocketmq-starter/README.md)
- [sheep-secure-starter 安全启动器](sheep-secure-starter/README.md)
- [sheep-starter Spring Boot 启动器](sheep-starter/README.md)
- [sheep-test 测试模块](sheep-test/README.md)
- [sql-generate SQL 代码生成器](sql-generate/README.md)

### 外部参考

- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [Spring Security 官方文档](https://spring.io/projects/spring-security)
- [Redis 官方文档](https://redis.io/documentation)
- [Redisson 官方文档](https://redisson.org)
- [RocketMQ 官方文档](https://rocketmq.apache.org/zh/docs/)
- [MinIO 官方文档](https://min.io/docs/)
- [MyBatis 官方文档](https://mybatis.org/mybatis-3/)

## 版本信息

- **当前版本**：1.0.0-SNAPSHOT
- **Java 版本**：JDK 8+
- **Spring Boot 版本**：2.2.1.RELEASE
- **构建工具**：Maven 3.6+

## 许可证

本项目遵循 Apache License 2.0 许可证。

## 更新日志

### v1.0.0-SNAPSHOT
- 初始版本发布
- 集成认证授权模块
- 支持多种中间件集成
- 提供完整的工具类库
- 支持代码生成功能

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发送邮件

---

**wgq-sheep** - 让 Java 开发更简单！