Creating an Enterprise-Grade OSS Object Storage Spring Boot Starter

What is OSS?

Object Storage Service (OSS) is a cloud‑based storage solution that uses HTTP APIs to upload, download, preview, and manage files, offering versioning, permission control, and lifecycle management.

Why Use Amazon S3 Compatibility

Most commercial OSS providers support the Amazon S3 protocol, making it a universal standard for integration and migration across different cloud vendors.

Project Setup

A new Spring Boot project named oss-spring-boot-starter is created, and the required Maven dependencies (AWS SDK for S3, Hutool, Lombok, etc.) are added.

<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk-s3</artifactId>
    <version>1.12.423</version>
</dependency>

Configuration Properties

The OssProperties class binds configuration items prefixed with oss (endpoint, region, accessKey, secretKey, etc.) using Lombok @Data and Spring Boot @ConfigurationProperties .

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

OssTemplate Interface

An interface defining common OSS operations such as bucket creation, object upload/download, URL generation, and deletion is provided.

public interface OssTemplate {
    void createBucket(String bucketName);
    List
getAllBuckets();
    void putObject(String bucketName, String objectName, InputStream stream, String contentType) throws Exception;
    // other methods ...
}

Implementation

The OssTemplateImpl class implements the interface using the Amazon S3 Java SDK, handling bucket management, object upload (including metadata), retrieval, and presigned URL generation.

@RequiredArgsConstructor
public class OssTemplateImpl implements OssTemplate {
    private final AmazonS3 amazonS3;
    // method implementations ...
}

Auto‑Configuration

The OssAutoConfiguration class creates beans for AmazonS3 and OssTemplate with conditional annotations to ensure single instances.

@Configuration
@EnableConfigurationProperties(OssProperties.class)
public class OssAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public AmazonS3 ossClient(OssProperties props) { /* build client */ }

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

Packaging

The starter is packaged as a JAR and registered in META-INF/spring.factories to enable auto‑configuration when added as a dependency.

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

Testing

A sample Spring Boot test project adds the starter dependency, configures OSS credentials, and invokes ossTemplate.createBucket("oss02") to verify functionality.

@SpringBootTest
class TestOssSpringBootStarter {
    @Autowired
    private OssTemplate ossTemplate;

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

Conclusion

The guide demonstrates how to encapsulate OSS operations into a reusable Spring Boot starter, providing a plug‑and‑play solution for various S3‑compatible object storage services.