# 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>` 包装对象。
```java
@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 数据权限
支持注解式数据权限控制：
```java
@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 开发规范

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