# 缩略图生成器

基于 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. 运行项目

#### 开发环境
```bash
# 使用启动脚本（推荐）
start-dev.bat

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

#### 测试环境
```bash
# 使用启动脚本
start-test.bat

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

#### 生产环境
```bash
# 使用启动脚本
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` - 生产环境配置

详细配置说明请参考：[环境配置文档](ENVIRONMENT-CONFIG.md)

## API 接口

### 1. 生成单个缩略图

**接口**: `GET /api/thumbnail/generate`

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

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

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

**示例**:
```bash
# 生成 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):
```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`

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

### 4. 健康检查

**接口**: `GET /api/thumbnail/health`

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

## 配置说明

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

### 主配置文件: `application.yml`
```yaml
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 接口都包含统一的错误处理:

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

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

## 性能优化建议

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

## 扩展功能

可以考虑添加的功能:
- 图片裁剪
- 图片旋转
- 图片滤镜
- 批量压缩
- 异步处理队列
- 缩略图缓存

## License

MIT License