74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# 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。
|