后端脚手架

脚手架

DigitalHainan Spring 微服务框架脚手架与集成指南，覆盖 POM、缓存、MyBatis、认证、OSS 等核心模块。

概述

digitalhainan-oss

本文档用于指导在目标项目中完成 digitalhainan-oss 模块集成。
执行顺序：
先完成「9.1.2 快速集成」的全部步骤（必须）
根据业务需求，查阅「功能集成决策索引」选择对应路径，逐项实现
遇到配置问题时参考「9.1.3 配置属性参考」
出现异常时查阅「9.1.6 常见问题」
代码约定： 所有代码示例均包含完整 import 路径和类声明，可直接用于代码生成。

9.1.1 模块简介

digitalhainan-oss（artifactId: oss-spring-boot-starter）是数字海南框架的对象存储统一接口组件，支持多种存储协议：

IObjectStorageService — 统一存储接口：上传（byte[]/InputStream/本地文件）、下载、删除、签名 URL、分片上传、断点续传
阿里云 OSS — AliyunObjectStorageService 实现
华为云 OBS — ObsStorageService 实现
S3 协议 — S3ObjectStorageService 实现（兼容 MinIO 等）
多数据源 — @Oss 注解动态切换存储实例，支持 defaultDs 默认数据源
签名 URL — 生成带签名的临时访问 URL（支持 GET/PUT）
前端直传 — createPostSignature 生成 PostObject 签名

Maven 坐标：

xml

<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>oss-spring-boot-starter</artifactId>
</dependency>

前置依赖：

依赖	说明
`digitalhainan-pom`	父 POM
`digitalhainan-common`	通用基础组件
`digitalhainan-tools`	工具集

当前版本： 3.1.0-SNAPSHOT

9.1.2 快速集成

9.1.2.1 确认父 POM

xml

<parent>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>digitalhainan-pom</artifactId>
    <version>3.1.0-SNAPSHOT</version>
</parent>

9.1.2.2 添加依赖

xml

<dependencies>
    <dependency>
        <groupId>cn.com.digitalhainan</groupId>
        <artifactId>oss-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

9.1.2.3 配置 OSS 连接（application.yml）

阿里云 OSS 单数据源：

yaml

digitalhainan:
  component:
    oss:
      endpoint: oss-cn-hangzhou.aliyuncs.com
      access-key-id: YOUR_AK
      access-key-secret: YOUR_SK
      bucket-name: your-bucket
      domain: https://your-bucket.oss-cn-hangzhou.aliyuncs.com
      client-type: aliyun

9.1.2.4 验证清单

[ ] Spring Boot 启动成功
[ ] IObjectStorageService Bean 已注册
[ ] 上传/下载功能正常

9.1.3 配置属性参考

9.1.3.1 单数据源配置

配置键	类型	说明
`digitalhainan.component.oss.endpoint`	String	存储服务端点
`digitalhainan.component.oss.access-key-id`	String	AccessKey ID
`digitalhainan.component.oss.access-key-secret`	String	AccessKey Secret
`digitalhainan.component.oss.bucket-name`	String	Bucket 名称
`digitalhainan.component.oss.domain`	String	自定义域名（可选）
`digitalhainan.component.oss.region`	String	区域（S3/OBS 需要）
`digitalhainan.component.oss.client-type`	String	客户端类型：`aliyun` / `obs` / `s3`
`digitalhainan.component.oss.path-style-access`	Boolean	S3 路径风格访问（MinIO 需设为 true）

9.1.3.2 多数据源配置

yaml

digitalhainan:
  component:
    oss:
      default-ds: aliyun-oss    # 默认数据源名称
      ds:
        aliyun-oss:
          endpoint: oss-cn-hangzhou.aliyuncs.com
          access-key-id: YOUR_AK
          access-key-secret: YOUR_SK
          bucket-name: your-bucket
          client-type: aliyun
        huawei-obs:
          endpoint: obs.cn-north-4.myhuaweicloud.com
          access-key-id: YOUR_AK
          access-key-secret: YOUR_SK
          bucket-name: your-obs-bucket
          client-type: obs
        minio:
          endpoint: http://192.168.1.100:9000
          access-key-id: minioadmin
          access-key-secret: minioadmin
          bucket-name: your-minio-bucket
          client-type: s3
          path-style-access: true

9.1.4 核心功能使用

功能集成决策索引

需求场景	参考章节
文件上传（字节数组/流/本地文件）	4.1 文件上传
文件下载	4.2 文件下载
文件删除	4.3 文件删除
签名 URL（临时访问链接）	4.4 签名 URL
分片上传 / 断点续传	4.5 分片上传
前端直传签名	4.6 PostObject 签名
多数据源切换	4.7 @Oss 注解

9.1.4.1 文件上传

java

package com.example.service;

import cn.com.digitalhainan.oss.IObjectStorageService;
import cn.com.digitalhainan.oss.ObjectStorageResponse;
import org.springframework.stereotype.Service;
import java.io.InputStream;

@Service
public class FileUploadService {

    private final IObjectStorageService ossService;

    public FileUploadService(IObjectStorageService ossService) {
        this.ossService = ossService;
    }

    // 字节数组上传
    public ObjectStorageResponse uploadBytes(String fileName, byte[] bytes) {
        return ossService.upload(fileName, bytes);
    }

    // 输入流上传
    public ObjectStorageResponse uploadStream(String fileName, InputStream inputStream) {
        return ossService.upload(fileName, inputStream);
    }

    // 本地文件上传
    public ObjectStorageResponse uploadLocalFile(String fileName, String localFilePath) {
        return ossService.upload(fileName, localFilePath);
    }
}

9.1.4.2 文件下载

java

package com.example.service;

import cn.com.digitalhainan.oss.IObjectStorageService;
import org.springframework.stereotype.Service;
import java.io.InputStream;

@Service
public class FileDownloadService {

    private final IObjectStorageService ossService;

    public FileDownloadService(IObjectStorageService ossService) {
        this.ossService = ossService;
    }

    // 下载到本地文件
    public void downloadToLocal(String objectName, String localFilePath) {
        ossService.download(objectName, localFilePath);
    }

    // 获取输入流
    public InputStream downloadAsStream(String objectName) {
        return ossService.download(objectName);
    }
}

9.1.4.3 文件删除

java

// 删除文件
ossService.delete("path/to/file.txt");

9.1.4.4 签名 URL

java

package com.example.service;

import cn.com.digitalhainan.oss.IObjectStorageService;
import com.aliyun.oss.HttpMethod;
import org.springframework.stereotype.Service;
import java.net.URL;

@Service
public class SignatureUrlService {

    private final IObjectStorageService ossService;

    public SignatureUrlService(IObjectStorageService ossService) {
        this.ossService = ossService;
    }

    // 生成 GET 签名 URL（有效期 3600 秒）
    public String getSignedUrl(String objectName) {
        return ossService.securityUrlStr(objectName, 3600L);
    }

    // 生成 PUT 签名 URL（用于前端直传）
    public String getPutSignedUrl(String objectName) {
        return ossService.securityUrlStr(objectName, 3600L, HttpMethod.PUT);
    }

    // 获取公开访问 URL（Bucket 需为公共读）
    public String getPublicUrl(String objectName) {
        return ossService.getObjectUrl(objectName);
    }
}

9.1.4.5 分片上传 / 断点续传

java

// 分片上传
String uploadId = ossService.getUploadId("large-file.zip");
// ... 分片上传各部分
// ossService.uploadPart("large-file.zip", uploadId, partNumber, offset, partSize, bytes);
// ossService.completeMultipartUpload("large-file.zip", uploadId, partEtags);

// 断点续传（本地文件）
ossService.resumeUpload("large-file.zip", "/path/to/large-file.zip", 3, 10 * 1024 * 1024);

9.1.4.6 PostObject 签名（前端直传）

java

import cn.com.digitalhainan.oss.model.Signature;
import java.util.Map;

// 生成前端直传签名
Signature signature = ossService.createPostSignature(null, null, null);
// 返回 Signature 对象，包含 signature、policy、url 字段
// 前端使用这些参数通过 PostObject 方式直传文件到 OSS

9.1.4.7 @Oss 注解 — 多数据源切换

java

package com.example.service;

import cn.com.digitalhainan.oss.IObjectStorageService;
import cn.com.digitalhainan.oss.ObjectStorageResponse;
import cn.com.digitalhainan.oss.source.annatation.Oss;
import org.springframework.stereotype.Service;

@Service
public class MultiOssService {

    private final IObjectStorageService ossService;

    public MultiOssService(IObjectStorageService ossService) {
        this.ossService = ossService;
    }

    // 使用默认数据源
    public ObjectStorageResponse uploadDefault(String fileName, byte[] bytes) {
        return ossService.upload(fileName, bytes);
    }

    // 切换到华为云 OBS
    @Oss("huawei-obs")
    public ObjectStorageResponse uploadToObs(String fileName, byte[] bytes) {
        return ossService.upload(fileName, bytes);
    }

    // 切换到 MinIO
    @Oss("minio")
    public ObjectStorageResponse uploadToMinio(String fileName, byte[] bytes) {
        return ossService.upload(fileName, bytes);
    }
}

9.1.5 版本变更记录

v3.1.0（当前版本）

支持 defaultDs 默认数据源
修复多数据源不生效问题
支持前端上传（PostObject 签名）

v3.0.1

OSS 支持多数据源

v3.0.0

Spring Boot 3.x 适配

v2.1.0

多数据源功能

v2.0.0

初始版本

9.1.6 常见问题

Q1：启动报错 "No bean 'IObjectStorageService' available"？

原因： 未配置 OSS 连接参数。 解决： 在 application.yml 中配置 digitalhainan.component.oss 的 endpoint/accessKeyId/accessKeySecret/bucketName/clientType。

Q2：多数据源 @Oss 注解不生效？

原因： 同类内部方法调用导致 AOP 代理未生效。 解决： 确保 @Oss 注解的方法被不同 Bean 调用。

Q3：S3/MinIO 上传报 "NoSuchBucket"？

原因： 未开启路径风格访问。 解决： 设置 digitalhainan.component.oss.path-style-access: true（MinIO 必须）。

Q4：签名 URL 过期？

原因： expiration 参数单位为秒，设置过小。 解决： 根据业务需要设置合理的过期时间，如 3600 秒（1 小时）。

9.1.7 版本兼容性矩阵

oss-spring-boot-starter	Spring Boot	JDK	存储协议	说明
3.1.0-SNAPSHOT	3.x	21	阿里云 OSS / 华为 OBS / S3	当前版本，多数据源
3.0.0 ~ 3.0.1	3.x	21	阿里云 OSS / 华为 OBS / S3	Spring Boot 3.x
2.0.0 ~ 2.1.0	2.x	8/11	阿里云 OSS	javax 命名空间

digitalhainan-oss ​

9.1.1 模块简介 ​

9.1.2 快速集成 ​

9.1.2.1 确认父 POM ​

9.1.2.2 添加依赖 ​

9.1.2.3 配置 OSS 连接（application.yml） ​

9.1.2.4 验证清单 ​

9.1.3 配置属性参考 ​

9.1.3.1 单数据源配置 ​

9.1.3.2 多数据源配置 ​

9.1.4 核心功能使用 ​

功能集成决策索引 ​

9.1.4.1 文件上传 ​

9.1.4.2 文件下载 ​

9.1.4.3 文件删除 ​

9.1.4.4 签名 URL ​

9.1.4.5 分片上传 / 断点续传 ​

9.1.4.6 PostObject 签名（前端直传） ​

9.1.4.7 @Oss 注解 — 多数据源切换 ​

9.1.5 版本变更记录 ​

v3.1.0（当前版本） ​

v3.0.1 ​

v3.0.0 ​

v2.1.0 ​

v2.0.0 ​

9.1.6 常见问题 ​

Q1：启动报错 "No bean 'IObjectStorageService' available"？ ​

Q2：多数据源 @Oss 注解不生效？ ​

Q3：S3/MinIO 上传报 "NoSuchBucket"？ ​

Q4：签名 URL 过期？ ​

9.1.7 版本兼容性矩阵 ​

digitalhainan-oss

9.1.1 模块简介

9.1.2 快速集成

9.1.2.1 确认父 POM

9.1.2.2 添加依赖

9.1.2.3 配置 OSS 连接（application.yml）

9.1.2.4 验证清单

9.1.3 配置属性参考

9.1.3.1 单数据源配置

9.1.3.2 多数据源配置

9.1.4 核心功能使用

功能集成决策索引

9.1.4.1 文件上传

9.1.4.2 文件下载

9.1.4.3 文件删除

9.1.4.4 签名 URL

9.1.4.5 分片上传 / 断点续传

9.1.4.6 PostObject 签名（前端直传）

9.1.4.7 @Oss 注解 — 多数据源切换

9.1.5 版本变更记录

v3.1.0（当前版本）

v3.0.1

v3.0.0

v2.1.0

v2.0.0

9.1.6 常见问题

Q1：启动报错 "No bean 'IObjectStorageService' available"？

Q2：多数据源 @Oss 注解不生效？

Q3：S3/MinIO 上传报 "NoSuchBucket"？

Q4：签名 URL 过期？

9.1.7 版本兼容性矩阵