本文详细介绍了如何利用aws php sdk，通过s3 listobjects api的prefix和delimiter参数，高效地获取amazon s3存储桶中指定前缀下的单层对象和“子目录”列表。这种方法能有效避免递归遍历，实现类似文件系统目录结构的单层视图，适用于需要快速定位下一级资源的应用场景。
在Amazon S3中，对象存储的扁平特性意味着没有传统意义上的“文件夹”或“目录”。然而，通过巧妙地利用对象键（Key）中的斜杠（/），我们可以模拟出目录结构。当需要列出某个“目录”下的直接子“目录”或文件，而不深入其内部时，AWS S3的listObjects API提供了两个关键参数：Prefix和Delimiter。
理解核心参数：Prefix 与 Delimiter
- Prefix (前缀): 此参数用于筛选结果，使其仅包含以指定字符串开头的对象。例如，设置Prefix为public/uploads/test_company/，则所有返回的对象键都将以此字符串开头。
-
Delimiter (分隔符): 这是实现单层列表的关键。当设置了Delimiter时（通常是/），S3 API会将其视为一个目录分隔符。这意味着：
- listObjects将只返回在指定Prefix下、且在第一个Delimiter之前结束的对象（即直接位于该“目录”下的文件）。
- 它还会返回一个名为CommonPrefixes的列表，其中包含了所有直接位于Prefix下、以Delimiter结尾的“子目录”名称。这些“子目录”本身并不是对象，而是S3为了模拟目录结构而聚合的键前缀。
结合这两个参数，我们可以实现只获取指定路径下第一级“子目录”和文件的需求。例如，如果我们的对象键有：
public/uploads/test_company/test1 public/uploads/test_company/test2 public/uploads/test_company/test1/test.txt
当设置Prefix为public/uploads/test_company/，Delimiter为/时，S3将返回：
- 在CommonPrefixes中包含：public/uploads/test_company/test1/ 和 public/uploads/test_company/test2/。
- Contents列表将为空（因为没有直接位于public/uploads/test_company/且不包含进一步斜杠的对象）。
通过处理CommonPrefixes，我们就能得到所需的test1和test2。
立即学习“PHP免费学习笔记（深入）”；
PHP SDK 实现示例
以下是使用AWS PHP SDK v3实现这一功能的代码示例：
<?php
<p>require 'vendor/autoload.php'; // 假设已通过Composer安装AWS SDK</p><p>use Aws\S3\S3Client;
use Aws\Exception\AwsException;</p><p>// 1. 初始化S3客户端
// 请替换为您的AWS区域和凭证信息
$s3Client = new S3Client([
'version' => 'latest',
'region' => 'your-aws-region', // 例如: 'us-east-1'
'credentials' => [
'key' => 'YOUR_AWS_ACCESS_KEY_ID',
'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY',
],
]);</p><p>$bucketName = 'your-s3-bucket-name'; // 您的S3存储桶名称
$targetPrefix = 'public/uploads/test_company/'; // 目标前缀，通常以'/'结尾</p><p>try {
// 2. 调用 listObjects 方法，并设置 Prefix 和 Delimiter
$result = $s3Client->listObjects([
'Bucket' => $bucketName,
'Prefix' => $targetPrefix,
'Delimiter' => '/',
]);</p><pre class="brush:php;toolbar:false;">echo "在 '{$targetPrefix}' 下找到的顶级子项:\n";
// 3. 处理 CommonPrefixes (模拟的子目录)
if (isset($result['CommonPrefixes'])) {
foreach ($result['CommonPrefixes'] as $commonPrefix) {
// commonPrefix['Prefix'] 的格式为 'public/uploads/test_company/test1/'
// 我们需要提取 'test1'
$folderName = rtrim(str_replace($targetPrefix, '', $commonPrefix['Prefix']), '/');
echo "- 子目录: {$folderName}\n";
}
}
// 4. 处理 Contents (直接位于当前前缀下的文件，不含Delimiter)
// 在本例中，如果 'test1' 和 'test2' 是唯一的顶级项，此列表可能为空。
// 如果有文件如 'public/uploads/test_company/report.pdf'，它将出现在这里。
if (isset($result['Contents'])) {
foreach ($result['Contents'] as $object) {
$objectKey = $object['Key'];
// 确保是直接子文件，而不是深层文件
// 检查对象键是否直接在目标前缀下，且不包含额外的斜杠
$relativeKey = str_replace($targetPrefix, '', $objectKey);
if (!empty($relativeKey) && strpos($relativeKey, '/') === false) {
echo "- 文件: {$relativeKey}\n";
}
}
}} catch (AwsException $e) { // 错误处理 echo "列出S3对象时发生错误: " . $e->getMessage(); }
?>
注意事项与最佳实践
- Prefix的结尾斜杠: 当您希望列出某个“目录”下的内容时，Prefix通常应以/结尾。例如，public/uploads/test_company/。如果不以斜杠结尾，例如public/uploads/test_company，则可能会匹配到以test_company开头的所有对象，包括public/uploads/test_company_new/file.txt，这不是我们期望的“目录”行为。
- 分页处理: 对于包含大量对象（超过1000个）的存储桶，listObjects API会进行分页。您需要检查返回结果中的IsTruncated字段和NextMarker（或使用listObjectsV2的ContinuationToken）来迭代获取所有结果。
- 性能考虑: 尽管S3的列表操作速度很快，但频繁或大规模地列出对象仍然会产生开销。设计应用时应考虑缓存机制或事件驱动的更新。
- 错误处理: 务必在实际应用中加入健壮的错误处理逻辑，捕获AwsException以应对网络问题、权限不足等情况。
总结
通过巧妙地结合使用listObjects API的Prefix和Delimiter参数，AWS PHP SDK能够轻松实现S3存储桶
