JmsFile 1.x.x 使用指南

📖 快速开始

什么是 JmsFile？

JmsFile 是一个轻量级的文件处理工具库，提供了灵活的文件读写、处理和拦截机制。它根据文件大小自动选择内存或磁盘存储（阈值：4MB），支持流式处理和可扩展的处理器模式。

💡 核心理念

智能存储模式切换（内存/磁盘）
流式 API，链式调用
处理器模块化，职责单一
完善的资源管理机制
支持拦截器，流程可控

第一个 JmsFile 程序

// ① 读取文件
JmsFile file = JmsFile.read(new File("input.txt"));

// ② 写入到新文件
file.write(new File("output.txt"));

// ③ 释放资源
file.destroy();

✅ 简化版（推荐）

JmsFile.read(new File("input.txt"))
  .write(new File("output.txt"))
  .destroy();

从流中读取（推荐用于大文件）

// 使用 InputStream 读取，自动选择存储模式
try (InputStream input = new FileInputStream("large_file.zip")) {
    JmsFile file = JmsFile.read(input);
    
    // 写入到输出流
    try (OutputStream output = new FileOutputStream("copy.zip")) {
        file.write(output);
    }
    
    file.destroy();
}

📦 核心概念

1. FileMetaInfo - 文件元数据信息

FileMetaInfo 封装文件的字节数据和元信息，根据文件大小自动选择存储模式。

重要特性

≤ 4MB 的文件保存在内存（MEMORY 模式）
> 4MB 的文件自动切换到磁盘（DISK 模式）
临时文件保存在 ${user.home}/JmsFileTemp
提供统一的输入流接口，无需关心存储位置

// 从字节数组创建
byte[] bytes = Files.readAllBytes(Paths.get("file.txt"));
FileMetaInfo meta = new FileMetaInfo(bytes);

// 从输入流创建（推荐）
InputStream input = new FileInputStream("file.txt");
FileMetaInfo meta = new FileMetaInfo(input);

// 获取文件输入流
InputStream fis = meta.getInputStream();

// 写入到输出流
meta.write(new FileOutputStream("output.txt"));

// 配置文件路径
meta.setCompleteFilePath("C:/output/file.txt");

// 清理资源
meta.delete();   // 删除临时文件
meta.destroy();  // 释放对象引用

2. JmsFile - 文件实体类

JmsFile 是高级文件操作封装，提供链式调用和处理器执行能力。

// 静态工厂方法创建
JmsFile file = JmsFile.create(new byte[1024]);           // 从字节数组
JmsFile file = JmsFile.read(new File("input.txt"));     // 从文件
JmsFile file = JmsFile.read(inputStream);              // 从流

// 写入操作
file.write(new FileOutputStream("output.txt"));  // 到输出流
file.write(new File("output.txt"));            // 到文件
file.write("C:/output/file.txt");              // 到路径
file.write();                                   // 到配置的路径

// 链式调用
file.logInfo(logger, "开始处理")
    .execute(handler)
    .logInfo(logger, "处理完成")
    .write("output.txt")
    .destroy();

3. FileHandler - 文件处理器

处理器是 JmsFile 的灵魂！ 所有文件处理逻辑都在 Handler 中实现。

// 自定义处理器示例
public class FileEncryptHandler extends AbstractFileHandler {
    
    public FileEncryptHandler(boolean autoDestroy) {
        super(autoDestroy);
    }
    
    @Override
    protected void handleFile() {
        try {
            // 获取原始文件流
            InputStream input = this.fileMetaInfo.getInputStream();
            byte[] original = input.readAllBytes();
            
            // 执行加密
            byte[] encrypted = encrypt(original);
            
            // 更新文件元数据
            FileMetaInfo encryptedMeta = new FileMetaInfo(encrypted);
            encryptedMeta.setFileName(this.fileMetaInfo.getFileName());
            encryptedMeta.setFileExtension("enc");
            
            this.fileMetaInfo.destroy();
            this.fileMetaInfo = encryptedMeta;
            
        } catch (Exception e) {
            throw new RuntimeException("加密失败", e);
        }
    }
    
    private byte[] encrypt(byte[] data) {
        // 实现加密算法
        return data;
    }
}

4. HandlerInterceptor - 处理器拦截器

在文件处理前后进行拦截处理，实现流程控制。

// 文件验证拦截器
public class FileValidationInterceptor implements HandlerInterceptor {
    
    @Override
    public boolean preHandle(FileHandler handler) {
        FileMetaInfo meta = handler.getFileMetaInfo();
        String extension = meta.getFileExtension();
        
        // 验证文件类型
        if (!"txt".equalsIgnoreCase(extension)) {
            System.out.println("不支持的文件类型：" + extension);
            return false; // 中断处理
        }
        
        return true; // 继续处理
    }
    
    @Override
    public FileMetaInfo postHandle(FileHandler handler, FileMetaInfo result) {
        // 处理后的操作
        System.out.println("文件处理完成：" + result.getFileName());
        return result;
    }
    
    @Override
    public void exceptionHandle(FileHandler handler, Exception e) {
        System.err.println("文件处理异常：" + e.getMessage());
        e.printStackTrace();
    }
}

// 使用拦截器
file.execute(handler, new FileValidationInterceptor());

5. autoDestroy - 自动销毁

✅ 最佳实践：永远使用 true

让框架自动管理资源，避免内存泄漏！

💡 实战场景

场景 1：文件上传处理

@PostMapping("/upload/file")
public ResponseResult uploadFile(MultipartFile file) {
    try {
        // 读取上传的文件
        JmsFile jmsFile = JmsFile.read(file.getInputStream());
        
        // 执行文件校验
        jmsFile.execute(new FileValidationHandler(true), 
                       new FileValidationInterceptor());
        
        // 保存到目标路径
        String targetPath = "uploads/" + System.currentTimeMillis() + "_" + file.getOriginalFilename();
        jmsFile.write(targetPath);
        jmsFile.destroy();
        
        return ResponseResult.success("上传成功", targetPath);
    } catch (Exception e) {
        return ResponseResult.error("上传失败：" + e.getMessage());
    }
}

场景 2：文件加密解密

// 加密文件
public void encryptFile(String inputPath, String outputPath) {
    JmsFile.read(inputPath)
        .execute(new FileEncryptHandler(true))
        .write(outputPath + ".enc")
        .destroy();
}

// 解密文件
public void decryptFile(String encryptedPath, String outputPath) {
    JmsFile.read(encryptedPath)
        .execute(new FileDecryptHandler(true))
        .write(outputPath)
        .destroy();
}

场景 3：批量文件压缩

public void batchCompressFiles(List<String> filePaths) {
    for (String path : filePaths) {
        JmsFile.read(path)
            .execute(new GzipCompressHandler(true))
            .write(path + ".gz")
            .destroy();
    }
}

场景 4：文件内容转换

// JSON 转 XML
JmsFile.read("data.json")
    .execute(new JsonToXmlHandler(true))
    .write("data.xml")
    .destroy();

// CSV 转 Excel
JmsFile.read("data.csv")
    .execute(new CsvToExcelHandler(true))
    .write("data.xlsx")
    .destroy();

场景 5：多处理器串联

// 文件处理流水线
JmsFile.read("original.txt")
    .execute(new FileValidateHandler(true))       // ① 验证
    .execute(new FileEncryptHandler(true))         // ② 加密
    .execute(new GzipCompressHandler(true))        // ③ 压缩
    .execute(new AddChecksumHandler(true))         // ④ 添加校验和
    .write("processed.dat")
    .destroy();

⚙️ 高级用法

配置文件路径后写入

JmsFile file = JmsFile.read(new File("source.jpg"));

// 配置目标路径
file.getFileByteInfo().setCompleteFilePath("C:/images/target.jpg");

// 写入到配置的路径
file.write();

file.destroy();

日志记录

Logger logger = Logger.getLogger("FileProcessor");

JmsFile file = JmsFile.read(new File("data.txt"));

// 链式日志记录
file.logDebug(logger, "开始读取文件...")
    .logInfo(logger, "文件大小：" + file.getFileByteInfo().getFileName())
    .execute(handler)
    .logWarn(logger, "处理过程中出现警告")
    .logError(logger, "发生错误", exception)
    .write("output.txt")
    .message("文件已保存\n")
    .destroy();

获取文件信息

FileMetaInfo meta = file.getFileByteInfo();

// 获取文件名
String fileName = meta.getFileName();                    // 不带扩展名
String fileNameWithExt = meta.getFileNameWithExtension(); // 带扩展名
String extension = meta.getFileExtension();              // 仅扩展名

// 获取文件路径
String completePath = meta.getCompleteFilePath();
String pathWithoutName = meta.getFilePathNotFileName();

// 获取存储模式
FileMetaMode mode = meta.getMode();  // MEMORY 或 DISK

// 获取输入流
InputStream input = meta.getInputStream();

实用工具方法

// 从路径提取文件名
String fileName = FileMetaInfo.getFileName("C:/path/to/file.txt", false); // file.txt
String fileNameNoExt = FileMetaInfo.getFileName("C:/path/to/file.txt", true);  // file

// 从路径提取扩展名
String extension = FileMetaInfo.getFileExtension("file.txt");  // txt

⚠️ 注意事项

❌ 常见错误

忘记调用 destroy() → 内存泄漏（特别是大文件）
重复使用已销毁的对象 → 抛出 JmsFileException
Handler 复用 → 可能导致状态混乱
在处理器外部修改 FileMetaInfo 引用 → 破坏封装性

✅ 最佳实践

始终使用 try-finally 确保资源释放
大文件优先使用 InputStream 方式读取
Handler 的 autoDestroy 参数永远传 true
需要多次使用文件时，先复制到临时文件

资源管理示例

// ✅ 推荐：使用 try-finally
JmsFile file = null;
try {
    file = JmsFile.read(new File("input.txt"));
    // 处理文件...
} finally {
    if (file != null) {
        file.destroy();
    }
}

// ✅ 推荐：链式调用，自动管理
JmsFile.read(new File("input.txt"))
    .execute(handler)
    .write("output.txt")
    .destroy();

临时文件管理

// 磁盘模式下会创建临时文件
// 默认路径：${user.home}/JmsFileTemp

// 手动删除临时文件
FileMetaInfo meta = file.getFileByteInfo();
meta.delete();   // 删除临时文件
meta.destroy();  // 释放资源

// 或者直接使用 JmsFile.destroy()
file.destroy();  // 自动清理所有资源

异常处理

try {
    JmsFile file = JmsFile.read(new File("input.txt"));
    file.execute(new CustomHandler(true));
    file.write(new File("output.txt"));
    file.destroy();
    
} catch (JmsFileException e) {
    // 文件处理异常（已包装）
    logger.error("文件处理失败", e);
    
} catch (IOException e) {
    // IO 异常
    logger.error("IO 错误", e);
}

📊 性能参考

基于实测数据：

操作	文件大小	模式	耗时	说明
读取 + 写入	100KB	MEMORY	~5ms	✅ 极快
读取 + 写入	1MB	MEMORY	~20ms	✅ 很快
读取 + 写入	10MB	DISK	~150ms	✅ IO 瓶颈
读取 + 写入	100MB	DISK	~1.2s	✅ 大文件友好
资源销毁	任意	-	~1ms	✅ 极快

结论

小文件（≤ 4MB）使用内存模式，速度极快；大文件自动切换到磁盘模式，避免内存溢出。 4MB 是推荐的阈值，可根据实际需求调整。

存储模式对比

特性	MEMORY 模式	DISK 模式
适用文件大小	≤ 4MB	> 4MB
访问速度	极快（纳秒级）	较快（毫秒级，IO 限制）
内存占用	高（与文件大小相同）	低（仅缓冲区）
临时文件	无	有（自动清理）
GC 压力	较高	较低

🎯 总结

JmsFile 的优势

✅ 易用性：流式 API，代码简洁
✅ 智能性：自动选择存储模式（MEMORY/DISK/PROXY）
✅ 扩展性：模块化 Handler，基于 AbstractFileHandler 快速开发
✅ 安全性：完善的资源生命周期管理（init/destroy）
✅ 灵活性：支持拦截器、链式调用、日志记录
✅ 性能优：小文件极速，大文件友好，PROXY 模式延迟加载
✅ 统一异常：JmsFileException 统一包装处理

核心组件

组件	职责	关键特性
`JmsFile`	文件实体，高级操作	AutoCloseableResource、Executor、链式调用
`FileMetaInfo`	文件元数据封装	三模式切换、统一流接口、智能存储
`FileHandler`	文件处理逻辑	AutoCloseableResource、泛型返回、autoDestroy
`AbstractFileHandler`	处理器基类	状态管理、通用方法、简化开发
`HandlerInterceptor`	处理拦截器	preHandle/postHandle/exceptionHandle
`JmsFileException`	统一异常	继承 JmsBasicException、三种构造方法

适用场景

Web 应用文件上传下载
文件加密解密工具
批量文件转换器（JSON→XML、CSV→Excel）
文件压缩解压程序（GZIP、ZIP）
文件内容处理（敏感词过滤、格式转换）
任何需要文件处理的 Java 应用

🚀 快速上手口诀

一读（read）、二处理（execute）、三保存（write）、四销毁（destroy）
小文件内存，大文件磁盘，流用代理
Handler 传 true，资源不用愁
拦截器把关，流程全掌控
抽象基类好，状态自动管