Part 6: 公共组件与工具

文档定位：介绍平台核心的公共技术组件与通用工具类，指导业务开发人员如何高效复用现有能力，避免重复造轮子。

6.1 框架组件概览 (`viewsh-framework`)

项目基于 Spring Boot Starters 机制封装了一套开箱即用的技术组件库，业务模块仅需引入对应依赖即可获得能力。

组件 artifactId	功能描述	核心依赖
`viewsh-common`	通用工具包	Hutool, Jackson, Guava
`viewsh-spring-boot-starter-web`	Web 基础	Spring MVC, Swagger, Global Exception
`viewsh-spring-boot-starter-security`	安全组件	Spring Security, OAuth2 Resource Server
`viewsh-spring-boot-starter-mybatis`	数据库组件	MyBatis Plus, Druid, Dynamic Datasource
`viewsh-spring-boot-starter-redis`	缓存组件	Redisson, Spring Data Redis
`viewsh-spring-boot-starter-mq`	消息队列	RocketMQ, Kafka (可选)
`viewsh-spring-boot-starter-job`	定时任务	XXL-JOB
`viewsh-spring-boot-starter-protection`	服务保障	Sentinel, Lock4j, Idempotent
`viewsh-spring-boot-starter-biz-tenant`	多租户业务	MyBatis Plus Plugin

6.2 核心组件使用指南

6.2.1 统一响应结构 (`CommonResult`)

所有 HTTP 接口必须返回 CommonResult<T> 包装对象。

@GetMapping("/get")
public CommonResult<UserVO> getUser(@RequestParam("id") Long id) {
    UserVO user = userService.get(id);
    return CommonResult.success(user);
}

6.2.2 异常处理 (`GlobalExceptionHandler`)

框架自动拦截所有未捕获异常：

业务异常 (ServiceException)：返回对应业务错误码。
参数校验异常 (MethodArgumentNotValidException)：即 @Valid 校验失败，返回 400 错误。
系统异常 (Exception)：返回 500 “系统内部错误”，并打印堆栈日志。

6.2.3 多租户隔离

业务模块引入 viewsh-spring-boot-starter-biz-tenant 后，无需手动编写 WHERE tenant_id = ?。

忽略隔离：如需查询全局数据（如系统管理员），使用 @TenantIgnore 注解。

6.2.4 数据权限

支持注解式数据权限控制：

@DataPermission(deptAlias = "d", userAlias = "u") // 自动拼接 AND (d.id = ? OR u.id = ?)
public List<Order> selectList() { ... }

6.3 常用工具类

基于 Hutool 进行了二次封装，推荐优先使用 viewsh-common 中的工具类。

工具类	路径	用途
JsonUtils	`com.viewsh.framework.common.util.json`	JSON 序列化/反序列化 (Jackson)
DateUtils	`com.viewsh.framework.common.util.date`	日期时间格式化与计算
CollUtils	`com.viewsh.framework.common.util.collection`	集合操作 (Map/List)
ValidationUtils	`com.viewsh.framework.common.util.validation`	手动触发 Bean Validation
ServletUtils	`com.viewsh.framework.common.util.servlet`	获取当前 Request/Response/UserAgent

6.4 开发规范

禁止 System.out：必须使用 log.info/error。
禁止魔法值：状态值等必须定义枚举或常量。
Lombok 使用：推荐使用 @Data, @Slf4j, @Builder 简化代码。
对象转换：使用 MapStruct 进行 DO/DTO/VO 之间的转换，禁止手动 set。

3.4 KiB Raw Blame History

Part 6: 公共组件与工具

6.1 框架组件概览 (viewsh-framework)