# 通用工具

**Repository Path**: cruising-time/common-tools

## Basic Information

- **Project Name**: 通用工具
- **Description**: java 开发通用工具类
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-23
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用工具
#### 介绍
java 开发通用工具类
#### 软件架构
java
#### 使用说明

### 1. CacheOperationUtils API 文档

#### 概述

`CacheOperationUtils` 是一个用于内存缓存管理的工具类。它提供了设置缓存项、获取缓存项、以及获取所有缓存键列表的功能。此外，它还支持缓存项过期机制，以确保长时间未访问或已经过期的数据能够被自动清理。

---

#### 方法概览

| 方法名 | 描述 |
| --- | --- |
| `setItem(String key, Object o)` | 设置一个没有指定过期时间的缓存项。 |
| `setItem(String key, Object o, long overtime)` | 设置一个具有指定过期时间（毫秒）的缓存项。 |
| `getItem(String key)` | 根据键获取缓存项，如果缓存已过期，则返回 `null` 并从缓存中移除该项。 |
| `getKeyList()` | 获取当前缓存中所有键的列表。 |


#### 详细方法描述

##### `setItem(String key, Object o)`

- **描述**：向缓存中添加一个新的缓存项，该缓存项不会过期。
- **参数**：
    - `key` (`String`)：缓存项的唯一标识符。
    - `o` (`Object`)：要存储的对象。
- **返回值**：无


##### `setItem(String key, Object o, long overtime)`

- **描述**：向缓存中添加一个新的缓存项，并指定其有效时长（以毫秒为单位）。当超过这个时长后，缓存项将被视为过期。
- **参数**：
    - `key` (`String`)：缓存项的唯一标识符。
    - `o` (`Object`)：要存储的对象。
    - `overtime` (`long`)：缓存项的有效时长（毫秒）。
- **返回值**：无

##### `getKeyList()`

- **描述**：返回一个包含当前缓存中所有键的列表。
- **参数**：无
- **返回值**：
    - `List<String>`：当前缓存中所有键的列表。

---

当然，以下是为 `BeanUtils` 类生成的 Markdown 格式的 API 说明文档。这份文档将详细介绍类的功能、方法的使用方式、参数和返回值，并提供一些使用示例。

### 2. BeanUtils API 文档
#### 方法概览

| 方法名 | 描述 |
| --- | --- |
| `copyProperties(Object source, Object target)` | 将源对象的属性值复制到目标对象中。 |
| `getTargetMethod(Class<?> clazz, String methodName, Class<?> parameterType)` | 获取目标类中的指定方法。 |

---

#### 详细方法描述

##### `copyProperties(Object source, Object target)`

- **描述**：该方法使用反射来遍历源对象的所有 getter 方法，并尝试找到目标对象中相应的 setter 方法，然后调用这些方法完成属性值的复制。
- **参数**：
    - `source` (`Object`)：源对象，其属性值将被复制。
    - `target` (`Object`)：目标对象，属性值将被复制到这里。
- **异常**：
    - 如果 `source` 或 `target` 为 `null`，则抛出 `BeanException`。
    - 如果在调用 getter 或 setter 方法时发生错误，则抛出 `BeanException`。


##### `getTargetMethod(Class<?> clazz, String methodName, Class<?> parameterType)`

- **描述**：辅助方法，用于根据方法名称和参数类型查找并返回目标类中的相应方法。
- **参数**：
    - `clazz` (`Class<?>`)：要查找的方法所属的目标类。
    - `methodName` (`String`)：要查找的方法名称。
    - `parameterType` (`Class<?>`)：方法参数的类型。
- **返回值**：
    - `Method`：如果找到了对应的方法，则返回该方法；否则返回 `null`。
- **示例**：

---

#### 注意事项

- 两个对象之间属性复制必要要求是：getter stter 函数相同
---



### 3.SnowflakeIdUtils API 文档

#### 概述

`SnowflakeIdUtils` 是一个基于 Twitter 的 Snowflake 算法实现的全局唯一 ID 生成器。它能够生成符合特定规则的 64 位整数 ID，适用于分布式系统中的唯一标识需求。此工具类确保了即使在高并发环境下也能高效且无冲突地生成唯一的 ID。

---

#### 方法概览

| 方法名 | 描述 |
| --- | --- |
| `nextId()` | 生成下一个全局唯一的 64 位 ID。 |
| `nextId(long epoch, long workerId, long dataCenterId)` | 使用自定义的时间起点、工作机器 ID 和数据中心 ID 生成下一个全局唯一的 64 位 ID。 |

---

#### 详细方法描述

##### `nextId()`

- **描述**：该方法用于生成下一个全局唯一的 64 位 ID。它结合了当前时间戳、工作机器 ID、数据中心 ID 和序列号来构造最终的 ID。
- **参数**：无
- **返回值**：
  - `long`：下一个全局唯一的 64 位 ID。


##### `nextId(long epoch, long workerId, long dataCenterId)`

- **描述**：允许用户指定时间起点（Epoch）、工作机器 ID 和数据中心 ID 来生成下一个全局唯一的 64 位 ID。这在需要跨多个数据中心或不同配置环境时非常有用。
- **参数**：
  - `epoch` (`long`)：ID 时间部分的起始时间点，通常是一个固定的时间戳。
  - `workerId` (`long`)：工作机器 ID，用来区分不同的机器实例。
  - `dataCenterId` (`long`)：数据中心 ID，用来区分不同的数据中心。
- **返回值**：
  - `long`：下一个全局唯一的 64 位 ID。

---

### ImageUtils API 文档

#### 概述

`ImageUtils` 是一个用于处理图像的工具类，提供了多种图像操作功能，如读取和保存图像文件、缩放、转换格式、旋转、剪裁、调整亮度和对比度、添加水印以及应用马赛克效果等。此工具类适用于需要对图像进行各种处理的应用程序。

---

#### 方法概览

| 方法名 | 描述 |
| --- | --- |
| `readImage(File file)` | 从文件中读取图像并返回 `BufferedImage` 对象。 |
| `saveImage(BufferedImage image, String formatName, File file)` | 将 `BufferedImage` 对象保存为指定格式的图像文件。 |
| `resizeImage(BufferedImage image, int width, int height)` | 缩放图像到指定尺寸。 |
| `convertImageFormat(File sourceFile, String targetFormat, File targetFile)` | 转换图像文件的格式。 |
| `imgToBase64(File file)` | 将图像文件转换为 Base64 编码字符串。 |
| `base64ToImage(String base64String, File targetFile)` | 将 Base64 编码字符串转换回图像文件。 |
| `resize(BufferedImage image, int newWidth, int newHeight)` | 等比缩放图像。 |
| `rotate(BufferedImage image, double angle)` | 旋转图像。 |
| `crop(BufferedImage src, int x, int y, int width, int height)` | 剪裁图像。 |
| `adjustBrightnessAndContrast(BufferedImage image, float brightness, float contrast)` | 调整图像的亮度和对比度。 |
| `addWatermark(BufferedImage baseImage, BufferedImage watermark)` | 向图像添加水印。 |
| `applyMosaicInPlace(BufferedImage image, int blockSize)` | 应用马赛克效果到图像上。 |

---

#### 详细方法描述

##### `readImage(File file)`

- **描述**：从给定的文件路径加载图像，并返回 `BufferedImage` 对象。
- **参数**：
  - `file` (`File`)：包含图像数据的文件。
- **返回值**：
  - `BufferedImage`：表示加载的图像的对象。
- **异常**：
  - `IOException`：如果无法读取文件。
- **示例**：

```java
BufferedImage image = ImageUtils.readImage(new File("path/to/image.jpg"));
```

##### `saveImage(BufferedImage image, String formatName, File file)`

- **描述**：将 `BufferedImage` 对象保存为指定格式的图像文件。
- **参数**：
  - `image` (`BufferedImage`)：要保存的图像对象。
  - `formatName` (`String`)：图像格式（例如 "jpg" 或 "png"）。
  - `file` (`File`)：目标文件。
- **异常**：
  - `IOException`：如果无法写入文件。
- **示例**：

```java
ImageUtils.saveImage(image, "png", new File("path/to/output.png"));
```

##### `resizeImage(BufferedImage image, int width, int height)`

- **描述**：将图像缩放到指定的新宽度和高度。
- **参数**：
  - `image` (`BufferedImage`)：原始图像。
  - `width` (`int`)：新宽度。
  - `height` (`int`)：新高度。
- **返回值**：
  - `BufferedImage`：缩放后的图像对象。
- **示例**：

```java
BufferedImage resizedImage = ImageUtils.resizeImage(image, 800, 600);
```

##### `convertImageFormat(File sourceFile, String targetFormat, File targetFile)`

- **描述**：将源图像文件转换为目标格式并保存到新的文件中。
- **参数**：
  - `sourceFile` (`File`)：源图像文件。
  - `targetFormat` (`String`)：目标图像格式。
  - `targetFile` (`File`)：目标文件。
- **异常**：
  - `IOException`：如果读取或写入文件时发生错误。
- **示例**：

```java
ImageUtils.convertImageFormat(new File("input.jpg"), "png", new File("output.png"));
```

##### `imgToBase64(File file)`

- **描述**：将图像文件转换为 Base64 编码的字符串。
- **参数**：
  - `file` (`File`)：图像文件。
- **返回值**：
  - `String`：Base64 编码的字符串。
- **异常**：
  - `NullPointerException`：如果提供的文件为 `null`。
- **示例**：

```java
String base64String = ImageUtils.imgToBase64(new File("path/to/image.jpg"));
```

##### `base64ToImage(String base64String, File targetFile)`

- **描述**：将 Base64 编码的字符串转换回图像文件。
- **参数**：
  - `base64String` (`String`)：Base64 编码的字符串。
  - `targetFile` (`File`)：目标文件。
- **异常**：
  - `IOException`：如果写入文件时发生错误。
- **示例**：

```java
ImageUtils.base64ToImage(base64String, new File("path/to/output.jpg"));
```

##### `resize(BufferedImage image, int newWidth, int newHeight)`

- **描述**：等比缩放图像到新的尺寸。
- **参数**：
  - `image` (`BufferedImage`)：原始图像。
  - `newWidth` (`int`)：新宽度。
  - `newHeight` (`int`)：新高度。
- **返回值**：
  - `BufferedImage`：缩放后的图像对象。
- **示例**：

```java
BufferedImage resizedImage = ImageUtils.resize(image, 800, 600);
```

##### `rotate(BufferedImage image, double angle)`

- **描述**：旋转图像。
- **参数**：
  - `image` (`BufferedImage`)：原始图像。
  - `angle` (`double`)：旋转角度（以弧度为单位）。
- **返回值**：
  - `BufferedImage`：旋转后的图像对象。
- **示例**：

```java
BufferedImage rotatedImage = ImageUtils.rotate(image, Math.toRadians(90));
```

##### `crop(BufferedImage src, int x, int y, int width, int height)`

- **描述**：从原始图像中剪裁出指定区域。
- **参数**：
  - `src` (`BufferedImage`)：原始图像。
  - `x` (`int`)：剪裁区域左上角的 X 坐标。
  - `y` (`int`)：剪裁区域左上角的 Y 坐标。
  - `width` (`int`)：剪裁区域的宽度。
  - `height` (`int`)：剪裁区域的高度。
- **返回值**：
  - `BufferedImage`：剪裁后的图像对象。
- **示例**：

```java
BufferedImage croppedImage = ImageUtils.crop(image, 100, 100, 200, 200);
```

##### `adjustBrightnessAndContrast(BufferedImage image, float brightness, float contrast)`

- **描述**：调整图像的亮度和对比度。
- **参数**：
  - `image` (`BufferedImage`)：原始图像。
  - `brightness` (`float`)：亮度调整值。
  - `contrast` (`float`)：对比度调整值。
- **返回值**：
  - `BufferedImage`：调整后的图像对象。
- **示例**：

```java
BufferedImage adjustedImage = ImageUtils.adjustBrightnessAndContrast(image, 0.5f, 1.5f);
```

##### `addWatermark(BufferedImage baseImage, BufferedImage watermark)`

- **描述**：向图像添加水印。
- **参数**：
  - `baseImage` (`BufferedImage`)：原始图像。
  - `watermark` (`BufferedImage`)：水印图像。
- **返回值**：
  - `BufferedImage`：带有水印的图像对象。
- **示例**：

```java
BufferedImage watermarkedImage = ImageUtils.addWatermark(image, watermarkImage);
```

##### `applyMosaicInPlace(BufferedImage image, int blockSize)`

- **描述**：直接在传入的 `BufferedImage` 对象上应用马赛克效果。
- **参数**：
  - `image` (`BufferedImage`)：要应用马赛克效果的图像对象。
  - `blockSize` (`int`)：马赛克块的大小（以像素为单位）。
- **返回值**：
  - `BufferedImage`：应用马赛克效果后的图像对象。
- **示例**：

```java
BufferedImage mosaicImage = ImageUtils.applyMosaicInPlace(image, 10);
```

---

#### 注意事项

- **性能考虑**：某些操作（如缩放、旋转和应用马赛克）可能涉及大量的计算，对于大图像或高并发情况，应评估性能影响。
- **资源管理**：确保正确关闭所有打开的流和资源，避免内存泄漏。
- **线程安全**：本工具类中的方法未特别设计为线程安全，若需在多线程环境中使用，请自行实现同步控制。



---

### StringBaseUtils API 文档

#### 概述

`StringBaseUtils` 是一个用于处理字符串操作的工具类，提供了多种静态方法来检查字符串是否为空、是否包含特定子串、去除字符串两端的空格以及使用正则表达式验证字符串格式等功能。此工具类适用于需要对字符串进行各种处理的应用程序。

---

#### 方法概览

| 方法名 | 描述 |
| --- | --- |
| `isEmpty(CharSequence cs)` | 判断给定的字符序列是否为空或长度为0。 |
| `isNotEmpty(CharSequence cs)` | 判断给定的字符序列是否不为空且长度大于0。 |
| `isContainStr(CharSequence parent, CharSequence child)` | 检查一个字符序列是否包含另一个字符序列。 |
| `trim(CharSequence cs)` | 去除给定字符序列开头和结尾的空白字符。 |
| `isMatchRegex(String input, String regex)` | 使用给定的正则表达式来验证输入字符串。 |

---

#### 详细方法描述

##### `isEmpty(CharSequence cs)`

- **描述**：判断给定的字符序列是否为空或长度为0。
- **参数**：
  - `cs` (`CharSequence`)：要检查的字符序列。
- **返回值**：
  - `boolean`：如果 `cs` 为空或长度为0，则返回 `true`；否则返回 `false`。
- **示例**：

```java
boolean result = StringBaseUtils.isEmpty("hello");
// result = false
```

##### `isNotEmpty(CharSequence cs)`

- **描述**：判断给定的字符序列是否不为空且长度大于0。
- **参数**：
  - `cs` (`CharSequence`)：要检查的字符序列。
- **返回值**：
  - `boolean`：如果 `cs` 不为空且长度大于0，则返回 `true`；否则返回 `false`。
- **示例**：

```java
boolean result = StringBaseUtils.isNotEmpty("hello");
// result = true
```

##### `isContainStr(CharSequence parent, CharSequence child)`

- **描述**：检查一个字符序列是否包含另一个字符序列。
- **参数**：
  - `parent` (`CharSequence`)：要搜索的父字符串。
  - `child` (`CharSequence`)：要查找的子字符串。
- **返回值**：
  - `boolean`：如果 `parent` 包含 `child`，则返回 `true`；否则返回 `false`。
- **示例**：

```java
boolean result = StringBaseUtils.isContainStr("hello world", "world");
// result = true
```

##### `trim(CharSequence cs)`

- **描述**：去除给定字符序列开头和结尾的空白字符。
- **参数**：
  - `cs` (`CharSequence`)：要去除空白的字符序列。
- **返回值**：
  - `String`：去除空白后的字符串表示形式。
- **示例**：

```java
String result = StringBaseUtils.trim("   hello world   ");
// result = "hello world"
```

##### `isMatchRegex(String input, String regex)`

- **描述**：使用给定的正则表达式来验证输入字符串。
- **参数**：
  - `input` (`String`)：要匹配的输入字符串。
  - `regex` (`String`)：正则表达式模式。
- **返回值**：
  - `boolean`：如果输入字符串符合正则表达式的规则，则返回 `true`；否则返回 `false`。
- **示例**：

```java
boolean result = StringBaseUtils.isMatchRegex("example@example.com", StringBaseUtils.EMAIL_REGEX);
// result = true
```

---

#### 静态成员变量

| 成员变量名 | 描述 |
| --- | --- |
| `SPACE` | 定义了一个空格字符常量。 |
| `EMPTY_STR` | 定义了一个空字符串常量。 |
| `EMAIL_REGEX` | 定义了电子邮件地址的正则表达式。 |
| `CHINA_PHONE_REGEX` | 定义了中国手机号码的正则表达式。 |
| `URL_REGEX` | 定义了网址的正则表达式。 |
| `NUMBER_REGEX` | 定义了纯数字的正则表达式。 |
| `STRONG_PASSWORD_REGEX` | 定义了强密码的正则表达式。 |
| `IP_REGEX` | 定义了IP地址的正则表达式。 |

---
### 责任链模式实现说明文档

#### 概述

责任链模式（Chain of Responsibility Pattern）是一种行为设计模式，它允许你将请求沿着处理者链进行传递。接收到请求后，每个处理者都可以选择对其执行操作或将其传递给链上的下一个处理者。这种模式避免了请求发送者和接收者之间的耦合，使得多个对象都有机会处理请求，直到有一个对象真正处理它为止。

本文档将详细介绍如何使用 `IHandler` 和 `DutyChainFactory` 类来构建和执行一个责任链，并提供具体的代码示例。

---

#### 组件说明

##### IHandler<T, R>

- **描述**：抽象类，定义了责任链中的处理节点。
- **泛型参数**：
  - `T`：表示输入类型。
  - `R`：表示输出类型。
- **属性**：
  - `nextHandler` (`IHandler<T, R>`)：指向链中下一个处理节点的引用。
- **方法**：
  - `getNextHandler()`：获取下一个处理节点。
  - `setNextHandler(IHandler nextHandler)`：设置下一个处理节点。
  - `hasNext()`：检查是否还有下一个处理节点。
  - `handle(T t)`：处理逻辑，如果存在下一个处理节点，则将请求传递给下一个节点；否则返回 `null`。

##### DutyChainFactory<T, R>

- **描述**：工厂类，用于创建和初始化责任链。
- **泛型参数**：
  - `T`：表示输入类型。
  - `R`：表示输出类型。
- **属性**：
  - `first` (`IHandler<T, R>`)：责任链的第一个处理节点。
- **构造函数**：
  - `public DutyChainFactory(List<IHandler<T, R>> handleList)`：根据提供的处理节点列表初始化责任链。
- **方法**：
  - `executeHandle(T t)`：从责任链的第一个节点开始处理请求，并返回最终结果。

##### 使用示例

下面是一个简单的例子，展示了如何创建和执行一个责任链：

```java
package com.youyi;

import com.youyi.dutyChain.DutyChainFactory;
import com.youyi.dutyChain.IHandler;

import java.util.ArrayList;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        // 创建处理节点实例
        List<IHandler<Integer, Boolean>> handlers = new ArrayList<>();
        handlers.add(new OrderHandle());
        handlers.add(new CheckOrderHandle());
        handlers.add(new DoneOrderHandle());

        // 初始化责任链
        DutyChainFactory<Integer, Boolean> dutyChainFactory = new DutyChainFactory<>(handlers);

        // 执行责任链处理
        Boolean result = dutyChainFactory.executeHandle(0);
        System.out.println("Final result: " + result);
    }
}
```

---

#### 示例代码解析

1. **创建处理节点实例**

   ```java
   List<IHandler<Integer, Boolean>> handlers = new ArrayList<>();
   handlers.add(new OrderHandle());
   handlers.add(new CheckOrderHandle());
   handlers.add(new DoneOrderHandle());
   ```

   这里我们创建了一个 `ArrayList` 来存储三个自定义的处理节点：`OrderHandle`、`CheckOrderHandle` 和 `DoneOrderHandle`。每个处理节点都实现了 `IHandler<Integer, Boolean>` 接口 并通过super.hander() 调用下一个处理处理函数。

2. **初始化责任链**

   ```java
   DutyChainFactory<Integer, Boolean> dutyChainFactory = new DutyChainFactory<>(handlers);
   ```

   使用 `DutyChainFactory` 的构造函数来初始化责任链，传入之前创建的处理节点列表。构造函数会自动将这些节点链接起来，形成一个完整的责任链。

3. **执行责任链处理**

   ```java
   Boolean result = dutyChainFactory.executeHandle(0);
   System.out.println("Final result: " + result);
   ```

   最后，调用 `executeHandle` 方法来启动责任链处理流程，并传入初始数据 `0`。该方法会从第一个处理节点开始，依次传递数据，直到所有节点处理完毕或某个节点返回非空结果。

---

#### 注意事项

- **处理节点顺序**：责任链中处理节点的顺序非常重要，因为请求会按照这个顺序依次传递。确保节点的添加顺序符合业务逻辑的需求。
- **异常处理**：在实际应用中，应该考虑对可能出现的异常情况进行适当的处理，以保证系统的稳定性和健壮性。
- **线程安全**：当前实现的责任链模式并未考虑到多线程环境下的线程安全性问题。如果需要在多线程环境中使用，请自行实现必要的同步控制。

---

2. xxxx
3. xxxx




#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request