Building an Enterprise OSS Object Storage Spring Boot Starter Based on Amazon S3

The article introduces the concept of Object Storage Service (OSS) and Amazon S3, highlighting that most cloud providers (Alibaba Cloud OSS, Tencent COS, Qiniu OSS, MinIO, etc.) support the S3 protocol, making it a universal interface for object storage.

It then explains why a Spring Boot starter based on Amazon S3 is advantageous: it abstracts vendor‑specific SDKs, simplifies migration, and provides a consistent API for uploading, downloading, and managing objects.

Step 1: Create a Spring Boot project named oss-spring-boot-starter and add the required Maven dependencies, e.g.:

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

The project's pom.xml is configured with Spring Boot parent, AWS SDK, and Hutool dependencies.

Step 2: Define configuration properties using @ConfigurationProperties(prefix = "oss") in OssProperties , which holds endpoint, region, accessKey, secretKey, and other settings.

@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;
}

Step 3: Create the OssTemplate interface that declares common OSS operations such as creating buckets, uploading files, retrieving objects, generating URLs, and deleting objects.

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;
    // other methods omitted for brevity
}

Step 4: Implement the interface in OssTemplateImpl , delegating to the AmazonS3 client. The implementation includes helper methods for handling metadata and generating pre‑signed URLs.

@RequiredArgsConstructor
public class OssTemplateImpl implements OssTemplate {
    private final AmazonS3 amazonS3;
    @Override
    public void createBucket(String bucketName) {
        if (!amazonS3.doesBucketExistV2(bucketName)) {
            amazonS3.createBucket(bucketName);
        }
    }
    // other methods omitted for brevity
}

Step 5: Auto‑configuration with OssAutoConfiguration creates the AmazonS3 bean (configuring endpoint, credentials, connection pool) and the OssTemplate bean when the client is 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 endpoint = new AwsClientBuilder.EndpointConfiguration(
                props.getEndpoint(), props.getRegion());
        AWSCredentials credentials = new BasicAWSCredentials(props.getAccessKey(), props.getSecretKey());
        return AmazonS3Client.builder()
                .withEndpointConfiguration(endpoint)
                .withClientConfiguration(clientConfig)
                .withCredentials(new AWSStaticCredentialsProvider(credentials))
                .disableChunkedEncoding()
                .withPathStyleAccessEnabled(props.getPathStyleAccess())
                .build();
    }
    @Bean
    @ConditionalOnBean(AmazonS3.class)
    public OssTemplate ossTemplate(AmazonS3 amazonS3) {
        return new OssTemplateImpl(amazonS3);
    }
}

Additional files such as spring.factories register the auto‑configuration, and the ClientConfiguration section explains how to tune connection settings.

Step 6: Packaging and testing – remove the Spring Boot Maven plugin from the starter’s build to avoid install errors, add the Maven source plugin for Javadoc, and run mvn install to publish the starter to the local repository.

In a separate test project, add the starter as a dependency, configure oss.endpoint , oss.accessKey , and oss.secretKey , then write a simple test that creates a bucket using OssTemplate :

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

The article concludes with screenshots of successful bucket creation in MinIO and encourages readers to share the tutorial.