# 1.0.4 API接口文档

[返回主文档](../../README.md)

## 📋 概述
1.0.4版本在1.0.3基础上增加了图片多版本压缩功能，支持original、medium、thumbnail、small四种规格。
支持防盗链
增加支持视频上传
增加支持若依富文本图片以及[富文本本身](ruoyi-upgrade.md#rich-text)上传
增加支持若依[图片上传](ruoyi-upgrade.md)
增加支持若依[视频上传](ruoyi-upgrade-file-upload#quick-start)
增加支持doc,pdf等文件上传：todo test it
图片降级成ruoyi的方案；迁移方案,相互转换的方案
增加一个脚本一件化改造。
增加支持根据domain生成ddl，并根据domain生成基于mongodb的脚本
todo视频压缩（支持异步化）
https://chat.deepseek.com/a/chat/s/e4c19f81-0778-453d-aa4e-d12b0d47fdfb
sudo yum install ffmpeg ffmpeg-devel -y

## 🔌 基础信息
- **API版本**: v1.0.4
- **基础目录**: `com.leying.minio.service`

## quick-start 🚀
[setup](../v1.0.3/api.md#setup)
### dependencies
```xml
<dependency>
    <groupId>com.leying</groupId>
    <artifactId>minio-spring-boot-starter</artifactId>
    <version>1.0.4-SNAPSHOT</version>
</dependency>
```
[yml](../v1.0.3/api.md#yml)

## 📤 上传接口
### 1. 多版本文件上传通用(新增)
```java
package com.ruoyi.spring;

import com.leying.minio.service.MinIOService;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.mock.web.MockMultipartFile;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.TestPropertySource;
import org.springframework.web.multipart.MultipartFile;

import javax.imageio.ImageIO;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.Map;

import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.doNothing;
import static org.mockito.Mockito.verify;

@SpringBootTest
@ActiveProfiles("dev")
@TestPropertySource(properties = {
        "leying.minio.enabled=true",
        "leying.minio.endpoint=https://oss.dev1.ipykj.com",
        "leying.minio.access-key=dev1",
        "leying.minio.secret-key=dev1@100%",
        "leying.minio.bucket=dev1-bucket"
})
@Slf4j
public class MinIOService104Test {

    @Autowired
    private MinIOService ioService;

    @Value("${leying.minio.bucket}")
    private String bucketName;

    @Test
    void testUploadAndProcessImage_LargeImage() throws Exception {
        // 创建大尺寸测试图片（2000x1500）
        MultipartFile largeImage = createLargeTestImage("large-image.jpg", 2000, 1500);


        ImageResult imageResult = ioService.uploadAndProcessImage(largeImage);
        log.info("{}", JSON.toJSONString(imageResult));

        assertNotNull(imageResult);
        assertTrue(imageResult.getMetadata().getImageKeys().get("original").endsWith(".jpg"));
        assertTrue(imageResult.getMetadata().getImageKeys().get("medium").endsWith(".jpg"));
        assertTrue(imageResult.getMetadata().getImageKeys().get("small").endsWith(".jpg"));
        assertTrue(imageResult.getMetadata().getImageKeys().get("thumbnail").endsWith(".jpg"));

    }

}
```
#### 响应示例：
```json
{
    "metadata": {
        "id": "1764816945822_large-image",
        "imageKeys": {
            "small": "files/images/small/2025/12/04/1764816945822_large-image.jpg",
            "thumbnail": "files/images/thumbnail/2025/12/04/1764816945822_large-image.jpg",
            "original": "files/images/originals/2025/12/04/1764816945822_large-image.jpg",
            "medium": "files/images/medium/2025/12/04/1764816945822_large-image.jpg"
        },
        "originalFilename": "large-image.jpg",
        "timestamp": "1764816945822",
        "uploadTime": "Thu Dec 04 10:55:46 CST 2025"
    },
    "metadataKey": "files/metadata/1764816945822_large-image.json"
}
```
### 2.多版本文件上传文件路径
```java
 @Test
void testUploadAndProcessImage_FilePath_Success() throws Exception {

    String key = "files/lygateway";

    String filePath = "{yourpath}/doc/QRCode_258.png";

    ImageResult imageResult = ioService.uploadAndProcessImage(filePath, key);
    assertNotNull(imageResult);
    // 大图应该生成large尺寸
    // 这里需要根据你的实际实现调整断言
}
```
#### 响应示例：
```json
{
    "metadata": {
        "id": "1764816945822_large-image",
        "imageKeys": {
            "small": "files/images/small/2025/12/04/1764816945822_large-image.jpg",
            "thumbnail": "files/images/thumbnail/2025/12/04/1764816945822_large-image.jpg",
            "original": "files/images/originals/2025/12/04/1764816945822_large-image.jpg",
            "medium": "files/images/medium/2025/12/04/1764816945822_large-image.jpg"
        },
        "originalFilename": "large-image.jpg",
        "timestamp": "1764816945822",
        "uploadTime": "Thu Dec 04 10:55:46 CST 2025"
    },
    "metadataKey": "files/metadata/1764816945822_large-image.json"
}
```
### 3.视频上传文件路径方式
```java
 @Test
void testUploadVideo_FilePath_Success() throws Exception {

    String key = "files/lygateway";

    String filePath = "{yourpath}/938_1728966557.mp4";

    VideoResult videoResult = ioService.uploadVideo(filePath, key);
    log.info("{}", JSON.toJSONString(videoResult));
    assertNotNull(videoResult);
    // 大图应该生成large尺寸
    // 这里需要根据你的实际实现调整断言
}
```
### 4.视频｜图片 上传文件方式2
#### case1-文件
```java
@Test
void testUploadFile_FilePath_Success() throws Exception {

    String key = "files/guoshu";

    String filePath = "{yourpath}/938_1728966557.mp4";

    FileResult fileResult = this.ioService.uploadFile(filePath, key);
    log.info("{}", JSON.toJSONString(fileResult));
    assertNotNull(fileResult);
    // 大图应该生成large尺寸
    // 这里需要根据你的实际实现调整断言
}
```
#### 响应示例：
```json
{
  "img": false,
  "video": true,
  "videoResult": {
    "metadata": {
      "contentType": "video/mp4",
      "fileSize": 2402461,
      "id": "1764905856065_938_1728966557",
      "objectKey": "files/guoshu/videos/2025/12/05/1764905856065_938_1728966557.mp4",
      "originalFilename": "938_1728966557.mp4",
      "uploadTime": "Fri Dec 05 11:37:37 CST 2025",
      "videoInfo": {
        "note": "详细视频信息需要集成FFmpeg等视频处理库",
        "filename": "938_1728966557.mp4",
        "fileSize": 2402461,
        "format": "mp4",
        "extractTime": "Fri Dec 05 11:37:37 CST 2025"
      }
    },
    "metadataKey": "files/guoshu/video-metadata/1764905856065_938_1728966557.json"
  }
}
```
#### case2-图片
```java
 @Test
void testUploadFile_FilePath_Success() throws Exception {

    String key = "files/lygateway";

    String filePath = "/{yourpath}/doc/QRCode_258.png";

    FileResult fileResult = this.ioService.uploadFile(filePath, key);
    log.info("{}", JSON.toJSONString(fileResult));
    assertNotNull(fileResult);
    // 大图应该生成large尺寸
    // 这里需要根据你的实际实现调整断言
}
```
#### 响应示例：
```json
{
  "imageResult": {
    "metadata": {
      "id": "1764906041754_QRCode_258",
      "imageKeys": {
        "original": "files/lygateway/images/originals/2025/12/05/1764906041754_QRCode_258.png"
      },
      "originalFilename": "QRCode_258.png",
      "timestamp": "1764906041754",
      "uploadTime": "Fri Dec 05 11:40:42 CST 2025"
    },
    "metadataKey": "files/lygateway/metadata/1764906041754_QRCode_258.json"
  },
  "img": true,
  "video": false
}
```
## 📥 下载接口
### 1. 获取不带签名的url
```java
@Test
void testGetPublicImgUrl_case1() throws Exception {
    // 测试不支持的格式（如.ico）
    String imageUrl = ioService.getPublicImgUrl("files/images/small/2025/12/04/1764816945822_large-image.jpg");
    log.info(imageUrl);
    assertNotNull(imageUrl);
}
```
#### 响应示例：
```
https://oss.dev1.ipykj.com/dev1-bucket/files/images/small/2025/12/04/1764816945822_large-image.jpg
```
### 2. 获取签名的url(暂无使用场景,由于bucket公开)
```java
@Test
void testGetImageUrl_case1() throws Exception {
    var seconds = 60;
    // 测试不支持的格式（如.ico）
    String imageUrl = ioService.getImageUrl("files/images/small/2025/12/04/1764816945822_large-image.jpg", seconds);
    log.info(imageUrl);
    assertNotNull(imageUrl);
}
```
#### 响应示例：
```
https://oss.dev1.ipykj.com/dev1-bucket/files/images/small/2025/12/04/1764816945822_large-image.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=dev1%2F20251204%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20251204T065735Z&X-Amz-Expires=60&X-Amz-SignedHeaders=host&X-Amz-Signature=060d21ecbab318f071c79657cb5afd36d3ef3f006cfc7cdab5558cc5e9b9d97b
```
### 3. 获取视频不带签名的url
```java
 @Test
void testGetPublicVideoUrl_case1() throws Exception {
    // 测试不支持的格式（如.ico）
    String imageUrl = ioService.getVideoImgUrl("files/lygateway/videos/2025/12/04/1764833863227_938_1728966557.mp4");
    log.info(imageUrl);
    assertNotNull(imageUrl);
}
```
#### 响应示例：
```
https://oss.dev1.ipykj.com/dev1-bucket/files/lygateway/videos/2025/12/04/1764833863227_938_1728966557.mp4
```

## 📤 根据domain生成ddl & 生成mongodb
```bash
#根据domain生成ddl
curl -sSL https://oss.dev1.ipykj.com/dev1-bucket/mvn/domain2DDL-win.sh | bash
#生成mongodb
curl -sSL https://oss.dev1.ipykj.com/dev1-bucket/mvn/DomainMongoCodeGenerator-win.sh | bash -s -- "D:
uiqiu-java" RqTestUpload \                                                                             romwin7\home_syf\project_files
        --output-dir ./output/controller \
        --path-prefix system/rqTestUpload \
        --perm-prefix system:rqTestUpload 
```


## 🛠️ 故障排除
[集成问题指南](../v1.0.3/migration.md)

## 🔗 相关文档
[返回主文档](../../README.md)
[图片压缩详细说明](image-compression.md)
[视频压缩详细说明](video-compression.md)
[若依框架升级指南](ruoyi-upgrade.md)
[维护文件传送门](https://chat.deepseek.com/a/chat/s/cef9a241-efa8-4979-894f-80043a828315)
版本对比
[图片处理与异常验证代码优化](https://chat.deepseek.com/a/chat/s/f0008014-d4d0-4404-b5f4-86ed68601b84)
[防盗链](https://chat.deepseek.com/a/chat/s/52b36d96-01e3-404c-bd50-06805bf75f74)

*API版本: 1.0.4-SNAPSHOT | 最后更新: 2025-12-17*