Creating an Enterprise‑Grade OSS Object Storage Spring Boot Starter Based on the Amazon S3 Protocol

What is OSS?

OSS (Object Storage Service) is a cloud‑based service that stores and retrieves objects via HTTP APIs, offering features such as file upload, download, preview, versioning, permission control, and lifecycle management.

Why Use OSS in a Project?

Object storage is essential for managing images, files, audio, and other binary assets, providing centralized permission control, lifecycle policies, and operations like upload, download, preview, and deletion.

What is Amazon S3?

Amazon Simple Storage Service (Amazon S3) is the original cloud object storage service from AWS; its S3 protocol has become the industry standard and is supported by most OSS providers.

Supported Providers (S3‑Compatible)

Alibaba Cloud OSS

Qiniu Cloud OSS

Tencent Cloud COS

MinIO

Why Build a Spring Boot Starter Based on Amazon S3?

Because most OSS providers are S3‑compatible, a unified starter allows seamless switching between providers without code changes; only the endpoint and credentials need to be configured.

Creating the Spring Boot Project

Initialize a new Spring Boot project named oss-spring-boot-starter .

Adding Required Dependencies

Include the Amazon S3 SDK and Hutool core libraries in pom.xml :

<!-- https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-s3 -->
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk-s3</artifactId>
    <version>1.12.423</version>
</dependency>

The full pom.xml for the starter is:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.9</version>
        <relativePath />
    </parent>
    <groupId>com.qing</groupId>
    <artifactId>oss-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>oss-spring-boot-starter</name>
    <description>Demo oss-spring-boot-starter</description>
    <properties>
        <java.version>1.8</java.version>
        <aws.version>1.12.423</aws.version>
        <hutool.version>5.8.5</hutool.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <!-- Amazon S3 SDK -->
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-s3</artifactId>
            <version>${aws.version}</version>
        </dependency>
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-core</artifactId>
            <version>${hutool.version}</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>RELEASE</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

Defining Configuration Properties

Create a class OssProperties annotated with @ConfigurationProperties(prefix = "oss") and Lombok's @Data to bind properties such as endpoint, region, accessKey, secretKey, etc.

oss.endpoint=xxx
oss.accessKey=xxx
oss.secretKey=xxx

/**
 * @Author 公众号：码猿技术专栏
 * @Description Oss configuration class
 */
@Data
@ConfigurationProperties(prefix = "oss")
public class OssProperties {
    /** Object storage service URL */
    private String endpoint;
    /** Region */
    private String region;
    /** Path‑style access flag */
    private Boolean pathStyleAccess = true;
    /** Access key */
    private String accessKey;
    /** Secret key */
    private String secretKey;
    /** Max connections, default 100 */
    private Integer maxConnections = 100;
}

Creating the OssTemplate Interface

Define an interface that abstracts common OSS operations such as bucket creation, object upload, download, URL generation, and deletion.

/**
 * @Description OSS operation template
 */
public interface OssTemplate {
    void createBucket(String bucketName);
    List
getAllBuckets();
    void removeBucket(String bucketName);
    void putObject(String bucketName, String objectName, InputStream stream, String contentType) throws Exception;
    void putObject(String bucketName, String objectName, InputStream stream) throws Exception;
    S3Object getObject(String bucketName, String objectName);
    String getObjectURL(String bucketName, String objectName, Integer expires);
    void removeObject(String bucketName, String objectName) throws Exception;
    List
getAllObjectsByPrefix(String bucketName, String prefix, boolean recursive);
}

Implementing the Template

Provide an implementation OssTemplateImpl that delegates to the Amazon S3 Java SDK. Key methods include bucket management, object upload (with metadata handling), URL generation, and object listing.

@RequiredArgsConstructor
public class OssTemplateImpl implements OssTemplate {
    private final AmazonS3 amazonS3;
    @Override
    @SneakyThrows
    public void createBucket(String bucketName) {
        if (!amazonS3.doesBucketExistV2(bucketName)) {
            amazonS3.createBucket(bucketName);
        }
    }
    // ... other methods omitted for brevity, each calling the corresponding AmazonS3 API
    private PutObjectResult putObject(String bucketName, String objectName, InputStream stream, long size, String contentType) {
        byte[] bytes = IOUtils.toByteArray(stream);
        ObjectMetadata metadata = new ObjectMetadata();
        metadata.setContentLength(size);
        metadata.setContentType(contentType);
        return amazonS3.putObject(bucketName, objectName, new ByteArrayInputStream(bytes), metadata);
    }
}

Auto‑Configuration

Define OssAutoConfiguration to create beans for AmazonS3 and OssTemplate when the required properties are present.

@Configuration
@RequiredArgsConstructor
@EnableConfigurationProperties(OssProperties.class)
public class OssAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public AmazonS3 ossClient(OssProperties props) {
        ClientConfiguration clientConfig = new ClientConfiguration();
        clientConfig.setMaxConnections(props.getMaxConnections());
        AwsClientBuilder.EndpointConfiguration endpointConfig =
            new AwsClientBuilder.EndpointConfiguration(props.getEndpoint(), props.getRegion());
        AWSCredentials credentials = new BasicAWSCredentials(props.getAccessKey(), props.getSecretKey());
        return AmazonS3Client.builder()
            .withEndpointConfiguration(endpointConfig)
            .withClientConfiguration(clientConfig)
            .withCredentials(new AWSStaticCredentialsProvider(credentials))
            .disableChunkedEncoding()
            .withPathStyleAccessEnabled(props.getPathStyleAccess())
            .build();
    }
    @Bean
    @ConditionalOnBean(AmazonS3.class)
    public OssTemplate ossTemplate(AmazonS3 amazonS3) {
        return new OssTemplateImpl(amazonS3);
    }
}

Registering the Starter

Add a spring.factories file under src/main/resources/META-INF :

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.qing.oss.OssAutoConfiguration

Packaging and Installing

Run mvn clean install after removing the default Spring Boot Maven plugin to avoid conflicts. The resulting JAR is placed in the local Maven repository and can be referenced by other projects.

Testing the Starter

Create a separate Spring Boot test project, add the starter as a dependency, configure the OSS properties (e.g., MinIO endpoint, accessKey, secretKey), and write a simple test that creates a bucket using OssTemplate :

@SpringBootTest
class TestOssSpringBootStarterApplication {
    @Autowired
    private OssTemplate ossTemplate;
    @Test
    void contextLoads() {
        ossTemplate.createBucket("oss02");
    }
}

Summary

The article demonstrates how to build an enterprise‑grade OSS object‑storage Spring Boot starter that works out‑of‑the‑box with major providers (Alibaba Cloud OSS, Tencent COS, Qiniu OSS, MinIO) by leveraging the Amazon S3 protocol, covering project setup, Maven configuration, Java implementation, auto‑configuration, packaging, and testing.