如何设计非特定化文件上传接口？适配多系统上传需求

1. 先拆分核心职责 #

别把「获取上传凭证」和「执行文件上传」揉在一块，拆成两个独立模块，这样接口就不会绑定S3预签名URL这种特定存储的细节了。

1.1 定义通用的上传数据模型 #

先搞两个通用模型，用来在模块间传递数据，适配不同存储系统的差异：

// 上传请求上下文，封装文件基本信息
public class UploadRequest {
    private InputStream fileStream;
    private String fileName;
    private String contentType;
    // 还可扩展文件大小、存储路径前缀这类通用属性
    // 自行补全getter/setter
}

// 上传结果上下文，封装不同存储系统的返回信息
public class UploadResult {
    private String fileUri; // 通用文件访问地址，比如S3对象URL、其他系统的文件ID转地址
    private Map<String, Object> extraInfo; // 存储系统特定额外信息，比如S3的ETag
    // 自行补全getter/setter
}

1.2 可选：单独定义凭证生成器接口 #

如果有些存储系统需要先获取上传凭证（比如S3预签名URL、阿里云OSS签名地址），单独抽一个接口出来：

public interface UploadCredentialProvider {
    // 根据上传请求生成对应存储系统的上传凭证
    UploadCredential generateCredential(UploadRequest request);
}

// 通用凭证模型，适配不同系统的凭证格式
public class UploadCredential {
    private String url; // 比如S3的预签名URL
    private Map<String, String> headers; // 上传需携带的请求头，比如Content-Type
    private Map<String, Object> params; // 其他参数，比如签名信息
    // 自行补全getter/setter
}

1.3 核心上传器接口 #

这个接口只专注「上传文件」核心动作，不暴露任何具体存储细节，异常别用泛化的Exception，自定义UploadException更清晰：

public interface FileUploader {
    UploadResult upload(UploadRequest request) throws UploadException;
}

2. S3的具体实现示例 #

针对当前S3需求，实现上面的接口即可：

2.1 S3凭证生成器 #

public class S3UploadCredentialProvider implements UploadCredentialProvider {
    private AmazonS3 s3Client;
    private String bucketName;

    @Override
    public UploadCredential generateCredential(UploadRequest request) {
        // 生成S3预签名URL
        GeneratePresignedUrlRequest generateReq = new GeneratePresignedUrlRequest(bucketName, request.getFileName())
                .withMethod(HttpMethod.PUT)
                .withContentType(request.getContentType());
        URL presignedUrl = s3Client.generatePresignedUrl(generateReq);
        
        UploadCredential credential = new UploadCredential();
        credential.setUrl(presignedUrl.toString());
        credential.getHeaders().put("Content-Type", request.getContentType());
        return credential;
    }
}

2.2 S3上传器实现 #

public class S3FileUploader implements FileUploader {
    private S3UploadCredentialProvider credentialProvider;
    private HttpClient httpClient; // 用于发送PUT请求到预签名URL

    @Override
    public UploadResult upload(UploadRequest request) throws UploadException {
        UploadCredential credential = credentialProvider.generateCredential(request);
        // 用HttpClient将InputStream上传到预签名URL
        HttpResponse response = httpClient.put(credential.getUrl(), request.getFileStream(), credential.getHeaders());
        
        UploadResult result = new UploadResult();
        result.setFileUri(credential.getUrl().split("\\?")[0]); // 去掉签名参数，获取原始文件URL
        // 从响应中提取ETag等额外信息存入extraInfo
        return result;
    }
}

3. 未来扩展其他存储的思路 #

比如要支持本地磁盘存储或其他云存储：

• 像本地磁盘这种不需要预签名的存储，直接在FileUploader实现里写文件写入逻辑即可，无需依赖凭证生成器。
• 要是其他需要凭证的存储（比如阿里云OSS），照着S3的实现方式，写对应的UploadCredentialProvider和FileUploader就行，上层业务代码完全不用修改。

4. 上层业务调用示例 #

业务代码只依赖通用接口，完全不用关心具体是S3还是其他存储：

// 注入具体的Uploader实现（比如S3FileUploader）
FileUploader uploader = new S3FileUploader();
UploadRequest request = new UploadRequest();
request.setFileStream(new FileInputStream("test.txt"));
request.setFileName("test.txt");
request.setContentType("text/plain");

UploadResult result = uploader.upload(request);
System.out.println("文件上传完成，访问地址：" + result.getFileUri());

这种设计的优势：

• 接口完全与具体存储解耦，不会被S3预签名URL限制未来扩展。
• 职责单一，凭证生成和上传动作分离，维护扩展更方便。
• 通用模型适配不同存储系统差异，避免重复造轮子。

内容的提问来源于stack exchange，提问作者ismala