JmsImage 1.x.x 使用指南

📖 版本说明

ℹ️ 关于此版本

JmsImage 1.x.x 是框架的初始版本，提供了基础的图片处理能力。虽然此版本已经归档，但它奠定了 JmsImage 的核心架构和设计理念。建议新用户直接使用 2.x.x 版本。

1.x.x 核心特性

🎯

执行器模式

采用 execute() 方法执行图片处理，链式调用

🔄

撤销/重做

支持 undo() 和 redo() 操作，历史栈管理

🛡️

资源管理

destroy() 方法释放资源，防止内存泄漏

🧩

模块化 Handler

水印、滤镜、压缩等处理器独立封装

🚀 快速开始

第一个 JmsImage 程序

                // ① 读取图片
JmsImage image = JmsImage.read("input.png");

// ② 执行水印处理
image.execute(new ImageWaterMark.BatchAddTextWaterMarkHandler(
    "版权所有",                    // 水印文字
    new Color(255, 255, 255, 64), // 半透明白色
    new Font("微软雅黑", 40),      // 字体
    30,                            // 旋转角度
    100,                           // 间隔
    true                           // 自动销毁
));

// ③ 保存图片
image.write("output.jpg");

// ④ 释放资源
image.destroy();
            

✅ 简化版（推荐）

                    JmsImage.read("input.png")
    .execute(new ImageWaterMark.BatchAddTextWaterMarkHandler(...))
    .write("output.jpg")
    .destroy();
                

📦 核心 API

1. JmsImage - 图片实体类

JmsImage 是框架的核心类，提供以下主要方法：

方法	说明	示例
`read(String path)`	从文件路径读取图片	`JmsImage.read("test.png")`
`read(InputStream is)`	从输入流读取图片	`JmsImage.read(inputStream)`
`create(w, h, type)`	创建空白图片	`JmsImage.create(800, 600, TYPE_INT_RGB)`
`execute(handler)`	执行图片处理器	`image.execute(new DarkColorFilterHandler(true))`
`write(String path)`	保存图片到文件	`image.write("output.jpg")`
`undo()`	撤销一步操作	`image.undo()`
`redo()`	重做一步操作	`image.redo()`
`store()`	还原到原始图片	`image.store()`
`destroy()`	释放资源	`image.destroy()`

2. 图片处理器（Handlers）

（1）水印处理器 - ImageWaterMark

                // 去水印（4 种算法）
new RemoveWaterMarkAverageHandler(x, y, width, height, true);
new RemoveWaterMarkBlurImprovedHandler(x, y, width, height, true);
new RemoveWaterMarkSurroundImprovedHandler(x, y, width, height, true);
new RemoveWaterMarkGradientHandler(x, y, width, height, true);
            

（2）滤镜处理器 - ImageFilter

                new DarkColorFilterHandler(true);         // 灰度处理
new SmallColorFilterHandler(true);        // 缩小色彩
new NegativeFilterHandler(true);          // 反色处理
new MosaicFilterHandler(true);            // 马赛克
            

（3）压缩处理器 - ImageCompress

                new ProportionCompressHandler(0.5, true);   // 按比例压缩 50%
new QualityCompressHandler(0.8f, true);   // JPEG 质量 80%
            

（4）基础处理器 - ImageBasicHandlers

                new AddNoiseHandler(100, true);       // 添加噪点
new AddLinesHandler(50, true);        // 添加线条
            

💡 实战场景

场景 1：图片去水印

                // 去除图片右下角的水印
JmsImage.read("watermarked.png")
    .historySwitchOn()
    .execute(new RemoveWaterMarkBlurImprovedHandler(
        800, 600, 200, 100, true  // x, y, width, height
    ))
    .write("clean.jpg")
    .destroy();
            

场景 2：图片压缩

                // 先按比例压缩，再按质量压缩
JmsImage.read("large.png")
    .execute(new ProportionCompressHandler(0.5, true))
    .execute(new QualityCompressHandler(0.75f, true))
    .write("compressed.jpg")
    .destroy();
            

场景 3：图片编辑器（支持撤销）

                public class SimpleEditor {
    private JmsImage image;

    public void load(String path) {
        image = JmsImage.read(path).historySwitchOn();
    }

    public void applyGrayscale() {
        image.execute(new DarkColorFilterHandler(true));
    }

    public void applyNegative() {
        image.execute(new NegativeFilterHandler(true));
    }

    public void undo() {
        image.undo();
    }

    public void save(String path) {
        image.write(path);
    }

    public void close() {
        image.destroy();
    }
}
            

⚙️ 高级用法

拦截器：流程控制

                image.execute(handler, new HandlerInterceptor() {
    @Override
    public boolean preHandle(BufferedImage image) {
        System.out.println("处理前检查...");
        return true;  // false 中断处理
    }

    @Override
    public BufferedImage postHandle(BufferedImage result) {
        System.out.println("处理后优化...");
        return result;
    }

    @Override
    public void exceptionHandle(BufferedImage image, Exception e) {
        System.out.println("捕获异常：" + e.getMessage());
    }
});
            

日志适配

                // 使用 LogAdapter 适配第三方日志框架
Logger logger = new LogAdapter<>(slf4jLogger);

image.logInfo(logger, "开始处理图片")
     .execute(handler)
     .logDebug(logger, "处理完成")
     .write("output.jpg")
     .destroy();
            

内部容器机制

                // 使用内部容器暂存图片
ImageContainer container = new ImageContainer(jmsImage);

jmsImage.putImageIntoInternalContainer()
        .releaseInternalContainerAndDestroy();

// 从容器获取图片
BufferedImage img = container.get();
            

⚠️ 注意事项

❌ 常见错误

忘记调用 destroy() → 内存泄漏
重复使用已销毁的对象 → 抛出 JmsImageException
Handler 复用 → 可能导致状态混乱
未开启历史栈就调用 undo()/redo() → 功能无效

✅ 最佳实践

始终使用 autoDestroy = true，让框架自动管理资源
需要撤销功能时，先调用 historySwitchOn()
使用 try-finally 确保资源释放
批量处理时注意及时调用 destroy()

1.x.x 版本限制

ℹ️ 已知限制

不支持泛型重构，类型安全性较低
缺少部分高级滤镜和处理算法
性能优化不如 2.x.x 版本完善
文档和示例相对较少