AWS SDK Java 中预签名 URL 生成与路径编码问题解析

在 AWS S3 服务中使用预签名 URL 进行对象上传时，开发人员可能会遇到签名不匹配的错误（SignatureDoesNotMatch）。本文将通过一个典型场景分析问题根源，并提供正确的解决方案。

问题现象

开发者在生成预签名 URL 时使用了包含路径前缀的 bucket 名称：

String bucketFullPath = "healthusbucket/health/prescriptions-nepals";
GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketFullPath, keyName);

生成的 URL 中路径分隔符被编码为 %2F：

https://s3.us-east-2.amazonaws.com/healthusbucket%2Fhealth%2Fprescriptions-nepals/bfcdab42...

当使用此 URL 进行 PUT 请求时，服务端返回 SignatureDoesNotMatch 错误，提示计算签名与提供的签名不匹配。

根本原因

AWS S3 预签名 URL 的签名计算基于规范请求（Canonical Request），其中包含请求路径的规范化形式。当开发者在 GeneratePresignedUrlRequest 构造函数中传入包含路径的 bucket 名称时：

1. SDK 会对路径中的斜杠进行 URL 编码（/ → %2F）
2. 但服务端在验证签名时，会按照未编码的路径进行计算
3. 这种不一致导致签名验证失败

正确实现方式

AWS SDK 设计规范要求：

• 第一个参数必须是纯 bucket 名称
• 所有路径前缀应作为对象键（key）的一部分

修正后的代码：

String bucketName = "healthusbucket";
String objectKey = "health/prescriptions-nepals/" + keyName;
GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucketName, objectKey);

版本差异说明

虽然某些旧版本 SDK 或框架（如 Micronaut 3.7.9）可能"容忍"这种错误用法，但这属于实现细节的巧合，并非官方支持的行为。新版本通常会严格执行规范，因此表现出不同的行为。

最佳实践建议

1. 始终将 bucket 名称与对象路径明确分离
2. 对于复杂路径，使用 Path 类或字符串拼接构建完整对象键
3. 在生成 URL 后，可通过日志验证路径结构是否符合预期
4. 考虑使用更高版本的 AWS SDK（如 v2），其 API 设计更加明确

签名验证机制解析

AWS 签名过程的核心是规范请求的构建，包括：

1. HTTP 方法（PUT/GET等）
2. 规范化资源路径
3. 排序后的查询字符串
4. 排序后的请求头
5. 签名算法指定的哈希负载

任何环节的细微差异都会导致签名不匹配，因此必须严格按照规范构建请求。

总结

正确处理 S3 预签名 URL 的路径结构是保证签名有效性的关键。开发者应当遵循 AWS SDK 的 API 设计初衷，明确区分 bucket 名称和对象路径，避免依赖特定版本的实现细节。当遇到签名错误时，首先检查规范请求的构建是否符合 AWS 的签名算法要求。