如何按深度过滤Boto3 S3对象集合，实现指定层级文件夹的服务端筛选

API 探路者

2026-9-29

解决方案

可以通过S3原生的Delimiter请求参数实现服务端层级过滤，完全不需要拉取全量对象列表，请求成本和你要查询的层级下的对象、文件夹数量正相关，远低于当前的全量拉取过滤方案。

原理说明

S3是扁平结构的对象存储，本身没有原生文件夹概念，/是业界约定的路径分隔符。当你调用对象列表接口时指定Delimiter='/'，S3服务端会直接对返回结果做服务端分组：

所有匹配前缀、且路径中没有额外/的对象会归入Contents数组
所有匹配前缀、且下一级路径相同的公共前缀（即逻辑上的「文件夹」）会归入CommonPrefixes数组

上述过滤逻辑完全在S3服务端完成，不会返回超出目标层级的冗余对象，API请求成本极低。

适配代码实现

你当前需求是查询前缀下层级深度为1的对象，对应实现如下：

bucket = s3.Bucket(bucketName)
target_prefix = 'prefix/'
# 兼容前缀末尾不带/的情况，避免匹配到前缀相似的无关路径
if not target_prefix.endswith('/'):
    target_prefix += '/'

# 带Delimiter参数调用，服务端直接返回目标层级结果
result = bucket.objects.filter(Prefix=target_prefix, Delimiter='/')

# 打印当前层级的所有文件夹（即CommonPrefixes中的内容）
for prefix_obj in result.common_prefixes:
    print(prefix_obj['Prefix'])

# 如果需要同时打印当前层级的非文件夹对象，打开下方注释即可
# for obj in result.all():
#     print(obj.key)

如果需要查询更深的固定层级，只需要在前序层级的CommonPrefixes结果基础上，继续携带Delimiter='/'调用接口即可，全程不需要拉取全量桶对象。