yujin-thumbnailator/API-USAGE.md

缩略图API使用示例

接口地址

基础URL: http://localhost:8080

1. 生成缩略图

接口信息

• 方法: GET
• 路径: /api/thumbnail/generate
• 功能: 根据文件路径生成指定尺寸的缩略图

请求参数

参数名	类型	必填	默认值	说明
path	String	是	-	相对文件路径
w	Integer	否	200	缩略图宽度(1-4000)
h	Integer	否	200	缩略图高度(1-4000)

请求示例

# 基本用法
curl "http://localhost:8080/api/thumbnail/generate?path=photos/sunset.jpg&w=300&h=300" \
  --output thumbnail.jpg

# 使用默认尺寸
curl "http://localhost:8080/api/thumbnail/generate?path=images/photo.png" \
  --output thumbnail.jpg

# 生成不同尺寸
curl "http://localhost:8080/api/thumbnail/generate?path=gallery/image.jpg&w=150&h=150" \
  --output small_thumbnail.jpg

响应说明

成功响应:

• 状态码: 200
• Content-Type: image/jpeg
• Cache-Control: max-age=3600
• 响应体: JPG格式的图片二进制数据

错误响应:

• 状态码: 500
• Content-Type: application/json

• 响应体:

  {
  "success": false,
  "message": "错误信息"
  }
  

常见错误

错误信息	原因	解决方案
"文件路径不能为空"	path参数为空	提供有效的文件路径
"宽度必须在1-4000像素之间"	w参数超出范围	设置正确的宽度值
"高度必须在1-4000像素之间"	h参数超出范围	设置正确的高度值
"源文件不存在"	文件路径不存在	检查文件路径是否正确
"不支持的文件类型"	文件格式不支持	使用支持的图片格式

2. 健康检查

接口信息

• 方法: GET
• 路径: /api/thumbnail/health
• 功能: 检查服务是否正常运行

请求示例

curl "http://localhost:8080/api/thumbnail/health"

响应示例

{
  "success": true,
  "message": "服务正常运行",
  "data": "OK",
  "timestamp": 1699123456789
}

3. 获取支持格式

接口信息

• 方法: GET
• 路径: /api/thumbnail/formats
• 功能: 获取支持的图片格式列表

请求示例

curl "http://localhost:8080/api/thumbnail/formats"

响应示例

{
  "success": true,
  "message": "获取支持格式成功",
  "data": ["jpg", "jpeg", "png", "webp"],
  "timestamp": 1699123456789
}

配置说明

文件路径配置

在 application.properties 中配置文件路径前缀：

# 文件路径前缀
thumbnail.file.prefix=D:/images/

缩略图存储

• 缩略图文件保存在原图片相同目录
• 文件名格式: 原文件名_宽度_高度.jpg
• 例如: sunset_300_300.jpg

缓存机制

• 首次生成缩略图时会保存到磁盘
• 后续相同参数的请求直接返回已缓存的缩略图
• 提高响应速度，减少服务器负载

JavaScript调用示例

// 生成缩略图并显示
async function generateThumbnail(path, width, height) {
    try {
        const url = `/api/thumbnail/generate?path=${encodeURIComponent(path)}&w=${width}&h=${height}`;
        const response = await fetch(url);

        if (response.ok) {
            const blob = await response.blob();
            const imageUrl = URL.createObjectURL(blob);

            // 显示图片
            const img = document.createElement('img');
            img.src = imageUrl;
            document.body.appendChild(img);

            return imageUrl;
        } else {
            const error = await response.json();
            console.error('生成失败:', error.message);
        }
    } catch (error) {
        console.error('请求失败:', error);
    }
}

// 使用示例
generateThumbnail('photos/sunset.jpg', 300, 300);

性能特点

1. 直接流输出: 缩略图直接写入HTTP响应流，无额外内存拷贝
2. 磁盘缓存: 生成的缩略图保存到磁盘，避免重复计算
3. 高效处理: 基于Thumbnailator库，高性能图片处理
4. 内存优化: 避免大图片在内存中的完整加载