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

The article explains how to create an enterprise‑level OSS (Object Storage Service) Spring Boot starter that works out‑of‑the‑box and can be used with various cloud storage providers such as Alibaba Cloud OSS, Tencent COS, Qiniu OSS, and MinIO.

What is OSS?

OSS is a service that stores and retrieves objects over HTTP, offering features like upload, download, preview, versioning, permission control, and lifecycle management.

Why use Amazon S3 as the underlying protocol?

Most commercial OSS providers support the Amazon S3 API, so building a starter on top of S3 ensures compatibility, easy migration, and minimal code changes when switching providers.

Creating the Spring Boot project

A new Maven project named oss-spring-boot-starter is created.

Adding required dependencies

<!-- 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 is shown, including Spring Boot parent, Lombok, and the AWS SDK.

Defining configuration properties

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

/**
 * @Author 公众号：码猿技术专栏
 * @Description Oss配置类
 */
@Data
@ConfigurationProperties(prefix = "oss")
public class OssProperties {
    private String endpoint;
    private String region;
    private Boolean pathStyleAccess = true;
    private String accessKey;
    private String secretKey;
    private Integer maxConnections = 100;
}

Creating the OSS template interface

/**
 * oss操作模板
 */
public interface OssTemplate {
    void createBucket(String bucketName);
    List
getAllBuckets();
    void removeBucket(String bucketName);
    void putObject(String bucketName, String objectName, InputStream stream, String contextType) 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

@RequiredArgsConstructor
public class OssTemplateImpl implements OssTemplate {
    private final AmazonS3 amazonS3;
    // methods delegating to amazonS3 (createBucket, listBuckets, deleteBucket, putObject, getObject, generatePresignedUrl, etc.)
    private PutObjectResult putObject(String bucketName, String objectName, InputStream stream, long size, String contextType) {
        byte[] bytes = IOUtils.toByteArray(stream);
        ObjectMetadata meta = new ObjectMetadata();
        meta.setContentLength(size);
        meta.setContentType(contextType);
        return amazonS3.putObject(bucketName, objectName, new ByteArrayInputStream(bytes), meta);
    }
}

Auto‑configuration

@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 endpoint = new AwsClientBuilder.EndpointConfiguration(props.getEndpoint(), props.getRegion());
        AWSCredentials cred = new BasicAWSCredentials(props.getAccessKey(), props.getSecretKey());
        return AmazonS3Client.builder()
                .withEndpointConfiguration(endpoint)
                .withClientConfiguration(clientConfig)
                .withCredentials(new AWSStaticCredentialsProvider(cred))
                .disableChunkedEncoding()
                .withPathStyleAccessEnabled(props.getPathStyleAccess())
                .build();
    }

    @Bean
    @ConditionalOnBean(AmazonS3.class)
    public OssTemplate ossTemplate(AmazonS3 amazonS3) {
        return new OssTemplateImpl(amazonS3);
    }
}

spring.factories

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

Packaging and installation

The project is built with mvn install after removing the Spring Boot Maven plugin to avoid conflicts, producing a JAR that can be published to a local Maven repository.

Testing the starter

@SpringBootTest
class TestOssSpringBootStarterApplicationTests {
    @Autowired
    private OssTemplate ossTemplate;

    @Test
    void contextLoads() {
        ossTemplate.createBucket("oss02");
    }
}

A test Spring Boot application adds the starter as a dependency, configures the oss.* properties for a MinIO instance, and verifies bucket creation.

Conclusion

The guide demonstrates a complete workflow—from project setup, dependency management, and configuration to implementation, auto‑configuration, packaging, and testing—enabling developers to quickly integrate any S3‑compatible object storage service into their Java backend applications.