本文介绍如何在 java 中使用 aws sdk v2 的 s3 transfer manager 上传文件时计算本地文件与 s3 上对象的校验和（如 md5），并通过 etag 或 checksum 字段比对，确保数据完整性。
本文介绍如何在 java 中使用 aws sdk v2 的 s3 transfer manager 上传文件时计算本地文件与 s3 上对象的校验和（如 md5），并通过 etag 或 checksum 字段比对，确保数据完整性。
在将文件上传至 Amazon S3 后，验证其完整性至关重要——尤其在传输大文件、跨网络或关键业务场景中。AWS S3 默认对单部分上传（non-multipart）返回的 ETag 即为文件内容的 MD5 哈希值（十六进制小写，无引号），但仅适用于未启用服务端加密（SSE）且非分段上传的场景；若启用 SSE-S3、SSE-KMS 或使用分段上传，ETag 将不再是标准 MD5，而是一个由分块哈希拼接生成的非标准值（如 "<md5-of-each-part>-<part-count>"），此时不可直接用于校验。
✅ 推荐做法：显式计算并传递校验和
自 AWS SDK v2.17.0+ 起，PutObjectRequest 支持 checksumAlgorithm 和 checksumValue 参数，可强制 S3 校验上传数据，并在响应中返回对应 Checksum 字段（如 ChecksumSHA256）。同时，客户端应预先计算本地文件的相同算法哈希值进行比对。
以下是改进后的完整示例（基于 SDK v2.20+）：
import software.amazon.awssdk.checksums.ChecksumValidationException;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.PutObjectResponse;
import software.amazon.awssdk.utils.BinaryUtils;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
public class S3Uploader {
private final S3Client s3Client; // 推荐使用 S3Client 替代 TransferManager 实现精准控制
public S3Uploader(S3Client s3Client) {
this.s3Client = s3Client;
}
public String uploadFileWithChecksum(String bucketName, String key, String filePath)
throws IOException, NoSuchAlgorithmException {
Path path = Path.of(filePath);
byte[] fileBytes = Files.readAllBytes(path);
// ✅ 计算 SHA-256（推荐，兼容所有上传方式 & 加密场景）
String checksumSha256 = BinaryUtils.toHex(
MessageDigest.getInstance("SHA-256").digest(fileBytes)
);
PutObjectRequest request = PutObjectRequest.builder()
.bucket(bucketName)
.key(key)
.checksumAlgorithm("SHA256") // 显式声明校验算法
.build();
PutObjectResponse response = s3Client.putObject(
request,
RequestBody.fromBytes(fileBytes, checksumSha256) // 自动填充校验值
);
// ✅ 验证：S3 返回的 ChecksumSHA256 应与本地一致
String s3Checksum = response.checksumSHA256();
if (!checksumSha256.equalsIgnoreCase(s3Checksum)) {
throw new IllegalStateException(
String.format("Checksum mismatch: local=%s, S3=%s", checksumSha256, s3Checksum)
);
}
return "Upload successful with verified SHA-256 integrity.";
}
}? 注意事项：
- 避免依赖 ETag 进行校验：除非确认是纯 MD5、无加密、单部分上传，否则 ETag 不可靠；
- 优先选用 SHA-256：比 MD5 更安全，且 S3 对 checksumAlgorithm="SHA256" 的支持稳定（包括 SSE 加密场景）；
- 内存优化建议：对于超大文件（>100MB），改用流式读取 + 分块哈希（如 Apache Commons Codec 的 DigestInputStream），避免 Files.readAllBytes() 导致 OOM；
- 异常处理：S3 会在校验失败时直接拒绝上传（HTTP 400 Bad Request + InvalidRequest 错误），因此 putObject() 成功即代表校验通过；但建议仍比对响应中的 checksumSHA256 字段，实现端到端双重保障。
✅ 总结：
通过 PutObjectRequest.checksumAlgorithm 与 RequestBody.fromBytes(..., checksum) 显式传递校验值，结合 S3 的服务端校验能力，可实现高可靠性、低侵入性的上传完整性验证。该方案兼容加密、分段上传及大规模文件场景，是现代 AWS Java SDK 最佳实践。
