177 lines
5.2 KiB
Markdown
177 lines
5.2 KiB
Markdown
# 评论图片WebP转JPG功能说明
|
||
|
||
## 功能概述
|
||
|
||
评论模块中的图片如果是webp格式，会自动转换为jpg格式。转换后的图片会被缓存，下次不需要再次转换。
|
||
|
||
## 功能特性
|
||
|
||
1. **自动检测**：自动检测图片URL中的webp格式
|
||
2. **格式转换**：将webp格式图片转换为jpg格式
|
||
3. **结果缓存**：转换结果存储在数据库中，避免重复转换
|
||
4. **文件存储**：转换后的jpg图片保存到本地目录
|
||
5. **HTTP访问**：通过ImageController提供HTTP访问接口
|
||
|
||
## 配置说明
|
||
|
||
在 `application.yml` 中配置：
|
||
|
||
```yaml
|
||
image:
|
||
convert:
|
||
# 图片存储路径（转换后的jpg图片存储目录）
|
||
storage-path: ${user.home}/comment-images
|
||
# 图片访问基础URL（如果配置，转换后的图片将通过此URL访问）
|
||
# 例如: http://your-domain.com/images 或 http://localhost:6666/images
|
||
# 如果为空，则返回本地文件路径
|
||
base-url: http://localhost:6666/images
|
||
```
|
||
|
||
### 配置项说明
|
||
|
||
- **storage-path**：转换后的jpg图片存储目录，默认使用 `${user.home}/comment-images`
|
||
- **base-url**：图片访问的基础URL，如果配置，转换后的图片URL将使用此地址；如果不配置，则返回本地文件路径
|
||
|
||
## 数据库表
|
||
|
||
需要执行以下SQL创建图片转换记录表：
|
||
|
||
```sql
|
||
-- 执行 sql/image_conversions.sql
|
||
```
|
||
|
||
表结构：
|
||
- `id`：主键ID
|
||
- `original_url`：原始webp图片URL（唯一索引）
|
||
- `converted_url`：转换后的jpg图片URL或路径
|
||
- `converted_at`：转换时间
|
||
- `file_size`：文件大小（字节）
|
||
- `created_at`：创建时间
|
||
|
||
## 工作流程
|
||
|
||
1. **图片URL解析**：从评论数据中解析出图片URL列表
|
||
2. **格式检测**：检查URL中是否包含webp格式标识
|
||
3. **缓存查询**：查询数据库，检查是否已转换过
|
||
4. **格式转换**（如果未转换过）：
|
||
- 下载原始webp图片
|
||
- 使用webp-imageio库读取webp格式
|
||
- 转换为BufferedImage
|
||
- 保存为jpg格式到本地目录
|
||
- 保存转换记录到数据库
|
||
5. **返回结果**：返回转换后的图片URL（或原URL，如果不是webp）
|
||
|
||
## 依赖库
|
||
|
||
项目已添加以下依赖：
|
||
|
||
1. **Thumbnailator** (0.4.20)：图片处理库
|
||
|
||
**注意**：WebP格式支持需要系统或JVM本身支持webp格式。如果系统不支持webp，转换功能会跳过webp图片并返回原URL，不会影响系统正常运行。
|
||
|
||
如需支持webp格式转换，可以：
|
||
- 使用支持webp的JVM版本
|
||
- 手动添加webp-imageio库到项目中
|
||
- 使用其他webp解码库
|
||
|
||
## API接口
|
||
|
||
### 图片访问接口
|
||
|
||
**GET** `/images/{filename}`
|
||
|
||
访问转换后的jpg图片文件。
|
||
|
||
**参数：**
|
||
- `filename`：文件名（通常是MD5值.jpg）
|
||
|
||
**返回：**
|
||
- 成功：图片文件（Content-Type: image/jpeg）
|
||
- 失败：404 Not Found 或 400 Bad Request
|
||
|
||
**安全特性：**
|
||
- 防止路径遍历攻击
|
||
- 文件路径验证
|
||
- 仅允许访问存储目录内的文件
|
||
|
||
## 使用示例
|
||
|
||
### 前端调用
|
||
|
||
评论生成接口返回的图片URL列表已经过转换处理：
|
||
|
||
```json
|
||
{
|
||
"list": [
|
||
{
|
||
"commentText": "评论内容",
|
||
"images": [
|
||
"http://localhost:6666/images/abc123.jpg",
|
||
"http://localhost:6666/images/def456.jpg"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 后端调用
|
||
|
||
图片转换服务会自动集成到评论生成流程中：
|
||
|
||
```java
|
||
// 在 JDInnerController.commentGenerate 方法中
|
||
List<String> imageUrls = parsePictureUrls(commentToUse.getPictureUrls());
|
||
List<String> convertedImageUrls = imageConvertService.convertImageUrls(imageUrls);
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **首次转换**：首次转换webp图片时，需要下载图片并转换，可能耗时较长
|
||
2. **存储空间**：转换后的jpg图片会占用磁盘空间，建议定期清理旧文件
|
||
3. **网络依赖**：转换过程需要下载原始图片，确保网络连接正常
|
||
4. **WebP支持**：确保webp-imageio库正确加载，否则转换会失败
|
||
5. **并发处理**：多个请求同时转换同一张图片时，可能会导致重复转换（建议后续优化为加锁机制）
|
||
|
||
## 故障排查
|
||
|
||
### 问题1：转换失败，提示"无法读取webp图片格式"
|
||
|
||
**解决方案：**
|
||
1. 确认 `webp-imageio` 依赖已正确添加到pom.xml
|
||
2. 确认依赖已成功下载（检查Maven本地仓库）
|
||
3. 检查日志中的WebP支持检测信息
|
||
|
||
### 问题2：图片无法访问（404）
|
||
|
||
**解决方案：**
|
||
1. 检查 `storage-path` 配置是否正确
|
||
2. 确认图片文件已成功转换并保存
|
||
3. 检查文件权限
|
||
4. 如果配置了 `base-url`，确认URL是否正确
|
||
|
||
### 问题3：转换后的图片URL是本地路径
|
||
|
||
**解决方案：**
|
||
在 `application.yml` 中配置 `base-url`：
|
||
|
||
```yaml
|
||
image:
|
||
convert:
|
||
base-url: http://your-domain:6666/images
|
||
```
|
||
|
||
## 性能优化建议
|
||
|
||
1. **异步转换**：对于大量图片，可以考虑异步转换
|
||
2. **CDN加速**：将转换后的图片上传到CDN，提供更快的访问速度
|
||
3. **定期清理**：定期清理长时间未使用的转换图片
|
||
4. **缓存预热**：提前转换常用的图片
|
||
|
||
## 后续优化
|
||
|
||
1. 添加转换任务队列，支持批量转换
|
||
2. 添加转换状态监控和统计
|
||
3. 支持其他图片格式转换（如png、gif等）
|
||
4. 添加图片压缩功能，减小文件大小
|
||
|