add AttachmentVariant

This commit is contained in:
Timi
2026-08-21 23:43:40 +08:00
parent 3a3809b661
commit 2e9225852d
15 changed files with 827 additions and 258 deletions
@@ -25,18 +25,6 @@ public interface AttachmentService extends BaseService<Attachment, String> {
/// @return 克隆后的附件
Attachment clone(String id);
/**
* 按需获取或创建缩略图附件。
* <p>当附件为图片或视频时,若指定尺寸的缩略图已存在则直接返回缓存,
* 否则生成并持久化后返回。不支持缩略图的附件类型返回 {@code null}。</p>
*
* @param source 源附件(必须已持久化,mimeType 已填充)
* @param requestWidth 请求宽度,{@code null} 表示未指定
* @param requestHeight 请求高度,{@code null} 表示未指定
* @return 缩略图附件,不支持时返回 {@code null}
*/
Attachment fetchThumb(Attachment source, Integer requestWidth, Integer requestHeight);
Attachment getByBizId(Attachment.BizType bizType, String bizId);
Attachment getByAttachType(Attachment.BizType bizType, String bizId, String attachType);
@@ -0,0 +1,28 @@
package com.imyeyu.api.modules.common.service;
import com.imyeyu.api.modules.common.bean.attachment.ThumbnailFitMode;
import com.imyeyu.api.modules.common.entity.Attachment;
/// 附件缩略图变体服务
///
/// @author 夜雨
/// @since 2026-08-21
public interface AttachmentVariantService {
/// 按需获取或创建缩略图附件
///
/// @param source 源附件
/// @param requestWidth 请求宽度
/// @param requestHeight 请求高度
/// @param fitMode 缩放模式
/// @return 缩略图附件
Attachment fetchThumb(Attachment source, Integer requestWidth, Integer requestHeight, ThumbnailFitMode fitMode);
/// 删除源附件对应的全部缩略图变体
///
/// @param sourceAttachmentId 源附件 ID
void deleteBySourceId(String sourceAttachmentId);
/// 清理已过期的缩略图变体
void clearExpired();
}
@@ -3,19 +3,14 @@ package com.imyeyu.api.modules.common.service.implement;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.imyeyu.api.config.dbsource.TimiServerDBConfig;
import com.imyeyu.api.modules.common.bean.attachment.MediaAttach;
import com.imyeyu.api.modules.common.bean.attachment.Metadata;
import com.imyeyu.api.modules.common.entity.Attachment;
import com.imyeyu.api.modules.common.mapper.AttachmentMapper;
import com.imyeyu.api.modules.common.service.AttachmentService;
import com.imyeyu.api.util.JavaCV;
import com.imyeyu.api.modules.common.service.AttachmentVariantService;
import com.imyeyu.io.IO;
import com.imyeyu.java.TimiJava;
import com.imyeyu.java.bean.CallbackArg;
import com.imyeyu.java.bean.timi.TimiCode;
import com.imyeyu.java.bean.timi.TimiException;
import com.imyeyu.java.ref.Ref;
import com.imyeyu.network.Network;
import com.imyeyu.spring.TimiSpring;
import com.imyeyu.spring.bean.Page;
import com.imyeyu.spring.bean.PageResult;
@@ -26,7 +21,6 @@ import com.mongodb.client.gridfs.GridFSBucket;
import com.mongodb.client.gridfs.model.GridFSFile;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import net.coobird.thumbnailator.Thumbnails;
import org.apache.tika.Tika;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.data.mongodb.core.query.Query;
@@ -36,9 +30,6 @@ import org.springframework.transaction.annotation.Transactional;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
@@ -47,7 +38,6 @@ import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.UUID;
import java.util.stream.Collectors;
/**
@@ -64,6 +54,7 @@ public class AttachmentServiceImplement extends AbstractEntityService<Attachment
private final ObjectMapper jackson;
private final GridFSBucket gridFSBucket;
private final GridFsTemplate gridFsTemplate;
private final AttachmentVariantService variantService;
@Override
protected BaseMapper<Attachment, String> mapper() {
@@ -124,6 +115,7 @@ public class AttachmentServiceImplement extends AbstractEntityService<Attachment
}
// 有新文件时,先查旧记录获取旧 mongoId 和兜底字段
Attachment old = mapper.selectRaw(attachment.getId());
TimiException.required(old, "not found attachment");
// 存储新文件
newMongoId = gridFsTemplate.store(stream, attachment.buildMongoName()).toString();
GridFSFile gridFSFile = gridFsTemplate.findOne(new Query(Criteria.where("_id").is(newMongoId)));
@@ -141,6 +133,8 @@ public class AttachmentServiceImplement extends AbstractEntityService<Attachment
// 更新数据库后删除旧 GridFS 文件
super.update(attachment);
// 源文件版本已变化,旧缩略图全部失效
variantService.deleteBySourceId(attachment.getId());
gridFsTemplate.delete(Query.query(Criteria.where("_id").is(old.getMongoId())));
} catch (Exception e) {
// 新文件已上传但后续操作失败,清理新文件防止孤儿数据
@@ -155,36 +149,18 @@ public class AttachmentServiceImplement extends AbstractEntityService<Attachment
@Transactional(TimiServerDBConfig.ROLLBACKER)
@Override
public void delete(String id) {
mapper.selectThumbsBySourceId(id).forEach(thumb -> super.delete(thumb.getId()));
variantService.deleteBySourceId(id);
super.delete(id);
}
@Transactional(TimiServerDBConfig.ROLLBACKER)
@Override
public void destroy(String id) {
CallbackArg<Attachment> doDestroy = attach -> {
try {
if (attach.getMongoId() != null) {
gridFsTemplate.delete(Query.query(Criteria.where("_id").is(attach.getMongoId())));
}
if (!attach.isDeleted()) {
attach.setDeletedAt(Time.now());
}
attach.setIsDestroyed(true);
attach.setDestroyAt(Time.now());
mapper.update(attach);
if (Ref.toType(MediaAttach.Type.class, attach.getAttachType()) == MediaAttach.Type.THUMB) {
// 缩略图记录物理删除
mapper.destroy(attach.getId());
}
} catch (Exception e) {
log.error("delete mongo file error, id={}", attach.getId(), e);
throw new TimiException(TimiCode.ERROR, "TODO delete mongo file error");
}
};
mapper.selectThumbsBySourceId(id).forEach(doDestroy::handler);
doDestroy.handler(mapper.selectRaw(id));
variantService.deleteBySourceId(id);
Attachment attachment = mapper.selectRaw(id);
if (attachment != null) {
destroyAttachment(attachment);
}
}
@Transactional(TimiServerDBConfig.ROLLBACKER)
@@ -216,74 +192,20 @@ public class AttachmentServiceImplement extends AbstractEntityService<Attachment
}
}
@Transactional(TimiServerDBConfig.ROLLBACKER)
@Override
public Attachment fetchThumb(Attachment source, Integer requestWidth, Integer requestHeight) {
TimiException.requiredTrue(requestWidth != null || requestHeight != null, "required width or height");
String mimeType = source.getMimeType();
boolean isImage = mimeType != null && Set.of("image/png", "image/bmp", "image/jpeg").contains(mimeType);
boolean isVideo = mimeType != null && Set.of("video/mp4", "video/quicktime").contains(mimeType);
if (!isImage && !isVideo) {
return null;
}
Attachment cached = mapper.selectThumb(source.getBizType(), source.getId(), requestWidth, requestHeight);
if (cached != null) {
// 命中缓存直接返回
return cached;
}
private void destroyAttachment(Attachment attachment) {
try {
ByteArrayOutputStream thumbStream = new ByteArrayOutputStream();
CallbackArg<InputStream> applyThumbSize = inputStream -> {
try {
Thumbnails.Builder<? extends InputStream> builder = Thumbnails.of(inputStream);
if (requestWidth != null && requestHeight != null) {
builder.size(requestWidth, requestHeight).keepAspectRatio(false).toOutputStream(thumbStream);
} else if (requestWidth != null) {
builder.width(requestWidth).keepAspectRatio(true).toOutputStream(thumbStream);
} else {
builder.height(requestHeight).keepAspectRatio(true).toOutputStream(thumbStream);
}
} catch (IOException e) {
log.error("applyThumbSize error for fetchThumb", e);
throw new RuntimeException(e);
}
};
if (isImage) {
applyThumbSize.handler(source.openInputStream());
} else {
String name = source.getName();
File tempFile = IO.file("temp/%s_%s".formatted(UUID.randomUUID(), name));
try {
IO.toFile(tempFile, source.openInputStream());
ByteArrayOutputStream baos = JavaCV.captureThumbnail(IO.getInputStream(tempFile), 2);
applyThumbSize.handler(IO.toInputStream(baos));
} finally {
IO.destroy(tempFile);
}
if (attachment.getMongoId() != null) {
gridFsTemplate.delete(Query.query(Criteria.where("_id").is(attachment.getMongoId())));
}
Metadata.ThumbImage thumbMeta = new Metadata.ThumbImage();
thumbMeta.setSourceId(source.getId());
thumbMeta.setSourceMongoId(source.getMongoId());
thumbMeta.setSourceMimeType(mimeType);
thumbMeta.setRequestWidth(requestWidth);
thumbMeta.setRequestHeight(requestHeight);
Attachment thumb = new Attachment();
thumb.setName(Network.simpleURIFileName(source.getName()) + ".png");
thumb.setBizType(source.getBizType());
thumb.setBizId(source.getId());
thumb.setAttachType(MediaAttach.Type.THUMB.toString());
thumb.setMetadata(jackson.valueToTree(thumbMeta));
thumb.setInputStream(new ByteArrayInputStream(thumbStream.toByteArray()));
// 缩略图 7 天后过期,额外 1 天宽限供后台任务销毁
long expireAt = Time.now() + 7 * Time.D;
thumb.setDeletedAt(expireAt);
thumb.setDestroyAt(expireAt + Time.D);
create(thumb);
return thumb;
if (!attachment.isDeleted()) {
attachment.setDeletedAt(Time.now());
}
attachment.setIsDestroyed(true);
attachment.setDestroyAt(Time.now());
mapper.update(attachment);
} catch (Exception e) {
log.error("create thumbnail error", e);
throw new TimiException(TimiCode.ERROR, "exception.attachment.create.error");
log.error("delete mongo file error, id={}", attachment.getId(), e);
throw new TimiException(TimiCode.ERROR, "TODO delete mongo file error", e);
}
}
@@ -390,6 +312,8 @@ public class AttachmentServiceImplement extends AbstractEntityService<Attachment
// 将临时文件的 GridFS 存储转移至当前永久记录,废弃临时记录
Attachment current = mapper.selectRaw(item.getId());
Attachment tempFile = mapper.selectRaw(tempFileId);
// 源文件版本已变化,旧缩略图全部失效
variantService.deleteBySourceId(current.getId());
// 删除旧 GridFS 文件
gridFsTemplate.delete(Query.query(Criteria.where("_id").is(current.getMongoId())));
// 将存储信息从临时记录迁移到永久记录
@@ -0,0 +1,339 @@
package com.imyeyu.api.modules.common.service.implement;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.imyeyu.api.config.dbsource.TimiServerDBConfig;
import com.imyeyu.api.modules.common.bean.attachment.MediaAttach;
import com.imyeyu.api.modules.common.bean.attachment.ThumbnailFitMode;
import com.imyeyu.api.modules.common.entity.Attachment;
import com.imyeyu.api.modules.common.entity.AttachmentVariant;
import com.imyeyu.api.modules.common.mapper.AttachmentVariantMapper;
import com.imyeyu.api.modules.common.service.AttachmentVariantService;
import com.imyeyu.api.util.JavaCV;
import com.imyeyu.io.IO;
import com.imyeyu.java.TimiJava;
import com.imyeyu.java.bean.timi.TimiCode;
import com.imyeyu.java.bean.timi.TimiException;
import com.imyeyu.network.Network;
import com.imyeyu.spring.util.Redis;
import com.imyeyu.utils.Time;
import com.mongodb.client.gridfs.GridFSBucket;
import com.mongodb.client.gridfs.model.GridFSFile;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import net.coobird.thumbnailator.Thumbnails;
import net.coobird.thumbnailator.geometry.Positions;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.data.mongodb.core.query.Query;
import org.springframework.data.mongodb.gridfs.GridFsTemplate;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.util.Set;
import java.util.UUID;
/// 附件缩略图变体服务实现
///
/// 负责缩略图生成、变体缓存、并发控制和变体文件清理,源附件生命周期由 `AttachmentService` 负责
///
/// @author 夜雨
/// @since 2026-08-21
@Slf4j
@Service
@RequiredArgsConstructor
public class AttachmentVariantServiceImplement implements AttachmentVariantService {
private static final int THUMB_MAX_WIDTH = 4096;
private static final int THUMB_MAX_HEIGHT = 4096;
private static final long THUMB_MAX_PIXELS = 16_000_000L;
private static final long THUMB_CACHE_TTL = Time.D * 7;
private static final long THUMB_LOCK_TTL = Time.M * 10;
private static final double THUMB_TARGET_SECONDS = 2;
private static final String THUMB_OUTPUT_FORMAT = "png";
private static final String THUMB_ALGORITHM_VERSION = "v3";
private static final String THUMB_LOCK_KEY_PREFIX = "ATTACHMENT:THUMB:LOCK:";
private final AttachmentVariantMapper variantMapper;
private final ObjectMapper jackson;
private final GridFSBucket gridFSBucket;
private final GridFsTemplate gridFsTemplate;
@Qualifier("redisLocker")
private final Redis<String, Integer> redisLocker;
@Override
public Attachment fetchThumb(Attachment source, Integer requestWidth, Integer requestHeight, ThumbnailFitMode fitMode) {
TimiException.required(source, "not found source attachment");
TimiException.required(source.getId(), "not found source attachment.id");
TimiException.required(source.getMongoId(), "not found source attachment.mongoId");
TimiException.requiredTrue(requestWidth != null || requestHeight != null, "required width or height");
if (requestWidth != null && !(0 < requestWidth && requestWidth < THUMB_MAX_WIDTH + 1)) {
throw new TimiException(TimiCode.ARG_BAD, "attachment.thumbnail.width.invalid");
}
if (requestHeight != null && !(0 < requestHeight && requestHeight < THUMB_MAX_HEIGHT + 1)) {
throw new TimiException(TimiCode.ARG_BAD, "attachment.thumbnail.height.invalid");
}
if (requestWidth != null && requestHeight != null) {
long pixels = (long) requestWidth * requestHeight;
if (THUMB_MAX_PIXELS < pixels) {
throw new TimiException(TimiCode.ARG_BAD, "attachment.thumbnail.area.invalid");
}
}
fitMode = TimiJava.defaultIfNull(fitMode, ThumbnailFitMode.FIT);
String mimeType = source.getMimeType();
boolean isImage = mimeType != null && Set.of("image/png", "image/bmp", "image/jpeg").contains(mimeType);
boolean isVideo = mimeType != null && Set.of("video/mp4", "video/quicktime").contains(mimeType);
if (!isImage && !isVideo) {
throw new TimiException(TimiCode.ARG_BAD, "attachment.thumbnail.not.support");
}
int width = TimiJava.defaultIfNull(requestWidth, 0);
int height = TimiJava.defaultIfNull(requestHeight, 0);
long now = Time.now();
Attachment cached = variantMapper.selectValidAttachment(
source.getId(),
source.getMongoId(),
width,
height,
fitMode.toString(),
THUMB_OUTPUT_FORMAT,
THUMB_ALGORITHM_VERSION,
now
);
if (cached != null) {
return cached;
}
String lockKey = buildThumbLockKey(source, width, height, fitMode);
if (!redisLocker.lock(lockKey, 1, THUMB_LOCK_TTL)) {
throw new TimiException(TimiCode.ERROR_SERVICE_BUSY, "attachment.thumbnail.generating");
}
try {
cached = variantMapper.selectValidAttachment(
source.getId(),
source.getMongoId(),
width,
height,
fitMode.toString(),
THUMB_OUTPUT_FORMAT,
THUMB_ALGORITHM_VERSION,
Time.now()
);
if (cached != null) {
return cached;
}
AttachmentVariant oldVariant = variantMapper.selectByKey(
source.getId(),
source.getMongoId(),
width,
height,
fitMode.toString(),
THUMB_OUTPUT_FORMAT,
THUMB_ALGORITHM_VERSION
);
if (oldVariant != null) {
deleteVariant(oldVariant);
}
File thumbFile = null;
AttachmentVariant variant = null;
boolean variantInserted = false;
try {
thumbFile = createThumbFile(source, requestWidth, requestHeight, fitMode, isImage);
variant = new AttachmentVariant();
variant.setId(UUID.randomUUID().toString());
variant.setName(Network.simpleURIFileName(source.getName()) + "." + THUMB_OUTPUT_FORMAT);
variant.setMimeType("image/" + THUMB_OUTPUT_FORMAT);
long expireAt = Time.now() + THUMB_CACHE_TTL;
variant.setSourceAttachmentId(source.getId());
variant.setSourceMongoId(source.getMongoId());
variant.setSourceMd5(source.getMd5());
variant.setRequestWidth(width);
variant.setRequestHeight(height);
variant.setFitMode(fitMode);
variant.setOutputFormat(THUMB_OUTPUT_FORMAT);
variant.setAlgorithmVersion(THUMB_ALGORITHM_VERSION);
variant.setCreatedAt(Time.now());
variant.setExpireAt(expireAt);
BufferedImage image = ImageIO.read(thumbFile);
if (image != null) {
ObjectNode metadata = jackson.createObjectNode();
metadata.put("width", image.getWidth());
metadata.put("height", image.getHeight());
variant.setMetadata(metadata);
}
try (InputStream inputStream = Files.newInputStream(thumbFile.toPath())) {
String mongoId = gridFsTemplate.store(inputStream, variant.getName()).toString();
GridFSFile gridFSFile = gridFsTemplate.findOne(new Query(Criteria.where("_id").is(mongoId)));
variant.setMongoId(mongoId);
variant.setSize(gridFSFile.getLength());
try (InputStream md5InputStream = gridFSBucket.openDownloadStream(gridFSFile.getObjectId())) {
variant.setMd5(IO.md5(md5InputStream));
}
}
try {
variantMapper.insert(variant);
variantInserted = true;
} catch (DuplicateKeyException e) {
destroyVariantFile(variant);
Attachment concurrent = variantMapper.selectValidAttachment(
source.getId(),
source.getMongoId(),
width,
height,
fitMode.toString(),
THUMB_OUTPUT_FORMAT,
THUMB_ALGORITHM_VERSION,
Time.now()
);
if (concurrent != null) {
return concurrent;
}
throw e;
}
return toThumbAttachment(source, variant);
} catch (Exception e) {
if (variant != null) {
destroyVariantFile(variant);
if (variantInserted) {
variantMapper.delete(variant.getId());
}
}
throw e;
} finally {
IO.destroy(thumbFile);
}
} catch (TimiException e) {
throw e;
} catch (Exception e) {
log.error("create thumbnail error", e);
throw new TimiException(TimiCode.ERROR, "exception.attachment.create.error", e);
} finally {
redisLocker.releaseLock(lockKey);
}
}
private String buildThumbLockKey(Attachment source, int width, int height, ThumbnailFitMode fitMode) {
return "%s%s:%s:%s:%s:%s".formatted(
THUMB_LOCK_KEY_PREFIX,
source.getId(),
source.getMongoId(),
width,
height,
fitMode
);
}
private File createThumbFile(
Attachment source,
Integer requestWidth,
Integer requestHeight,
ThumbnailFitMode fitMode,
boolean isImage
) throws Exception {
File thumbFile = Files.createTempFile("timi-thumb-", ".png").toFile();
try {
if (isImage) {
try (InputStream inputStream = source.openInputStream()) {
resize(inputStream, thumbFile, requestWidth, requestHeight, fitMode);
}
return thumbFile;
}
try (InputStream inputStream = source.openInputStream()) {
ByteArrayOutputStream frame = JavaCV.captureThumbnail(inputStream, THUMB_TARGET_SECONDS);
if (!(0 < frame.size())) {
throw new TimiException(TimiCode.ERROR_NOT_SUPPORT, "attachment.thumbnail.video.frame.empty");
}
try (InputStream frameInputStream = new ByteArrayInputStream(frame.toByteArray())) {
resize(frameInputStream, thumbFile, requestWidth, requestHeight, fitMode);
}
return thumbFile;
}
} catch (Exception e) {
IO.destroy(thumbFile);
throw e;
}
}
private void resize(
InputStream inputStream,
File outputFile,
Integer requestWidth,
Integer requestHeight,
ThumbnailFitMode fitMode
) throws IOException {
Thumbnails.Builder<? extends InputStream> builder = Thumbnails.of(inputStream)
.useExifOrientation(true)
.outputFormat(THUMB_OUTPUT_FORMAT);
if (requestWidth != null && requestHeight != null) {
switch (fitMode) {
case FIT -> builder.size(requestWidth, requestHeight).keepAspectRatio(true);
case COVER -> builder.size(requestWidth, requestHeight).keepAspectRatio(true).crop(Positions.CENTER);
case STRETCH -> builder.size(requestWidth, requestHeight).keepAspectRatio(false);
}
} else if (requestWidth != null) {
builder.width(requestWidth).keepAspectRatio(true);
} else {
builder.height(requestHeight).keepAspectRatio(true);
}
builder.toFile(outputFile);
}
@Transactional(TimiServerDBConfig.ROLLBACKER)
@Override
public void deleteBySourceId(String sourceAttachmentId) {
for (AttachmentVariant variant : variantMapper.selectBySourceAttachmentId(sourceAttachmentId)) {
deleteVariant(variant);
}
}
private void deleteVariant(AttachmentVariant variant) {
destroyVariantFile(variant);
variantMapper.delete(variant.getId());
}
private void destroyVariantFile(AttachmentVariant variant) {
if (variant.getMongoId() != null) {
gridFsTemplate.delete(Query.query(Criteria.where("_id").is(variant.getMongoId())));
}
}
private Attachment toThumbAttachment(Attachment source, AttachmentVariant variant) {
Attachment thumb = new Attachment();
thumb.setId(variant.getId());
thumb.setBizType(source.getBizType());
thumb.setBizId(source.getId());
thumb.setAttachType(MediaAttach.Type.THUMB.toString());
thumb.setMongoId(variant.getMongoId());
thumb.setName(variant.getName());
thumb.setMimeType(variant.getMimeType());
thumb.setMetadata(variant.getMetadata());
thumb.setSize(variant.getSize());
thumb.setMd5(variant.getMd5());
thumb.setIsDestroyed(false);
thumb.setDestroyAt(variant.getExpireAt());
return thumb;
}
@Override
public void clearExpired() {
for (AttachmentVariant variant : variantMapper.selectExpired(Time.now())) {
try {
deleteVariant(variant);
} catch (Exception e) {
log.error("clear expired thumbnail variant error, id={}", variant.getId(), e);
}
}
}
}