wbase-core

基础核心模块 - 提供通用工具类、校验注解、异常处理、枚举基类等基础能力

---

📦 Maven 依赖

<dependency>
    <groupId>com.wzhcode.wbase</groupId>
    <artifactId>wbase-core</artifactId>
    <version>1.0.1</version>
</dependency>

---

📁 目录结构

wbase-core/src/main/java/com/wzhcode/wbase/core/
│
├── 📂 constants/          # 常量定义
├── 📂 core/               # 核心类（KeyValue）
├── 📂 enums/              # 枚举基类及通用枚举
├── 📂 exception/          # 异常体系
├── 📂 pojo/               # 通用POJO（分页、结果封装、树结构）
├── 📂 util/               # 工具类集合
└── 📂 validation/         # 自定义校验注解

---

📑 目录

• ✅ 自定义校验注解
• 🏷️ 枚举体系
• ⚠️ 异常体系
• 📋 通用POJO
• 🔧 工具类
• 📚 主要依赖
• 💡 最佳实践

---

✅ 自定义校验注解

位置: com.wzhcode.wbase.core.validation

注解	说明	校验器
@Mobile	📱 手机号格式校验	MobileValidator
@Telephone	☎️ 电话格式校验（座机+手机）	TelephoneValidator
@Md5	🔐 MD5格式校验（32位小写hex）	Md5Validator
@Precision	🔢 BigDecimal精度校验	PrecisionValidator
@InEnum	📊 枚举值范围校验	支持多种类型

📝 使用示例

public class UserDTO {
    
    // 手机号校验
    @Mobile
    private String phone;

    // 枚举值校验
    @InEnum(value = CommonStatusEnum.class, ignoreNull = true)
    private Integer status;

    // 精度校验（小数位数不超过2位）
    @Precision(value = 2, message = "金额精度错误")
    private BigDecimal amount;
}

---

🏷️ 枚举体系

位置: com.wzhcode.wbase.core.enums

BaseEnum 接口

所有业务枚举的基类，支持 Jackson 序列化：

public interface BaseEnum<T> {
    @JsonValue
    T getCode();      // 枚举值
    String getDesc(); // 描述
}

内置枚举

枚举	说明	值
CommonStatusEnum	通用状态	ENABLE(1) / DISABLE(0)
DateIntervalEnum	时间间隔	天/周/月/季/年
TerminalEnum	终端类型	小程序/H5/APP等

📝 BaseEnumUtils 工具示例

// 获取枚举描述信息
BaseEnumUtils.getDescription(CommonStatusEnum.class);
// 输出: [1-开启,0-关闭]

// 获取枚举code集合
BaseEnumUtils.getCodeList(List.of(CommonStatusEnum.class));
// 输出: Set[1, 0]

---

⚠️ 异常体系

位置: com.wzhcode.wbase.core.exception

异常类层级

RuntimeException
├── ServiceException      # 业务逻辑异常
├── ServerException       # 服务器异常
├── TODOException         # 待实现功能异常
└── UnrealizedException   # 未实现功能异常

错误码规范

范围	说明	示例
0	成功	SUCCESS
400-499	客户端错误	BAD_REQUEST, UNAUTHORIZED, FORBIDDEN
500-599	服务端错误	INTERNAL_SERVER_ERROR
900-999	自定义错误	REPEATED_REQUESTS, DEMO_DENY
1-xxx-xxx-xxx	业务错误码	1位类型 + 3位系统 + 3位模块 + 3位错误码

📝 异常使用示例

// 抛出业务异常
throw ServiceExceptionUtil.exception(ErrorCode.USER_NOT_EXISTS);

// 带参数的异常
throw ServiceExceptionUtil.exception(ErrorCode.USER_NOT_EXISTS, userId);

// 参数校验异常
throw ServiceExceptionUtil.invalidParamException("用户名不能为空");

---

📋 通用POJO

位置: com.wzhcode.wbase.core.pojo

类一览

类名	说明
PageParam	分页参数（pageNo, pageSize）
SortablePageParam	可排序分页参数
PageResult<T>	分页结果（list, total）
CommonResult<T>	通用返回结果（code, data, msg）
ScopeParam<T>	范围参数（start, end）
ScopeDateParam	日期范围参数
KeyValue<K,V>	键值对

树结构支持

ITreeNode<T, I>                    # 树节点接口
├── TreeNodeAbstract<T, I>         # 抽象实现
│   ├── TreeNodeLongAbstract<T>    # Long类型ID
│   └── TreeNodeStringAbstract<T>  # String类型ID
└── TreeUtil                       # 树构建工具

📝 使用示例

// ========== 分页 ==========
PageParam param = new PageParam();
param.setPageNo(1);
param.setPageSize(10);

PageResult<UserVO> result = new PageResult<>(list, total);

// ========== 通用返回 ==========
CommonResult.success(data);
CommonResult.error(errorCode);
T data = result.getCheckedData();  // 失败抛异常

// ========== 树结构 ==========
public class DeptVO extends TreeNodeLongAbstract<DeptVO> {
    private String name;
}
List<DeptVO> tree = TreeUtil.build(flatList);

---

🔧 工具类

位置: com.wzhcode.wbase.core.util

💡 原则: 优先使用 Hutool，自定义工具类以 Utils 结尾

工具类一览

包名	工具类	说明
collection	CollectionUtils	集合转换、过滤、分组
	ArrayUtils	数组操作
	MapUtils	Map操作
	SetUtils	Set操作
string	StrUtils	字符串处理
	StringUtils	字符串扩展（继承Hutool）
date	DateUtils	Date工具
	LocalDateTimeUtils	LocalDateTime工具
	LocalDateUtils	LocalDate工具
json	JsonUtils	JSON序列化（Jackson）
number	NumberUtils	数字处理
	MoneyUtils	金额计算
object	BeanUtils	对象转换
	ObjectUtils	对象操作
	PageUtils	分页工具
spring	SpringUtils	Spring上下文
	SpringExpressionUtils	SpEL表达式
	SpringAopUtils	AOP工具
servlet	ServletUtils	Servlet工具
http	HttpUtils	HTTP工具
io	FileUtils	文件操作
	IoUtils	IO操作
cache	CacheUtils	Guava缓存
validation	ValidationUtils	校验工具
monitor	TracerUtils	链路追踪
bigdecimal	BigDecimalUtils	BigDecimal计算

📝 CollectionUtils 示例

// 提取字段
List<Long> ids = CollectionUtils.convertList(users, User::getId);
Set<Long> idSet = CollectionUtils.convertSet(users, User::getId);

// 转Map
Map<Long, User> userMap = CollectionUtils.convertMap(users, User::getId);

// 分组
Map<Long, List<User>> deptUserMap = CollectionUtils.convertMultiMap(users, User::getDeptId);

// 过滤
List<User> adults = CollectionUtils.filterList(users, u -> u.getAge() >= 18);

// 差异对比 [新增, 修改, 删除]
List<List<User>> diff = CollectionUtils.diffList(oldList, newList, 
    (a, b) -> a.getId().equals(b.getId()));

📝 日期工具示例

// LocalDateTimeUtils
LocalDateTimeUtils.isBetween(startTime, endTime);          // 当前时间是否在范围内
LocalDateTimeUtils.beginOfMonth(dateTime);                 // 月初
LocalDateTimeUtils.endOfMonth(dateTime);                   // 月末
LocalDateTimeUtils.getQuarterOfYear(dateTime);             // 获取季度
LocalDateTimeUtils.getDateRangeList(start, end, interval); // 按间隔切割时间段

// DateUtils
DateUtils.of(localDateTime);  // LocalDateTime -> Date
DateUtils.of(date);           // Date -> LocalDateTime
DateUtils.isToday(dateTime);  // 是否今天

📝 JSON工具示例

// 序列化
String json = JsonUtils.toJsonString(user);
byte[] bytes = JsonUtils.toJsonByte(user);

// 反序列化
User user = JsonUtils.parseObject(json, User.class);
List<User> users = JsonUtils.parseArray(json, User.class);

// 解析
JsonNode node = JsonUtils.parseTree(json);
boolean isJson = JsonUtils.isJson(text);

📝 金额工具示例

// 分转元
BigDecimal yuan = MoneyUtils.fenToYuan(100);  // 1.00
String yuanStr = MoneyUtils.fenToYuanStr(100); // "1.00"

// 折扣计算
Integer price = MoneyUtils.calculateRatePrice(1000, 80.0);  // 800

// 金额相乘
BigDecimal total = MoneyUtils.priceMultiply(price, count);

📝 对象转换示例

// 单个对象转换
UserVO vo = BeanUtils.toBean(user, UserVO.class);

// 列表转换
List<UserVO> voList = BeanUtils.toBean(userList, UserVO.class);

// 分页结果转换
PageResult<UserVO> pageVO = BeanUtils.toBean(pageResult, UserVO.class);

// 带回调的转换
UserVO vo = BeanUtils.toBean(user, UserVO.class, v -> v.setFullName(v.getName()));

---

📚 主要依赖

依赖	用途	版本管理
Spring Boot Starter	基础框架	✅
Hutool	工具类库	✅
Guava	缓存、集合增强	✅
Jackson	JSON处理	✅
MapStruct	对象映射	✅
Lombok	简化代码	✅
Jakarta Validation	参数校验	✅
MyBatis-Plus Annotation	枚举注解	✅
SkyWalking	链路追踪	✅
Swagger v3	API文档注解	✅

版本由 wbase-dependencies 统一管理

---

💡 最佳实践

场景	推荐做法
🔧 工具类选择	优先使用 Hutool，不满足再自定义
🏷️ 枚举定义	实现 BaseEnum 接口，配合 @InEnum 校验
⚠️ 异常处理	使用 ServiceExceptionUtil.exception() 抛出业务异常
🔄 对象转换	复杂转换用 MapStruct，简单转换用 BeanUtils
📄 分页查询	入参用 PageParam，返回用 PageResult
🌳 树结构	继承 TreeNodeLongAbstract，使用 TreeUtil.build()