缩略图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/{path}&w=300&h=300" \
  --output thumbnail.jpg


### 响应说明

### 常见错误

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

## 2. 健康检查

### 接口信息
- **方法**: GET
- **路径**: `/api/thumbnail/health`
- **功能**: 检查服务是否正常运行

### 请求示例

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


### 响应示例

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


## 3. 获取支持格式

### 接口信息
- **方法**: GET
- **路径**: `/api/thumbnail/formats`
- **功能**: 获取支持的图片格式列表

### 请求示例

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


### 响应示例

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


## 配置说明

### 文件路径配置

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

properties

文件路径前缀

thumbnail.file.prefix=D:/images/


### 缩略图存储

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

### 缓存机制

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

## JavaScript调用示例

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); ```

性能特点

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

API-USAGE.md 3.6 KB Permalink Istoric Crud