缩略图

xiaoyelj 0dd9921eaa 更新缩略图生成逻辑，添加缩放参数支持；修改生成路径以包含缩放信息		5 月之前
script	2b25caee5c 更新缩略图生成逻辑，支持不同类型的缩略图生成；修改配置文件以添加 MinIO 基础 URL	5 月之前
src	0dd9921eaa 更新缩略图生成逻辑，添加缩放参数支持；修改生成路径以包含缩放信息	5 月之前
.gitignore	2b25caee5c 更新缩略图生成逻辑，支持不同类型的缩略图生成；修改配置文件以添加 MinIO 基础 URL	5 月之前
API-USAGE.md	2b25caee5c 更新缩略图生成逻辑，支持不同类型的缩略图生成；修改配置文件以添加 MinIO 基础 URL	5 月之前
ENVIRONMENT-CONFIG.md	2f3326452d 图片缩略图	5 月之前
README.md	2f3326452d 图片缩略图	5 月之前
pom.xml	2b25caee5c 更新缩略图生成逻辑，支持不同类型的缩略图生成；修改配置文件以添加 MinIO 基础 URL	5 月之前

缩略图生成器

基于 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
}

常见错误类型:

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

性能优化建议

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

扩展功能

可以考虑添加的功能:

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

License

MIT License

README.md