keyfil/文档/基础组件/oss/20250530-engine-starter-oss-2.0.0.md

<!-- Space: qifu -->
<!-- Parent: 后端技术&知识&规范 -->
<!-- Parent: 技术方案 -->
<!-- Parent: 基建 -->
<!-- Parent: 00-基础组件 -->
<!-- Parent: 00-EngineStarterOss使用指南 -->
<!-- Title: 20250509-engine-starter-oss-2.0.0 -->

<!-- Macro: :anchor\((.*)\):
     Template: ac:anchor
     Anchor: ${1} -->
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
     Template: ac:image
     Url: ${1}
     Width: ${2} -->
<!-- Macro: \<\!\-\- :toc: \-\-\>
     Template: ac:toc
     Printable: 'false'
     MinLevel: 2 
     MaxLevel: 4 -->
<!-- Include: 杂项/声明文件.md -->

<!-- :toc: -->

# engine-starter-oss 使用教程

> 这是一个基于 `aws-s3-client` 封装的 oss 存储对接项目

## 特性

- [X] `YmOssTemplateContext` 消息发送工具类

## 快速开始

- **注意：** `qifu-saas-parent >= 2.0.0-SNAPSHOT`

### 添加依赖

```xml

<dependency>
    <groupId>com.yuanmeng.engine</groupId>
    <artifactId>engine-starter-oss</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>
```

### 配置 OSS

```yaml
yuanmeng:
  oss:
    #- 阿里云
    endpoint: https://oss-cn-shenzhen.aliyuncs.com
    region: cn-shenzhen
    access-key: xxx
    secret-key: xxx
    bucket-name: xxx
    path-style-access: false
    configs:
      #- minio
      minIoOssTemplate:
        endpoint: http://local.com:9000
        region: cn-shenzhen
        access-key: xxx
        secret-key: xxx
        bucket-name: aws-s3-client
        path-style-access: true
```

## 工具使用

### 文件存储使用

```java

@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/oss")
public class TestController {

    @PostMapping("/upload")
    public String upload(MultipartFile file,
                         @RequestParam(value = "client", required = false) String client) throws IOException {
        log.info(YmThreadLocalUtils.getTokenInfoString());
        PutObjectResponse local = YmOssTemplateContext.load(client)
                .putObject(file.getOriginalFilename(), file.getInputStream());
        return local.toString();
    }

    @GetMapping("/url-get")
    public String getUrl(@RequestParam("name") String objectName,
                         @RequestParam(value = "client", required = false) String client) {
        log.info(YmThreadLocalUtils.getTokenInfoString());
        return YmOssTemplateContext.load(client).getObjectURL(objectName);
    }

    @GetMapping("/url-get-presigned")
    public String getPresignedUrl(@RequestParam("name") String objectName,
                                  @RequestParam(value = "client", required = false) String client) {
        log.info(YmThreadLocalUtils.getTokenInfoString());
        return YmOssTemplateContext.load(client).getPresignedURL(objectName, 10);
    }

    @GetMapping("/url-post-presigned")
    public String getPostPresignedUrl(@RequestParam("name") String objectName,
                                      @RequestParam(value = "client", required = false) String client) {
        log.info(YmThreadLocalUtils.getTokenInfoString());
        return YmOssTemplateContext.load(client).getPutPresignedURL(objectName, 10);
    }

}
```

## 完整配置

```yaml
yuanmeng:
  oss:
    #- 阿里云
    endpoint: https://oss-cn-shenzhen.aliyuncs.com
    region: cn-shenzhen
    access-key: xxx
    secret-key: xxx
    bucket-name: xxx
    path-style-access: false
    configs:
      #- minio
      minIoOssTemplate:
        endpoint: http://local.com:9000
        region: cn-shenzhen
        access-key: xxx
        secret-key: xxx
        bucket-name: aws-s3-client
        path-style-access: true
      #- qiniu
      qiNiuOssTemplate:
        endpoint: xxx
        region: cn-shenzhen
        access-key: xxx
        secret-key: xxx
        bucket-name: aws-s3-client
        path-style-access: true
      #- 其他支持 s3 协议的 oss 存储
```