# jtool

**Repository Path**: ccbx/jtool

## Basic Information

- **Project Name**: jtool
- **Description**: jdk1.8+ 工具库（包括文件操作、压缩解压、日期处理、系统信息获取、缓存管理、HTTP 请求、JSON 序列化、Shell 命令执行、JavaFX 界面开发、SMB 文件共享以及 Spring 生态集成等。）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-29
- **Last Updated**: 2026-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, Javafx, Spring, minio, compress

## README



# JTool 项目简介

JTool 是一个基于 Java 的多功能工具库集合，旨在简化开发任务并提供常见的工具方法，包括文件操作、压缩解压、日期处理、系统信息获取、缓存管理、HTTP 请求、JSON 序列化、Shell 命令执行、JavaFX 界面开发、SMB 文件共享以及 Spring 生态集成等。

## 项目结构

该项目由多个模块组成，每个模块专注于特定的功能领域：

### 汇总模块 (`jtool-all`)

- **功能**: 整合所有模块的功能，提供一站式依赖引入。

### 核心模块 (`jtool-core`)

- **功能**: 提供通用工具类，涵盖文件操作、日期处理、字符串处理、集合操作、系统信息获取等基础功能。
- **关键类**:
  - `FileUtil`: 文件和目录操作工具类，支持文件搜索、复制、移动、清理等功能
  - `DateUtil`: 时间和日期格式化工具类
  - `StrUtil`: 字符串判空、处理工具类
  - `SetUtil`: Set 集合创建和操作工具类
  - `SystemUtil`: 系统和命令执行工具类
  - `DiskUtil`: 磁盘空间获取工具类
  - `MimeTypeUtil`: MIME 类型推断工具类
  - `ReflectUtil`: 反射操作工具类
  - `ShutdownHookUtil`: 关闭钩子管理工具类
  - `ProgressCallback`: 用于进度回调的函数式接口
  - `ProcessBytesCallback`: 用于字节处理进度回调的函数式接口

### 缓存模块 (`jtool-cache`)

- **功能**: 基于 Caffeine 提供高性能的本地缓存解决方案。
- **关键类**:
  - `CaffeineFactory`: Caffeine 缓存构建工厂，支持配置容量、超时时间、移除监听器等
  - `SoftReferenceCache`: 使用软引用实现的缓存，在内存紧张时自动回收
  - `CaffeineListenerBase`: 缓存移除监听器基类，支持显式移除、替换、回收、过期、大小变化等事件
  - `CaffeineExpiredListener`: 专门处理缓存过期事件的监听器

### 压缩模块 (`jtool-compress`)

- **功能**: 支持多种压缩格式（ZIP、TAR、GZ、TAR.GZ）的压缩和解压操作，支持进度回调。
- **关键类**:
  - `CompressUtil`: 压缩操作的统一入口，提供 Apache 和 Java 两种实现
  - `ApacheArchiveTool`: 使用 Apache Commons Compress 实现的归档工具
  - `JavaCompressUtil`: 使用 Java 内置 ZIP API 实现的压缩工具
  - `ApacheZipTool`: ZIP 格式具体实现
  - `ApacheTarTool`: TAR 格式具体实现
  - `ApacheGzTool`: GZ 格式具体实现
  - `ApacheTarGzTool`: TAR.GZ 格式具体实现
  - `CountingInputStream`: 用于统计读取字节数的输入流

### JSON 模块 (`jtool-json`)

- **功能**: 提供基于 Jackson 的 JSON 序列化与反序列化工具，支持深度拷贝、文件操作、JSON 美化等。
- **关键类**:
  - `JacksonUtil`: 对象与 JSON 字符串之间的转换工具，支持pretty print
  - `JacksonCopyStrategy`: 基于 Jackson 的拷贝策略实现
  - `CustomJsonPrettyPrinter`: 自定义 JSON 格式化输出器

### HTTP 模块 (`jtool-http`)

- **功能**: 提供标准化的 HTTP 响应封装，支持 GET/POST 请求。
- **关键类**:
  - `ApiResp<R>`: HTTP 响应的标准封装类，包含状态码、消息和数据
  - `HttpProUtil`: HTTP 请求工具类，支持超时配置和类型安全的响应处理

### Shell 模块 (`jtool-shell`)

- **功能**: 提供 Shell 命令、Shell 脚本、BAT 脚本的封装执行，支持同步和异步执行，日志记录。
- **关键类**:
  - `ShellUtil`: Shell 操作统一入口
  - `CommandExecutor`: 命令行执行器
  - `ShellExecutor`: Shell 脚本执行器
  - `BatExecutor`: BAT 脚本执行器
  - `StreamProcessor`: 输出流处理器，支持日志文件记录
  - `ProcessThreadPoolManager`: 进程线程池管理器

### FX 模块 (`jtool-fx`)

- **功能**: 基于 JavaFX 的界面开发工具库，提供窗口管理、任务调度、UI 组件等。
- **关键类**:
  - `FxUtil`: JavaFX 工具类
  - `FxTaskUtil`: 任务调度工具类，支持异步任务、超时控制、线程池管理
  - `FxUiUtil`: UI 组件工具类
  - `IconUtil`: 图标工具类
  - `AlertUtil`: 弹窗工具类
  - `BareWindowComponent`: 简单窗口组件
  - `SimpleProgress`: 简单进度条
  - `BytesHandlingProgress`: 字节处理进度组件
  - `CustomTitleBarAlert`: 自定义标题栏弹窗
  - `CodeWindowBase`: 窗口基类
  - `StageManage`: 舞台管理器

### FX Spring 模块 (`jtool-fx-spring`)

- **功能**: JavaFX 与 Spring 框架集成，提供 Spring 上下文初始化支持。
- **关键类**:
  - `FxSpringInitializer`: Spring 应用上下文初始化器

### Spring 模块 (`jtool-spring`)

- **功能**: Spring 框架集成工具，提供上下文获取、环境配置、线程池管理等功能。
- **关键类**:
  - `SpringContextUtil`: Spring 上下文工具类
  - `SpringEnvUtil`: Spring 环境工具类
  - `ThreadPoolTaskConfig`: 异步线程池配置类
  - `SpringGlobalAsyncExceptionHandler`: 异步全局异常处理器

### MinIO 模块 (`jtool-spring-minio`)

- **功能**: MinIO 对象存储服务集成工具。
- **关键类**:
  - `MinioUtil`: MinIO 操作工具类，支持文件上传、下载、预签名URL、桶管理等功能
  - `MinioConfig`: MinIO 配置属性类
  - `UploadProcessInputStream`: 带进度反馈的输入流
  - `UploadBytesInputStream`: 带字节处理回调的输入流

### SMB 模块 (`jtool-smb`)

- **功能**: SMB/CIFS 文件共享协议支持。
- **关键类**:
  - `SmbUtil`: SMB 操作工具类，支持文件上传、下载、目录创建等功能

## 依赖管理

本项目使用 Maven 进行依赖管理，各模块可通过 Maven 引入：

```xml
<!-- 汇总模块 (包含所有功能) -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-all</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- 核心模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-core</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- 缓存模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-cache</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- 压缩模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-compress</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- JSON 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-json</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- HTTP 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-http</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- Shell 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-shell</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- FX 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-fx</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- FX Spring 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-fx-spring</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- Spring 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-spring</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- MinIO 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-spring-minio</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- SMB 模块 -->
<dependency>
    <groupId>top.ccbx</groupId>
    <artifactId>jtool-smb</artifactId>
    <version>1.0.0</version>
</dependency>
```

## 使用示例

### 文件操作示例

```java
import top.ccbx.core.io.FileUtil;
import java.nio.file.Path;
import java.util.List;

// 检查文件是否存在
boolean exists = FileUtil.exist(Path.of("/path/to/file"));

// 查找文件
List<Path> files = FileUtil.findFiles(
    Path.of("/search/dir"), 
    "keyword", 
    ".java", ".xml"
);

// 清理目录
FileUtil.cleanDirInExtensions(Path.of("/temp"), "log", "tmp");
```

### 压缩解压示例

```java
import top.ccbx.compress.CompressUtil;
import top.ccbx.compress.enums.CompressLibrary;
import java.nio.file.Path;

// 压缩文件
CompressUtil.compress(
    CompressLibrary.APACHE, 
    Path.of("/output.zip"),
    Path.of("/input/file1.txt"),
    Path.of("/input/file2.txt")
);

// 解压文件
CompressUtil.uncompressed(
    CompressLibrary.APACHE,
    Path.of("/input.zip"),
    Path.of("/output/dir"),
    null,  // 不创建子目录
    null   // 无进度回调
);
```

### JSON 处理示例

```java
import top.ccbx.json.JacksonUtil;
import com.fasterxml.jackson.core.type.TypeReference;

// 对象转 JSON
User user = new User("张三", 25);
String json = JacksonUtil.objToJson(user, true);

// JSON 转对象
User result = JacksonUtil.jsonToObj(json, new TypeReference<User>() {});

// 深度拷贝
List<User> copied = JacksonUtil.deepCopyByJackson(originalList, User.class);
```

### HTTP 请求示例

```java
import top.ccbx.http.domain.ApiResp;
import top.ccbx.http.utils.HttpProUtil;
import com.fasterxml.jackson.core.type.TypeReference;

// GET 请求
ApiResp<User> resp = HttpProUtil.getApiRespJson(
    "https://api.example.com/user/1",
    5000,  // 超时时间
    new TypeReference<ApiResp<User>>() {}
);

if (resp.isSuccess()) {
    User user = resp.getData();
}

// POST 请求
Map<String, Object> params = new HashMap<>();
params.put("name", "李四");
ApiResp<String> postResp = HttpProUtil.postApiRespJson(
    "https://api.example.com/create",
    params,
    new TypeReference<ApiResp<String>>() {}
);
```

### 缓存使用示例

```java
import top.ccbx.cache.CaffeineFactory;
import com.github.benmanes.caffeine.cache.Cache;

// 创建缓存
Cache<String, User> cache = CaffeineFactory.<String, User>build()
    .maximumSize(100)
    .expireAfterWrite(10, TimeUnit.MINUTES)
    .build();

// 使用缓存
cache.put("user:1", new User("王五", 30));
User user = cache.get("user:1", k -> fetchUserFromDb(k));
```

### Shell 命令示例

```java
import top.ccbx.shell.ShellUtil;

// 执行 Shell 命令
boolean success = ShellUtil.executeCommand("ls -la", true);

// 异步执行
ShellUtil.executeCommandNoWait("sleep 10 && echo done", true);

// 执行 Shell 脚本
ShellUtil.executeSh("/path/to/script.sh", true);

// 执行 BAT 脚本
ShellUtil.executeBat("C:\\scripts\\backup.bat", true);
```

### JavaFX 任务调度示例

```java
import top.ccbx.fx.utils.FxTaskUtil;

// 异步任务
FxTaskUtil.async(() -> {
    // 后台执行的任务
    return computeResult();
}, result -> {
    // 完成回调 (在 JavaFX 线程执行)
    updateUI(result);
}, error -> {
    // 错误处理
    error.printStackTrace();
}, () -> {
    // 最终回调
    hideLoading();
}, Duration.ofSeconds(30));  // 超时设置

// 延迟任务
FxTaskUtil.runDelay(() -> {
    System.out.println("延迟执行的任务");
}, Duration.ofSeconds(5));
```

### MinIO 操作示例

```java
import top.ccbx.spring.minio.utils.MinioUtil;
import org.springframework.web.multipart.MultipartFile;

// 配置 MinIO (application.yml)
// ccbx.minio.endpoint: http://localhost:9000
// ccbx.minio.bucketName: mybucket
// ccbx.minio.accessKey: minioadmin
// ccbx.minio.secretKey: minioadmin

@Autowired
private MinioUtil minioUtil;

// 上传文件
minioUtil.fileUpload(file, "object-name");

// 下载文件
minioUtil.fileDownloadToLocal("object-name", "/local/path");

// 获取预签名 URL (7天有效期)
String url = minioUtil.filePreUrl("object-name", 7, TimeUnit.DAYS);

// 公共访问 URL
String publicUrl = minioUtil.filePublicUrl("object-name");
```

### SMB 操作示例

```java
import top.ccbx.smb.SmbUtil;
import java.nio.file.Path;

// 初始化认证信息
SmbUtil.initCIFSContext("domain", "username", "password");

// 下载文件
boolean success = SmbUtil.download(
    "smb://server/share/file.txt",
    Path.of("/local/file.txt")
);

// 上传文件
SmbUtil.upload(
    "smb://server/share/uploaded.txt",
    Path.of("/local/file.txt")
);
```

## 版本要求

- **Java**: JDK 1.8 或更高版本
- **Maven**: 3.6 或更高版本

## 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

## 贡献指南

欢迎贡献代码或提出问题。请参考项目的 [贡献指南](CONTRIBUTING.md) 进行提交。