yujin-thumbnailator

缩略图生成器

基于 Kotlin + Solon Boot + Thumbnailator 的高性能缩略图生成服务。

功能特性

• ✅ 基于文件路径的缩略图生成
• ✅ 自动缓存检查（缩略图已存在则直接返回）
• ✅ 直接流输出，高性能无内存拷贝
• ✅ 批量多尺寸缩略图生成
• ✅ 支持多种图片格式 (JPG, PNG, WebP, BMP, GIF)
• ✅ 固定JPG输出格式，优化性能
• ✅ 文件大小限制和类型验证
• ✅ RESTful API 接口
• ✅ Web 测试界面
• ✅ 可配置的文件路径前缀

技术栈

• 后端框架: Solon Boot 2.7.6
• 编程语言: Kotlin 1.9.21
• 图片处理: Thumbnailator 0.4.20
• 构建工具: Maven
• JDK版本: 17

快速开始

1. 环境要求

• JDK 17+
• Maven 3.6+

2. 运行项目

开发环境

# 使用启动脚本（推荐）
start-dev.bat

# 或者使用 Maven 命令
mvn clean compile
mvn exec:java -Dexec.mainClass="com.yujin.thumbnail.ThumbnailApplicationKt" -Dspring.profiles.active=dev

测试环境

# 使用启动脚本
start-test.bat

# 或者使用 Maven 命令
mvn exec:java -Dexec.mainClass="com.yujin.thumbnail.ThumbnailApplicationKt" -Dspring.profiles.active=test

生产环境

# 使用启动脚本
start-prod.bat

# 或者使用 Maven 命令
mvn exec:java -Dexec.mainClass="com.yujin.thumbnail.ThumbnailApplicationKt" -Dspring.profiles.active=prod

3. 访问测试页面

• 开发环境: http://localhost:8080/index.html
• 测试环境: http://localhost:8081/index.html
• 生产环境: http://localhost/index.html

环境配置

项目支持多环境配置，使用YAML格式：

• application.yml - 主配置文件
• application-dev.yml - 开发环境配置
• application-test.yml - 测试环境配置
• application-prod.yml - 生产环境配置

详细配置说明请参考：环境配置文档

API 接口

1. 生成单个缩略图

接口: GET /api/thumbnail/generate

参数:

• path: 相对文件路径 (必需)
• w: 目标宽度，默认 200px
• h: 目标高度，默认 200px

响应: 返回生成的缩略图文件 (JPG格式)

功能特性:

• 自动检查缩略图是否已存在
• 如存在则直接返回，不存在则生成后返回
• 缩略图文件名格式: 原文件名_w_h.jpg
• 缩略图保存在与原文件相同目录下
• 直接流输出，无内存拷贝，高性能

示例:

# 生成 300x300 的缩略图
curl "http://localhost:8080/api/thumbnail/generate?path=photos/sunset.jpg&w=300&h=300" \
  --output thumbnail_300_300.jpg

2. 批量生成缩略图

接口: POST /api/thumbnail/batch

参数:

• file: 上传的图片文件 (form-data)

• 请求体 (JSON):

  {
  "sizes": [
  {"width": 100, "height": 100},
  {"width": 200, "height": 200},
  {"width": 300, "height": 300}
  ],
  "quality": 0.8,
  "format": "jpg"
  }
  

响应: 返回包含所有尺寸缩略图的 ZIP 文件

3. 获取支持格式

接口: GET /api/thumbnail/formats

响应:

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

4. 健康检查

接口: GET /api/thumbnail/health

响应:

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

配置说明

项目使用YAML格式的配置文件，支持多环境配置。

主配置文件: application.yml

spring:
  profiles:
    active: dev  # 默认激活开发环境

server:
  host: 0.0.0.0

# 通用配置...

环境特定配置

开发环境 (application-dev.yml)

• 端口: 8080
• 文件路径: D:/dev/images/
• 日志级别: DEBUG
• 缓存时间: 1小时

测试环境 (application-test.yml)

• 端口: 8081
• 文件路径: /app/test/images/
• 日志级别: INFO
• 缓存时间: 2小时

生产环境 (application-prod.yml)

• 端口: 80
• 文件路径: /data/images/
• 日志级别: WARN
• 缓存时间: 24小时

限制说明

• 图片尺寸范围: 1-4000px
• 批量生成最多支持 10 种尺寸
• 支持的输入图片格式: JPG, PNG, WebP, BMP, GIF
• 输出格式固定为: JPG
• 图片质量固定为: 0.8
• 单个文件最大 50MB
• 文件路径必须在配置的前缀目录下

项目结构

src/main/kotlin/com/yujin/thumbnail/
├── ThumbnailApplication.kt          # 主应用程序类
├── controller/
│   └── ThumbnailController.kt       # REST 控制器
├── service/
│   └── ThumbnailService.kt          # 缩略图生成服务
├── dto/
│   └── ThumbnailDto.kt              # 数据传输对象
└── config/
    └── GlobalExceptionHandler.kt    # 全局异常处理器

src/main/resources/
├── application.properties           # 配置文件
└── static/
    └── index.html                   # 测试页面

错误处理

所有 API 接口都包含统一的错误处理:

{
  "success": false,
  "message": "错误信息",
  "data": null,
  "timestamp": 1699123456789
}

常见错误类型:

• 参数验证错误
• 文件类型不支持
• 文件大小超限
• 图片尺寸超限
• 服务器内部错误

性能优化建议

1. 内存优化: 对于大量图片处理，建议增加 JVM 堆内存
2. 并发处理: Solon Boot 支持异步处理，可配置线程池
3. 缓存策略: 可添加 Redis 缓存常用尺寸的缩略图
4. 文件存储: 生产环境建议使用对象存储服务

扩展功能

可以考虑添加的功能:

• 图片裁剪
• 图片旋转
• 图片滤镜
• 批量压缩
• 异步处理队列
• 缩略图缓存

License

MIT License