# springuitls

**Repository Path**: lwx19960428/springuitls

## Basic Information

- **Project Name**: springuitls
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-21
- **Last Updated**: 2025-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot 开发必备：20 个官方工具类深度实战

> **适用读者：** Java 后端开发者（需基础 Spring Boot 知识）  
> **核心理念：** Spring Framework 早已内置大量开箱即用的工具，**拒绝重复造轮子**！

## 📋 项目简介

本项目是对 Spring Framework 内置的 20 个精选工具类的完整演示和深度解析。每个工具类都包含：

- ✅ **完整可运行的代码示例**
- ✅ **实际应用场景演示**
- ✅ **最佳实践和注意事项**
- ✅ **与其他方案的对比说明**

## 🎯 为什么使用 Spring 官方工具类？

- **无额外依赖**：Spring Boot 项目开箱即用
- **深度框架集成**：与 Spring AOP、IoC 等无缝协作
- **异常处理完善**：自动处理 `null`、边界条件等陷阱
- **性能优化**：经 Spring 团队长期生产验证

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd springuitls
```

### 2. 运行演示

#### 方式一：交互式菜单（推荐）

```bash
mvn spring-boot:run
```

启动后会显示交互式菜单，可以选择运行单个或所有演示。

#### 方式二：一次性运行所有演示

```bash
mvn spring-boot:run -Dspring-boot.run.arguments="all"
```

## 📚 工具类清单

### 【核心工具】

#### 1. StringUtils - 字符串处理终结者
- **包路径**：`org.springframework.util.StringUtils`
- **核心功能**：字符串判空、去空格、路径处理
- **常用方法**：
  - `hasText()` - 判断字符串是否有内容（自动 trim）
  - `hasLength()` - 判断字符串长度是否大于 0
  - `getFilename()` - 从路径提取文件名
  - `arrayToCommaDelimitedString()` - 数组转逗号分隔字符串

**示例代码：**
```java
// 安全判空（自动处理 null 和空格）
if (StringUtils.hasText(nickname)) {
    System.out.println("昵称有效: " + nickname.trim());
}

// 提取文件名
String filename = StringUtils.getFilename("/path/to/file.txt"); // file.txt
```

**演示类：** `StringUtilsDemo.java`

---

#### 2. CollectionUtils - 集合操作防坑神器
- **包路径**：`org.springframework.util.CollectionUtils`
- **核心功能**：集合判空、合并、查找
- **常用方法**：
  - `isEmpty()` - 安全判空（自动处理 null）
  - `firstElement()` / `lastElement()` - 获取首尾元素
  - `intersection()` - 求交集

**示例代码：**
```java
// 安全遍历集合
if (CollectionUtils.isEmpty(tags)) {
    System.out.println("无标签，跳过处理");
    return;
}
tags.forEach(tag -> System.out.println("处理标签: " + tag));
```

**演示类：** `CollectionUtilsDemo.java`

---

#### 3. ObjectUtils - 对象安全操作卫士
- **包路径**：`org.springframework.util.ObjectUtils`
- **核心功能**：对象安全打印、哈希、比较
- **常用方法**：
  - `nullSafeToString()` - 安全转字符串（支持数组）
  - `nullSafeHashCode()` - 安全获取哈希码
  - `nullSafeEquals()` - null 安全比较

**示例代码：**
```java
// 安全打印对象（避免 NullPointerException）
System.out.println("用户信息: " + ObjectUtils.nullSafeToString(user));

// 数组安全打印
String[] array = {"Java", "Spring", "Boot"};
System.out.println("数组: " + ObjectUtils.nullSafeToString(array)); // [Java, Spring, Boot]
```

**演示类：** `ObjectUtilsDemo.java`

---

#### 4. Assert - 参数校验断言大师
- **包路径**：`org.springframework.util.Assert`
- **核心功能**：参数校验、前置条件检查
- **常用方法**：
  - `notNull()` - 断言非空
  - `hasText()` - 断言字符串有内容
  - `isTrue()` - 断言条件为真

**示例代码：**
```java
// Service 方法入口校验
public void cancelOrder(Long orderId) {
    Assert.notNull(orderId, "订单ID不能为空");
    Assert.isTrue(orderId > 0, "订单ID必须大于0");
    // 业务逻辑...
}
```

**演示类：** `AssertDemo.java`

---

### 【文件和流】

#### 5. FileCopyUtils - 文件拷贝终极方案
- **包路径**：`org.springframework.util.FileCopyUtils`
- **核心功能**：文件、流、字节数组互拷
- **常用方法**：
  - `copy(InputStream, OutputStream)` - 流拷贝
  - `copyToByteArray(File)` - 文件转字节数组
  - `copy(byte[], File)` - 字节数组写入文件

**演示类：** `FileCopyUtilsDemo.java`

---

#### 6. StreamUtils - 流操作轻量级专家
- **包路径**：`org.springframework.util.StreamUtils`
- **核心功能**：流转字符串、字节数组
- **常用方法**：
  - `copyToString(InputStream, Charset)` - 流转字符串
  - `copyToByteArray(InputStream)` - 流转字节数组
  - `drain(InputStream)` - 排空流

**演示类：** `StreamUtilsDemo.java`

---

#### 7. ResourceUtils - 资源路径解析器
- **包路径**：`org.springframework.util.ResourceUtils`
- **核心功能**：解析 classpath:、file: 等协议
- **⚠️ 重要提醒**：生产环境推荐使用 `ResourceLoader`，此工具在 Fat JAR 中可能失效

**演示类：** `ResourceUtilsDemo.java`

---

### 【反射和 AOP】

#### 8. ReflectionUtils - 反射操作安全网
- **包路径**：`org.springframework.util.ReflectionUtils`
- **核心功能**：反射调用方法、访问字段
- **常用方法**：
  - `findMethod()` - 查找方法
  - `invokeMethod()` - 调用方法
  - `findField()` / `setField()` - 字段操作

**⚠️ 提醒**：仅推荐在测试中使用，生产代码避免反射

**演示类：** `ReflectionUtilsDemo.java`

---

#### 9. AopProxyUtils - AOP 代理解密器
- **包路径**：`org.springframework.aop.support.AopProxyUtils`
- **核心功能**：获取代理对象的真实类型
- **使用场景**：调试 AOP 代理、日志打印

**演示类：** `AopProxyUtilsDemo.java`

---

### 【加密和编码】

#### 10. DigestUtils - 加密工具精简版
- **包路径**：`org.springframework.util.DigestUtils`
- **核心功能**：MD5、SHA-256 摘要计算
- **⚠️ 生产警告**：MD5 已不安全！密码加密必须用 `BCryptPasswordEncoder`

**示例代码：**
```java
String md5 = DigestUtils.md5DigestAsHex("123456".getBytes()); // e10adc3949ba59abbe56e057f20f883e
```

**演示类：** `DigestUtilsDemo.java`

---

#### 11. Base64Utils - Base64 编解码专家
- **包路径**：`org.springframework.util.Base64Utils`
- **核心功能**：Base64 编解码、URL 安全编码
- **常用方法**：
  - `encodeToString()` - 编码为字符串
  - `decodeFromString()` - 从字符串解码
  - `encodeToUrlSafeString()` - URL 安全编码

**演示类：** `Base64UtilsDemo.java`

---

### 【性能和路径】

#### 12. StopWatch - 代码耗时统计器
- **包路径**：`org.springframework.util.StopWatch`
- **核心功能**：多任务耗时统计、性能分析
- **使用场景**：接口性能监控、方法耗时分析

**示例代码：**
```java
StopWatch watch = new StopWatch("订单服务监控");
watch.start("查询订单");
// 业务逻辑...
watch.stop();
System.out.println(watch.prettyPrint()); // 输出格式化报告
```

**演示类：** `StopWatchDemo.java`

---

#### 13. AntPathMatcher - 路径匹配引擎
- **包路径**：`org.springframework.util.AntPathMatcher`
- **核心功能**：路径通配符匹配、变量提取
- **通配符说明**：
  - `?` - 匹配单个字符
  - `*` - 匹配任意字符（不含 /）
  - `**` - 匹配任意层级路径

**示例代码：**
```java
AntPathMatcher matcher = new AntPathMatcher();
boolean match = matcher.match("/api/user/**", "/api/user/1001/profile"); // true

// 提取路径变量
Map<String, String> vars = matcher.extractUriTemplateVariables(
    "/api/user/{id}", "/api/user/1001");
System.out.println(vars.get("id")); // 1001
```

**演示类：** `AntPathMatcherDemo.java`

---

### 【Web 工具】

#### 14. MimeTypeUtils - MIME 类型解析器
- **包路径**：`org.springframework.util.MimeTypeUtils`
- **核心功能**：MIME 类型解析、内容协商
- **常用常量**：`APPLICATION_JSON`, `TEXT_HTML`, `IMAGE_PNG` 等

**演示类：** `MimeTypeUtilsDemo.java`

---

#### 15. UriComponentsBuilder - URL 构建安全专家
- **包路径**：`org.springframework.web.util.UriComponentsBuilder`
- **核心功能**：安全构建 URL、自动编码参数
- **核心优势**：防止 XSS 注入、自动编码特殊字符

**示例代码：**
```java
String url = UriComponentsBuilder
    .fromHttpUrl("http://api.example.com/search")
    .queryParam("q", "Spring Boot 教程") // 自动编码中文
    .queryParam("id", 1001)
    .toUriString();
```

**演示类：** `UriComponentsBuilderDemo.java`

---

### 【其他工具】

#### 16. ClassUtils - 类操作安全助手
- **包路径**：`org.springframework.util.ClassUtils`
- **核心功能**：类存在性检查、类信息获取
- **使用场景**：条件化配置、自动配置

**示例代码：**
```java
// 检查 Redis 依赖是否存在
boolean available = ClassUtils.isPresent(
    "redis.clients.jedis.Jedis", 
    classLoader);
```

**演示类：** `ClassUtilsDemo.java`

---

#### 17. SystemPropertyUtils - 系统属性占位符解析器
- **包路径**：`org.springframework.util.SystemPropertyUtils`
- **核心功能**：解析 ${user.home} 等占位符
- **使用场景**：动态生成路径、测试临时目录

**示例代码：**
```java
String path = SystemPropertyUtils.resolvePlaceholders("${user.home}/logs");
// 输出：/Users/yourname/logs
```

**演示类：** `SystemPropertyUtilsDemo.java`

---

#### 18. NumberUtils - 数字转换安全卫士
- **包路径**：`org.springframework.util.NumberUtils`
- **核心功能**：字符串安全转数字、类型转换
- **常用方法**：
  - `parseNumber(String, Class)` - 解析数字
  - `convertNumberToTargetClass()` - 数字类型转换

**演示类：** `NumberUtilsDemo.java`

---

#### 19. ConcurrentReferenceHashMap - 并发弱引用 Map
- **包路径**：`org.springframework.util.ConcurrentReferenceHashMap`
- **核心功能**：基于弱/软引用的并发 Map，自动回收
- **使用场景**：轻量级缓存、元数据缓存

**⚠️ 提醒**：仅用于非关键缓存，生产级缓存用 Caffeine/Redis

**演示类：** `ConcurrentReferenceHashMapDemo.java`

---

#### 20. LinkedMultiValueMap - 多值 Map 实现
- **包路径**：`org.springframework.util.LinkedMultiValueMap`
- **核心功能**：一个 key 对应多个 value，保留插入顺序
- **使用场景**：HTTP 请求参数、表单提交

**示例代码：**
```java
MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
params.add("hobby", "篮球");
params.add("hobby", "足球");
System.out.println(params.get("hobby")); // [篮球, 足球]
```

**演示类：** `LinkedMultiValueMapDemo.java`

---

## 📊 工具类归属包速查表

| 工具类                  | 所属包                                | 依赖模块       |
|-------------------------|---------------------------------------|----------------|
| StringUtils             | org.springframework.util              | spring-core    |
| CollectionUtils         | org.springframework.util              | spring-core    |
| ObjectUtils             | org.springframework.util              | spring-core    |
| Assert                  | org.springframework.util              | spring-core    |
| FileCopyUtils           | org.springframework.util              | spring-core    |
| StreamUtils             | org.springframework.util              | spring-core    |
| ResourceUtils           | org.springframework.util              | spring-core    |
| ReflectionUtils         | org.springframework.util              | spring-core    |
| AopProxyUtils           | org.springframework.aop.support       | spring-aop     |
| DigestUtils             | org.springframework.util              | spring-core    |
| Base64Utils             | org.springframework.util              | spring-core    |
| StopWatch               | org.springframework.util              | spring-core    |
| AntPathMatcher          | org.springframework.util              | spring-core    |
| MimeTypeUtils           | org.springframework.util              | spring-core    |
| UriComponentsBuilder    | org.springframework.web.util          | spring-web     |
| ClassUtils              | org.springframework.util              | spring-core    |
| SystemPropertyUtils     | org.springframework.util              | spring-core    |
| NumberUtils             | org.springframework.util              | spring-core    |
| ConcurrentReferenceHashMap | org.springframework.util           | spring-core    |
| LinkedMultiValueMap     | org.springframework.util              | spring-core    |

## 🎓 最佳实践总结

### ✅ 推荐使用场景

1. **StringUtils**：任何字符串判空、处理场景
2. **CollectionUtils**：任何集合判空、操作场景
3. **Assert**：Service 层方法入口参数校验
4. **StopWatch**：性能监控、耗时统计
5. **UriComponentsBuilder**：任何需要构建 URL 的场景

### ⚠️ 使用注意事项

1. **ResourceUtils**：勿用于生产环境，Fat JAR 中会失败
2. **DigestUtils**：MD5 已不安全，密码加密用 BCrypt
3. **ReflectionUtils**：仅限测试使用，生产避免反射
4. **ConcurrentReferenceHashMap**：仅用于临时缓存

### 🚫 避免重复造轮子

| 不要自己写                     | 使用 Spring 工具             |
|-------------------------------|------------------------------|
| `if (str == null || str.isEmpty())` | `StringUtils.hasText(str)` |
| `if (list == null || list.isEmpty())` | `CollectionUtils.isEmpty(list)` |
| `String.format()` 拼接 URL    | `UriComponentsBuilder`       |
| 手写 MD5 工具类                | `DigestUtils`                |
| 手写 Base64 工具类             | `Base64Utils`                |

## 🛠 技术栈

- **Spring Boot**: 3.2.5
- **Java**: 17+
- **Maven**: 3.6+

## 📝 项目结构

```
springuitls/
├── src/main/java/com/artisan/springuitls/
│   ├── SpringuitlsApplication.java          # 主启动类
│   ├── SpringUtilsDemoRunner.java           # 演示运行器
│   └── demos/                                # 演示类包
│       ├── StringUtilsDemo.java
│       ├── CollectionUtilsDemo.java
│       ├── ObjectUtilsDemo.java
│       ├── AssertDemo.java
│       ├── FileCopyUtilsDemo.java
│       ├── StreamUtilsDemo.java
│       ├── ResourceUtilsDemo.java
│       ├── ReflectionUtilsDemo.java
│       ├── AopProxyUtilsDemo.java
│       ├── DigestUtilsDemo.java
│       ├── Base64UtilsDemo.java
│       ├── StopWatchDemo.java
│       ├── AntPathMatcherDemo.java
│       ├── MimeTypeUtilsDemo.java
│       ├── UriComponentsBuilderDemo.java
│       ├── ClassUtilsDemo.java
│       ├── SystemPropertyUtilsDemo.java
│       ├── NumberUtilsDemo.java
│       ├── ConcurrentReferenceHashMapDemo.java
│       └── LinkedMultiValueMapDemo.java
├── pom.xml
└── README.md
```

## 📖 学习建议

1. **按顺序学习**：从核心工具开始，逐步深入
2. **动手实践**：运行每个演示，观察输出
3. **对比学习**：理解为什么用 Spring 工具而不是第三方库
4. **应用到项目**：在实际项目中替换现有代码

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

---

**觉得有帮助？请给个 ⭐️ Star！**

立即行动：在你的 Spring Boot 项目中搜索 `import org.springframework.util`，替换掉所有手动编写的工具方法。**少写一行代码，少一个潜在 Bug！**