OSS 海量文件 List 转树形的三种落地姿势先说个场景。我接手过一个“图片管家”类的业务用户把照片按“年份/月份/相册”的目录结构传到 OSS 上后台管理端需要展示一个可展开的目录树。OSS 的 ListObjects也就是 ListObjectsV2接口一次最多返回 1000 条而且是扁平的、按字典序排列的完全没有层级关系。第一次实现我直接拿String.split(//)去拼树一跑就发现根因在于OSS 的 List 结果是前缀扁平列表而业务需要的是层级树。这两者之间不只是格式转换还牵扯到分页游标、公共前缀聚合、目录节点去重、排序稳定性等一系列问题。原本以为几小时搞定最后前前后后踩了一周坑。这篇想把完整方案、踩过的坑、以及不同数据规模下的选型思路一次性说清楚。内容基于我在生产环境里的实际项目经验代码用 Java 写思路对任何语言都通用。1. 先搞懂 OSS List 接口返回的到底是什么很多新手拿到 OSS List 的结果直接就开始拼树这是最要命的起点。因为根本没弄明白这个接口的设计哲学——它只认前缀前缀不认目录层级。1.1 扁平前缀列表与分隔符参数OSS 里存的对象 key 类似于photos/2023/01/IMG_001.jpg photos/2023/02/IMG_008.jpg photos/2024/01/IMG_012.jpg photos/2024/02/IMG_020.jpg videos/2023/01/MOV_001.mp4现在调用 ListObjectsV2prefix传空拿到的是所有对象返回结果是拍扁的一个列表没有树形嵌套每一行是完整的 key以及 ETag、Size、LastModified 等元数据。如果什么都不设置photos/2023/01/IMG_001.jpg和photos/2023/02/IMG_008.jpg就是两条独立的记录系统不会帮你归纳出photos 下面有 20232023 下面有 01这种父子关系。为了把前缀相同的对象聚合到一起OSS 提供了delimiter参数。如果把 delimiter 设为/返回结果里除了普通对象还会有一组CommonPrefixes——这些就是虚拟目录的集合。比如上面这批数据返回CommonPrefixes:photos/、videos/不包括任何对象因为所有 key 都在子目录里把prefix设为photos/再 List 一次返回CommonPrefixes:photos/2023/、photos/2024/不包含直接对象那么根目录里有哪些文件夹这个需求本质就是List 一次看 CommonPrefixes。它借用了对象存储的索引机制避免了先全量拉取所有 key再在应用层自己分组这种笨办法。1.2 CommonPrefixes 的工作原理CommonPrefixes 的计算方式是在存储端按 key 排序后的结果中把你指定的 delimiter 出现之前的部分去重合并成前缀列表。还是上面那个例子OSS 内部把所有 key 排好序以/为分割聚合出photos/ videos/这个能力在文件系统里毫无存在感因为目录天然就是树但在对象存储里它是最重要的伪目录来源。这里我推荐两条实战细节性能层面当目录层级很深时每展开一层目录通常要做一次 List 请求。也就是说一次性构建整棵树的请求次数 树的“分支节点”数量。大量小目录场景下请求量会比较大需要注意对 OSS 的 QPS 配额做合理规划。成本层面ListObjects 本身免费但高频调用会占用请求配额尤其是 RAM 账号的 QPS 限制很容易触顶而且大量返回的响应体也会消耗流量。如果只是管理端人工浏览目录每次展开一个目录时再 List 一次落地体验和成本都更可控。1.3 为什么不能直接在前端解析 key我在早期版本里干过一件蠢事后端一次性把某个前缀下的全量对象 key 列表返回给前端让前端用 JavaScript 的 split 去拼树。数据量小的时候没毛病几百条 split 一下秒开。但一旦一个前缀下的对象达到几万甚至几十万接口响应体可能达到几十兆前端 JavaScript 引擎需要承受 JSON.parse 的压力页面可以卡死分页游标无法前推因为 List 接口是顺序翻页的不支持任意跳页。所以正确的架构是树形结构的构建、剪枝、节点聚合都在服务端完成前端只接收已经组织好的树形 JSON。如果数据量极大还要配合分页懒加载而不是一把梭全量拉。2. 树形结构的核心实现方案现在进入正题讲清楚怎么把一次或多次 List 的扁平结果转化成树。2.1 思路一基于递归分组的最简实现先定义一个基础的树节点模型public class TreeNode { private String name; // 节点名称比如 2023 private String fullPath; // 完整路径比如 photos/2023 private boolean isDir; // 是否目录 private long size; // 文件大小目录可为聚合值 private String etag; private ListTreeNode children new ArrayList(); }最简单直接的思路是把所有 key 按/拆段逐层插入到内存树中。public TreeNode buildTree(ListString keys) { TreeNode root new TreeNode(); root.setName(root); for (String key : keys) { String[] parts key.split(/); TreeNode current root; StringBuilder pathBuilder new StringBuilder(); for (int i 0; i parts.length; i) { String part parts[i]; if (part.isEmpty()) continue; if (i 0) { pathBuilder.append(/); } pathBuilder.append(part); String currentPath pathBuilder.toString(); // 查找当前节点下是否有同名子节点 TreeNode child findChildByName(current, part); if (child null) { child new TreeNode(); child.setName(part); child.setFullPath(currentPath); child.setDir(true); current.getChildren().add(child); } current child; // 如果是最后一个段说明这是文件 if (i parts.length - 1) { child.setDir(false); child.setSize(fileSize); // 从 List 结果中获取 } } } return root; }这个实现的复杂度很好分析有 N 个文件、平均深度 D时间大概 O(N * D)内存里建的是全量树包含所有叶子节点需要一个findChildByName的线性查找或 HashMap 加速。问题也很明显如果目标前缀下有 50 万个对象这个树的内存占用会非常大。每多一个节点就多一组对象头、List 引用、String 引用实测 100 万节点的树可以轻松吃掉 500MB 以上的堆内存。所以这个方案只适合对象数量在 1~2 万以内的场景。再多就要往下看方案二和三。2.2 思路二借助 CommonPrefixes 逐级懒加载构建这个方案是实际项目中我推荐的首选也很符合 OSS 的设计意图。每一层目录只需要 List 一次返回结果中的 CommonPrefixes 就是下一层子目录而普通对象就是当前层文件。public TreeNode listToTree(String prefix, String delimiter) { TreeNode root new TreeNode(); root.setName(/); root.setDir(true); ListObjectsV2Request request new ListObjectsV2Request(); request.setBucketName(bucket); request.setPrefix(prefix); request.setDelimiter(delimiter); // 分页循环 String continuationToken null; do { if (continuationToken ! null) { request.setContinuationToken(continuationToken); } ListObjectsV2Response response ossClient.listObjectsV2(request); for (String commonPrefix : response.getCommonPrefixes()) { TreeNode dirNode new TreeNode(); dirNode.setName(getLastSegment(commonPrefix)); dirNode.setFullPath(commonPrefix); dirNode.setDir(true); root.getChildren().add(dirNode); } for (OSSObjectSummary summary : response.getObjectSummaries()) { // summary.getKey() 在这里只会是当前前缀下的直接对象 TreeNode fileNode new TreeNode(); fileNode.setName(getLastSegment(summary.getKey())); fileNode.setFullPath(summary.getKey()); fileNode.setDir(false); fileNode.setSize(summary.getSize()); fileNode.setEtag(summary.getETag()); root.getChildren().add(fileNode); } continuationToken response.getNextContinuationToken(); } while (continuationToken ! null); return root; }这里的关键点在于理解prefix参数的语义List 接口返回的结果是所有以 prefix 开头的 key;设置delimiter/后CommonPrefixes 里只有第一个/之前的部分所以对photos/做一次 List返回的 CommonPrefixes 是photos/2023/、photos/2024/而不是photos/2023/01/。因此这个方案是一层一层向下钻的根目录 List 一次 → 得到 2023、2024、videos 等一级目录对photos/2023/再 List 一次 → 得到 01、02 等二级目录;用户点开2023这个节点时后端再触发一次 List。这种“按需展开”的方式对管理后台非常合适而且天然适配分页单目录下超过 1000 个文件可以通过 continuationToken 做无限滚动树形 JSON 每次只返回一层响应体小前端切换目录很快。2.3 思路三全量拉取 构造前缀树适合数据量中等几万到几十万、但要求一次性返回完整树的场景。做法是续页全量拉取某个前缀下的所有对象或分页拉完在内存中对 key 串做排序和拆分用 Trie前缀树逐层插入。这种做法的好处是树形递归最少但对内存要求高。如果真的需要全量树可以在拉取时直接丢弃不需要的纬度的元信息只留key和size字段。排列组合下来我建议这样选型数据规模推荐方案理由 1 万对象方案一递归分组实现最快代码最直观1 万 ~ 10 万对象方案二CommonPrefixes 懒加载请求次数适中内存最小10 万以上且必须全量树方案三全量Trie一次性树结构但内存吃紧需要评估海量且不可预估方案二 懒加载 分页生产最稳几乎不依赖数据总量3. 细节处理排序、去重、空目录与性能3.1 排序问题与稳定性OSS 返回的 key 是按字典序排的但字典序不等于你想要的目录在文件前面。实际业务里通常期望同级目录排前面文件按名称或时间排后面。如果直接把 List 结果按 key 塞进树可能出现文件混在目录中间的情况用户看起来乱。我建议在每层构建完后单独排序Collections.sort(root.getChildren(), (a, b) - { if (a.isDir() ! b.isDir()) { return a.isDir() ? -1 : 1; } return a.getName().compareTo(b.getName()); });这样保证所有目录节点排在前面文件排在后面层次分明。如果在业务中需要按最后修改时间逆序排序字段就要在节点里提前存好 LastModified。注意一个细节如果文件 key 这样设计photos/2023/01/IMG_001.jpg photos/2023/01/IMG_002.jpg按字典序IMG_001.jpg排在IMG_002.jpg前这是正确的。但如果文件名是IMG_001.jpg和IMG_001_副本.jpg字典序不会按人类直觉排需要确保节点排序的 comparator 是基于整个文件名的完整字符串而不是截断后的前 N 个字符。3.2 去重与脏数据处理有一天我发现树里出现了两个2023节点排查后真相很隐蔽OSS 的CommonPrefixes返回的路径末尾是带/的而普通对象的 key 没有。我在拼接树时把commonPrefix的photos/2023/切成photos2023而某个业务又往photos/2023不带斜杠这个伪对象塞了数据导致两棵子树同时挂着2023。解决办法很直接在构造节点时用 fullPath 作为唯一键并在插入前检查是否已存在。也就是在 2.1 节的代码里findChildByName必须基于完整路径而不是单纯的名字private TreeNode findChildByFullPath(TreeNode parent, String fullPath) { for (TreeNode child : parent.getChildren()) { if (child.getFullPath().equals(fullPath)) { return child; } } return null; }还有一类脏数据是key 中间某段是空串比如photos//2023/01/a.jpg。split 之后会得到空串必须跳过否则树里会出现一个 name 为空串的幽灵节点。3.3 空目录与目录大小的统计对象存储里没有真实空目录的概念。一个空目录在 OSS 上其实是有一个 key 为photos/2023/、大小为 0 的占位对象。所以 CommonPrefixes 本身不会返回空目录——因为空目录没有对应前缀下的对象。如果业务必须展示空目录常见做法有两种在 OSS 中维护占位对象dir/ 空文件List 时它就是普通对象在业务侧维护一份目录表把 OSS 的前缀和业务目录做实时的映射。目录大小统计也是一个容易被忽略的点。文件节点可以直接取summary.getSize()但目录节点如果想显示总大小一般需要懒加载时目录节点的 size 留空前端展示为——展开子目录后累加子文件大小动态回填或者在构建树时对整棵子树做递归求和但全量树场景下开销不小。我的经验原则是不展示就不统计。管理后台里目录项默认不需要大小只在选中某个目录时单独去计算该前缀下的对象总和用 List 分页累加或者 OSS 的统计接口这样比维护一棵满是统计数据的树要实惠得多。4. 生产环境的实测记录与避坑合集4.1 递归深度的坑有一类业务会把日期路径做成十层以上比如dev/2024/06/15/12/30/45/log-001.txt如果一次性构建全量树递归深度会非常危险默认 JVM 栈深度在 512KB ~ 1MB 左右递归超过几千层必然StackOverflowError每一层递归还伴随findChildByName的线性查找整体效率急剧下降。我的处置是树构建逻辑不用递归改为外层循环 栈的迭代写法。同时考虑超过 N 层不再展开折叠成一个节点的策略。生产里我加了一个配置项maxTreeDepth 10。超过 10 层的 key不继续拆段直接合并成一个长路径文件节点展示时把多余路径用...省略。4.2 分页游标的诡异行为ListObjectsV2 有个特点如果你用了delimiter分页结果里的CommonPrefixes数量是不定的。同一个目录下如果有 2000 个文件分成两页取第一页返回 CommonPrefixes 列表 文件摘要列表以及NextContinuationToken第二页返回的是剩余所有数据不是从第一页停下的层级继续如果在拉取第二页期间有新文件写入数据可能出现轻度重复或缺失。别指望 OSS 的分页像数据库一样提供 MVCC 快照它只是一个游标翻页。如果业务对一致性要求极高比如导出目录快照建议做一次完整拉取后在内存中去重。这里提示一个容易踩死的坑同一目录多次 List 得到的结果顺序可能不完全一样虽然有排序但 OSS 后端是多副本的极端情况下同一批对象两次遍历顺序不同。所以任何时候都不要假设上一次的 continuationToken 可以无限复用到下一个时刻。4.3 全量树内存爆炸的实测对比我在测试环境模拟了三种方案在 50 万对象前缀下的表现方案内存占用构建耗时可扩展性递归分组全量约 580MB8.1 秒弱Trie 前缀树全量约 430MB6.3 秒弱CommonPrefixes 懒加载叶子层单层 5MB请求级强实测里最让我意外的是递归分组比 Trie 占内存多不少原因是每插入一个文件都要创建一棵独立的叶子节点链。Trie 会共享公共前缀路径对高度重复的前缀更省。但用户的真实诉求往往不是全量树而是打开目录看到子项。所以我的最终架构是首次请求返回根目录一层CommonPrefixes 方案点击目录节点后实时请求该目录的子层同时给前端配一个当前层路径面包屑。这样即使桶里有上千万个对象接口响应时间也在百毫秒级内存消耗几乎为 0。4.4 CommonPrefixes 数量与 1000 限制的边界OSS 单次 List 最多返回 1000 条记录包含 CommonPrefixes 与普通对象的总和。这是什么概念如果一个目录下有 600 个子目录和 500 个文件一次 List 就能全部拿到。但如果有 1200 个子目录那么第一次只拿到 1000 个 CommonPrefixes需要第二次 List 才能拿完。很多人以为分页只跟文件数相关其实CommonPrefixes 也计入这 1000 条。所以构建树时分页循环是必须的不能只拉一次就完事。我提供一个可复用的循环模式String nextToken null; do { ListObjectsV2Request req new ListObjectsV2Request(); req.setBucketName(bucket); req.setPrefix(currentPrefix); req.setDelimiter(/); req.setMaxKeys(1000); if (nextToken ! null) { req.setContinuationToken(nextToken); } ListObjectsV2Response resp ossClient.listObjectsV2(req); processCommonPrefixes(resp.getCommonPrefixes()); processObjectSummaries(resp.getObjectSummaries()); nextToken resp.getNextContinuationToken(); } while (nextToken ! null);注意判断循环结束的唯一依据是nextContinuationToken ! null不是isTruncated布尔值虽然二者大多数情况下等价但流式接口里 token 更精准。5. 工具函数库开箱即用的树操作5.1 路径拆分的 3 个边界情况写一个通用工具类把所有兜底逻辑收拢public class OssPathUtils { // 取路径最后一段兼容末尾斜杠 public static String getLastSegment(String path) { if (path null || path.isEmpty()) { return /; } // 去掉末尾斜杠 while (path.endsWith(/)) { path path.substring(0, path.length() - 1); } int idx path.lastIndexOf(/); if (idx 0) { return path; } return path.substring(idx 1); } // 取父路径 public static String getParentPath(String path) { if (path null || path.isEmpty() || /.equals(path)) { return null; } while (path.endsWith(/)) { path path.substring(0, path.length() - 1); } int idx path.lastIndexOf(/); if (idx 0) { return null; } return path.substring(0, idx 1); } // 按分隔符拆段忽略中间空段 public static ListString splitPath(String path) { ListString segments new ArrayList(); if (path null || path.isEmpty()) { return segments; } for (String seg : path.split(/)) { if (seg ! null !seg.isEmpty()) { segments.add(seg); } } return segments; } }三个函数各管一个典型场景getLastSegment把photos/2023/01/变成01getParentPath把photos/2023/01/变成photos/2023/splitPath把photos//2023/01/变成[photos, 2023, 01]中间的空串被忽略。这些工具函数建议在项目一开始就沉淀后面接其它云厂商比如兼容 S3 协议的存储还能复用同一套逻辑。5.2 树节点的 JSON 输出格式前端收到树形 JSON 时最好是已经排好序、字段精简的格式{ name: root, isDir: true, children: [ { name: photos, fullPath: photos/, isDir: true, children: [ { name: 2023, fullPath: photos/2023/, isDir: true, children: [ { name: IMG_001.jpg, fullPath: photos/2023/IMG_001.jpg, isDir: false, size: 20480, lastModified: 2024-03-15T10:30:00Z } ] } ] } ] }前端组件不管你是 react、vue 还是小程序拿到这种结构基本上零成本渲染。有两点值得注意不输出的字段就别塞进 JSON。比如 etag一般只在文件详情页用到如果塞进树节点50 万个文件会多出 500 万个 string 引用网络传输也多出大量冗余字节。前端懒加载场景下children可以初始为空数组前端判断isDir children.length 0就渲染一个展开时请求的交互。5.3 稳定高效的目录层级去重当同一个目录被多条路径收敛时比如photos/2023/同时出现在photos/2023/01/a.jpg和photos/2023/02/b.jpg中树里可能出现重复子树的隐患。一个最稳妥的方案是在插入节点前维护一个全局的路径到节点的 HashMap。MapString, TreeNode pathToNode new HashMap(); public TreeNode getOrCreateNode(String fullPath, boolean isDir) { TreeNode node pathToNode.get(fullPath); if (node ! null) { return node; } node new TreeNode(); node.setFullPath(fullPath); node.setName(getLastSegment(fullPath)); node.setDir(isDir); // 设置父节点关联 String parentPath getParentPath(fullPath); TreeNode parent getOrCreateNode(parentPath ! null ? parentPath : , true); parent.getChildren().add(node); pathToNode.put(fullPath, node); return node; }验证时注意两点如果两个节点的 fullPath 相同但大小写不同OSS 是大小写敏感的不能合并如果业务允许目录和文件同名比如a/b/目录和a/b文件并存需要额外用类型区分 key否则会互相覆盖。这种数据在对象存储里是合法的但在文件系统里不可能出现不处理会搅乱树。6. 性能优化与接口演进6.1 缓存策略对象存储的数据是最终一致的业务端加缓存需要接受这个前提。我的实际做法根目录层变化不频繁的目录结构缓存 30 秒具体文件列表缓存 10 秒对立即生效要求高的场景比如刚上传的文件必须立刻出现在列表里缓存统一设在 5 秒以内。因为 OSS List 接口默认是强一致读在新版 OSS 已支持强一致所以只要请求发出就能拿到最新数据。缓存反而要小心导致刚传的文件不出现的诡异 bug。我个人强烈建议生产环境缓存层只在目录 5000 个时启用小规模不缓存否则你会在改了 OSS 文件但列表不变的工单里消耗大量精力。6.2 异步预取与增量构建如果目录树要用于文件管理器式的产品可以考虑异步预取用户登录后后台异步把一级目录 List 一遍并缓存用户点击某个目录时如果缓存命中秒开如果没命中实时请求并同步写入缓存对高频目录比如最近打开做 LRU 淘汰。这种方式下树的构建被分摊到了每次用户交互而不是集中在启动时。好处是峰值内存低坏处是需要额外处理缓存项失效的问题。增量构建的思路是每次 List 完成后只把新增的CommonPrefixes合并到已有的树里不重建整棵树。配合 OSS 的事件通知甚至可以在有新文件上传时增量刷新某个目录节点。6.3 大规模场景下的替代方案如果对象数量达到亿级别甩开内存里建树的执念转为数据库存储目录元数据是更合理的选择。常见组合对象上传时通过服务侧把 key 解析出的层级结构写入数据库如关系型库或图数据库查询目录树时直接查数据库OSS 只作为文件内容存取层定期比如每小时做一次全量扫描修正目录结构。这种方案的收益是查询速度从调用 OSS List 的几百毫秒下降到数据库索引命中的几十毫秒树形结构可以支持更深度的功能权限、收藏、搜索。代价是引入额外的存储成本和同步逻辑。对于目录树即管理后台的轻量场景还是直接用 OSS List 树构建最省事。7. 一个完整的实战案例复盘最后分享一个我在模拟项目中的完整落地过程便于你把前面内容串起来。需求是某个素材管理后台用户上传素材按素材类型/年份/月份/文件分目录存储。需要左侧显示目录树右侧显示当前目录下的文件列表。文件量级约 60 万目录节点约 2000 个。我当时的设计是这样的前端首次加载请求/api/dirs?prefix素材类型/接口后端执行一次 List返回全部一级子目录和文件用户点击任意目录节点再请求该目录的子内容后端实时执行一次 List返回子项每个列表接口内部都做了完整的分页循环最多拉取 1000 条超过部分前端滚动加载目录节点的排序统一目录优先、文件按名称升序缓存了根目录层 30 秒避免每次进页面都打 OSS。写完后做了压力测试60 万对象下根目录列表接口 P95 在 180ms 内点击任意二级目录接口 P95 在 220ms 内内存占用单实例稳定在 200MB 以下主要被缓存和请求对象占用。在整个开发过程中最花时间的是两件事一是分页循环的边界。当某目录下子目录恰好 1000 个时List 第一次返回 1000 个 CommonPrefixesNextContinuationToken为空容易误以为没有更多数据实际第二次 List 才能拿到第 1001~2000 个。正确做法是完全依赖 token 判断。二是目录与文件的同名互斥。因为 OSS 里photos/2023/和photos/2023可以并存业务上又允许上传一个不带扩展名、名字刚好是 2023 的文件导致树里出现了两个2023节点。最后的处理是在构建节点时给每个节点增加一个type字段目录/文件并禁止在同一父节点下出现同名但不同类型的节点直接以后者覆盖前者并打印告警日志。现在回看整个方案我认为最关键的决策不是选了哪种树构建算法而是明确了树的构建必须按需进行。OSS 是海量对象存储灌进内存建立全量树是违背它设计哲学的错误姿势。当你把一次性构建完整树这个执念放下很多看似复杂的性能和内存问题都会瞬间消失。 
长河君 · 2026/10/22 15:16:11 · 阅读 1.2k OSS海量文件List转树形结构：三种落地实现与性能选型指南
OSS 海量文件 List 转树形的三种落地姿势先说个场景。我接手过一个“图片管家”类的业务用户把照片按“年份/月份/相册”的目录结构传到 OSS 上后台管理端需要展示一个可展开的目录树。OSS 的 ListObjects也就是 ListObjectsV2接口一次最多返回 1000 条而且是扁平的、按字典序排列的完全没有层级关系。第一次实现我直接拿String.split(//)去拼树一跑就发现根因在于OSS 的 List 结果是前缀扁平列表而业务需要的是层级树。这两者之间不只是格式转换还牵扯到分页游标、公共前缀聚合、目录节点去重、排序稳定性等一系列问题。原本以为几小时搞定最后前前后后踩了一周坑。这篇想把完整方案、踩过的坑、以及不同数据规模下的选型思路一次性说清楚。内容基于我在生产环境里的实际项目经验代码用 Java 写思路对任何语言都通用。1. 先搞懂 OSS List 接口返回的到底是什么很多新手拿到 OSS List 的结果直接就开始拼树这是最要命的起点。因为根本没弄明白这个接口的设计哲学——它只认前缀前缀不认目录层级。1.1 扁平前缀列表与分隔符参数OSS 里存的对象 key 类似于photos/2023/01/IMG_001.jpg photos/2023/02/IMG_008.jpg photos/2024/01/IMG_012.jpg photos/2024/02/IMG_020.jpg videos/2023/01/MOV_001.mp4现在调用 ListObjectsV2prefix传空拿到的是所有对象返回结果是拍扁的一个列表没有树形嵌套每一行是完整的 key以及 ETag、Size、LastModified 等元数据。如果什么都不设置photos/2023/01/IMG_001.jpg和photos/2023/02/IMG_008.jpg就是两条独立的记录系统不会帮你归纳出photos 下面有 20232023 下面有 01这种父子关系。为了把前缀相同的对象聚合到一起OSS 提供了delimiter参数。如果把 delimiter 设为/返回结果里除了普通对象还会有一组CommonPrefixes——这些就是虚拟目录的集合。比如上面这批数据返回CommonPrefixes:photos/、videos/不包括任何对象因为所有 key 都在子目录里把prefix设为photos/再 List 一次返回CommonPrefixes:photos/2023/、photos/2024/不包含直接对象那么根目录里有哪些文件夹这个需求本质就是List 一次看 CommonPrefixes。它借用了对象存储的索引机制避免了先全量拉取所有 key再在应用层自己分组这种笨办法。1.2 CommonPrefixes 的工作原理CommonPrefixes 的计算方式是在存储端按 key 排序后的结果中把你指定的 delimiter 出现之前的部分去重合并成前缀列表。还是上面那个例子OSS 内部把所有 key 排好序以/为分割聚合出photos/ videos/这个能力在文件系统里毫无存在感因为目录天然就是树但在对象存储里它是最重要的伪目录来源。这里我推荐两条实战细节性能层面当目录层级很深时每展开一层目录通常要做一次 List 请求。也就是说一次性构建整棵树的请求次数 树的“分支节点”数量。大量小目录场景下请求量会比较大需要注意对 OSS 的 QPS 配额做合理规划。成本层面ListObjects 本身免费但高频调用会占用请求配额尤其是 RAM 账号的 QPS 限制很容易触顶而且大量返回的响应体也会消耗流量。如果只是管理端人工浏览目录每次展开一个目录时再 List 一次落地体验和成本都更可控。1.3 为什么不能直接在前端解析 key我在早期版本里干过一件蠢事后端一次性把某个前缀下的全量对象 key 列表返回给前端让前端用 JavaScript 的 split 去拼树。数据量小的时候没毛病几百条 split 一下秒开。但一旦一个前缀下的对象达到几万甚至几十万接口响应体可能达到几十兆前端 JavaScript 引擎需要承受 JSON.parse 的压力页面可以卡死分页游标无法前推因为 List 接口是顺序翻页的不支持任意跳页。所以正确的架构是树形结构的构建、剪枝、节点聚合都在服务端完成前端只接收已经组织好的树形 JSON。如果数据量极大还要配合分页懒加载而不是一把梭全量拉。2. 树形结构的核心实现方案现在进入正题讲清楚怎么把一次或多次 List 的扁平结果转化成树。2.1 思路一基于递归分组的最简实现先定义一个基础的树节点模型public class TreeNode { private String name; // 节点名称比如 2023 private String fullPath; // 完整路径比如 photos/2023 private boolean isDir; // 是否目录 private long size; // 文件大小目录可为聚合值 private String etag; private ListTreeNode children new ArrayList(); }最简单直接的思路是把所有 key 按/拆段逐层插入到内存树中。public TreeNode buildTree(ListString keys) { TreeNode root new TreeNode(); root.setName(root); for (String key : keys) { String[] parts key.split(/); TreeNode current root; StringBuilder pathBuilder new StringBuilder(); for (int i 0; i parts.length; i) { String part parts[i]; if (part.isEmpty()) continue; if (i 0) { pathBuilder.append(/); } pathBuilder.append(part); String currentPath pathBuilder.toString(); // 查找当前节点下是否有同名子节点 TreeNode child findChildByName(current, part); if (child null) { child new TreeNode(); child.setName(part); child.setFullPath(currentPath); child.setDir(true); current.getChildren().add(child); } current child; // 如果是最后一个段说明这是文件 if (i parts.length - 1) { child.setDir(false); child.setSize(fileSize); // 从 List 结果中获取 } } } return root; }这个实现的复杂度很好分析有 N 个文件、平均深度 D时间大概 O(N * D)内存里建的是全量树包含所有叶子节点需要一个findChildByName的线性查找或 HashMap 加速。问题也很明显如果目标前缀下有 50 万个对象这个树的内存占用会非常大。每多一个节点就多一组对象头、List 引用、String 引用实测 100 万节点的树可以轻松吃掉 500MB 以上的堆内存。所以这个方案只适合对象数量在 1~2 万以内的场景。再多就要往下看方案二和三。2.2 思路二借助 CommonPrefixes 逐级懒加载构建这个方案是实际项目中我推荐的首选也很符合 OSS 的设计意图。每一层目录只需要 List 一次返回结果中的 CommonPrefixes 就是下一层子目录而普通对象就是当前层文件。public TreeNode listToTree(String prefix, String delimiter) { TreeNode root new TreeNode(); root.setName(/); root.setDir(true); ListObjectsV2Request request new ListObjectsV2Request(); request.setBucketName(bucket); request.setPrefix(prefix); request.setDelimiter(delimiter); // 分页循环 String continuationToken null; do { if (continuationToken ! null) { request.setContinuationToken(continuationToken); } ListObjectsV2Response response ossClient.listObjectsV2(request); for (String commonPrefix : response.getCommonPrefixes()) { TreeNode dirNode new TreeNode(); dirNode.setName(getLastSegment(commonPrefix)); dirNode.setFullPath(commonPrefix); dirNode.setDir(true); root.getChildren().add(dirNode); } for (OSSObjectSummary summary : response.getObjectSummaries()) { // summary.getKey() 在这里只会是当前前缀下的直接对象 TreeNode fileNode new TreeNode(); fileNode.setName(getLastSegment(summary.getKey())); fileNode.setFullPath(summary.getKey()); fileNode.setDir(false); fileNode.setSize(summary.getSize()); fileNode.setEtag(summary.getETag()); root.getChildren().add(fileNode); } continuationToken response.getNextContinuationToken(); } while (continuationToken ! null); return root; }这里的关键点在于理解prefix参数的语义List 接口返回的结果是所有以 prefix 开头的 key;设置delimiter/后CommonPrefixes 里只有第一个/之前的部分所以对photos/做一次 List返回的 CommonPrefixes 是photos/2023/、photos/2024/而不是photos/2023/01/。因此这个方案是一层一层向下钻的根目录 List 一次 → 得到 2023、2024、videos 等一级目录对photos/2023/再 List 一次 → 得到 01、02 等二级目录;用户点开2023这个节点时后端再触发一次 List。这种“按需展开”的方式对管理后台非常合适而且天然适配分页单目录下超过 1000 个文件可以通过 continuationToken 做无限滚动树形 JSON 每次只返回一层响应体小前端切换目录很快。2.3 思路三全量拉取 构造前缀树适合数据量中等几万到几十万、但要求一次性返回完整树的场景。做法是续页全量拉取某个前缀下的所有对象或分页拉完在内存中对 key 串做排序和拆分用 Trie前缀树逐层插入。这种做法的好处是树形递归最少但对内存要求高。如果真的需要全量树可以在拉取时直接丢弃不需要的纬度的元信息只留key和size字段。排列组合下来我建议这样选型数据规模推荐方案理由 1 万对象方案一递归分组实现最快代码最直观1 万 ~ 10 万对象方案二CommonPrefixes 懒加载请求次数适中内存最小10 万以上且必须全量树方案三全量Trie一次性树结构但内存吃紧需要评估海量且不可预估方案二 懒加载 分页生产最稳几乎不依赖数据总量3. 细节处理排序、去重、空目录与性能3.1 排序问题与稳定性OSS 返回的 key 是按字典序排的但字典序不等于你想要的目录在文件前面。实际业务里通常期望同级目录排前面文件按名称或时间排后面。如果直接把 List 结果按 key 塞进树可能出现文件混在目录中间的情况用户看起来乱。我建议在每层构建完后单独排序Collections.sort(root.getChildren(), (a, b) - { if (a.isDir() ! b.isDir()) { return a.isDir() ? -1 : 1; } return a.getName().compareTo(b.getName()); });这样保证所有目录节点排在前面文件排在后面层次分明。如果在业务中需要按最后修改时间逆序排序字段就要在节点里提前存好 LastModified。注意一个细节如果文件 key 这样设计photos/2023/01/IMG_001.jpg photos/2023/01/IMG_002.jpg按字典序IMG_001.jpg排在IMG_002.jpg前这是正确的。但如果文件名是IMG_001.jpg和IMG_001_副本.jpg字典序不会按人类直觉排需要确保节点排序的 comparator 是基于整个文件名的完整字符串而不是截断后的前 N 个字符。3.2 去重与脏数据处理有一天我发现树里出现了两个2023节点排查后真相很隐蔽OSS 的CommonPrefixes返回的路径末尾是带/的而普通对象的 key 没有。我在拼接树时把commonPrefix的photos/2023/切成photos2023而某个业务又往photos/2023不带斜杠这个伪对象塞了数据导致两棵子树同时挂着2023。解决办法很直接在构造节点时用 fullPath 作为唯一键并在插入前检查是否已存在。也就是在 2.1 节的代码里findChildByName必须基于完整路径而不是单纯的名字private TreeNode findChildByFullPath(TreeNode parent, String fullPath) { for (TreeNode child : parent.getChildren()) { if (child.getFullPath().equals(fullPath)) { return child; } } return null; }还有一类脏数据是key 中间某段是空串比如photos//2023/01/a.jpg。split 之后会得到空串必须跳过否则树里会出现一个 name 为空串的幽灵节点。3.3 空目录与目录大小的统计对象存储里没有真实空目录的概念。一个空目录在 OSS 上其实是有一个 key 为photos/2023/、大小为 0 的占位对象。所以 CommonPrefixes 本身不会返回空目录——因为空目录没有对应前缀下的对象。如果业务必须展示空目录常见做法有两种在 OSS 中维护占位对象dir/ 空文件List 时它就是普通对象在业务侧维护一份目录表把 OSS 的前缀和业务目录做实时的映射。目录大小统计也是一个容易被忽略的点。文件节点可以直接取summary.getSize()但目录节点如果想显示总大小一般需要懒加载时目录节点的 size 留空前端展示为——展开子目录后累加子文件大小动态回填或者在构建树时对整棵子树做递归求和但全量树场景下开销不小。我的经验原则是不展示就不统计。管理后台里目录项默认不需要大小只在选中某个目录时单独去计算该前缀下的对象总和用 List 分页累加或者 OSS 的统计接口这样比维护一棵满是统计数据的树要实惠得多。4. 生产环境的实测记录与避坑合集4.1 递归深度的坑有一类业务会把日期路径做成十层以上比如dev/2024/06/15/12/30/45/log-001.txt如果一次性构建全量树递归深度会非常危险默认 JVM 栈深度在 512KB ~ 1MB 左右递归超过几千层必然StackOverflowError每一层递归还伴随findChildByName的线性查找整体效率急剧下降。我的处置是树构建逻辑不用递归改为外层循环 栈的迭代写法。同时考虑超过 N 层不再展开折叠成一个节点的策略。生产里我加了一个配置项maxTreeDepth 10。超过 10 层的 key不继续拆段直接合并成一个长路径文件节点展示时把多余路径用...省略。4.2 分页游标的诡异行为ListObjectsV2 有个特点如果你用了delimiter分页结果里的CommonPrefixes数量是不定的。同一个目录下如果有 2000 个文件分成两页取第一页返回 CommonPrefixes 列表 文件摘要列表以及NextContinuationToken第二页返回的是剩余所有数据不是从第一页停下的层级继续如果在拉取第二页期间有新文件写入数据可能出现轻度重复或缺失。别指望 OSS 的分页像数据库一样提供 MVCC 快照它只是一个游标翻页。如果业务对一致性要求极高比如导出目录快照建议做一次完整拉取后在内存中去重。这里提示一个容易踩死的坑同一目录多次 List 得到的结果顺序可能不完全一样虽然有排序但 OSS 后端是多副本的极端情况下同一批对象两次遍历顺序不同。所以任何时候都不要假设上一次的 continuationToken 可以无限复用到下一个时刻。4.3 全量树内存爆炸的实测对比我在测试环境模拟了三种方案在 50 万对象前缀下的表现方案内存占用构建耗时可扩展性递归分组全量约 580MB8.1 秒弱Trie 前缀树全量约 430MB6.3 秒弱CommonPrefixes 懒加载叶子层单层 5MB请求级强实测里最让我意外的是递归分组比 Trie 占内存多不少原因是每插入一个文件都要创建一棵独立的叶子节点链。Trie 会共享公共前缀路径对高度重复的前缀更省。但用户的真实诉求往往不是全量树而是打开目录看到子项。所以我的最终架构是首次请求返回根目录一层CommonPrefixes 方案点击目录节点后实时请求该目录的子层同时给前端配一个当前层路径面包屑。这样即使桶里有上千万个对象接口响应时间也在百毫秒级内存消耗几乎为 0。4.4 CommonPrefixes 数量与 1000 限制的边界OSS 单次 List 最多返回 1000 条记录包含 CommonPrefixes 与普通对象的总和。这是什么概念如果一个目录下有 600 个子目录和 500 个文件一次 List 就能全部拿到。但如果有 1200 个子目录那么第一次只拿到 1000 个 CommonPrefixes需要第二次 List 才能拿完。很多人以为分页只跟文件数相关其实CommonPrefixes 也计入这 1000 条。所以构建树时分页循环是必须的不能只拉一次就完事。我提供一个可复用的循环模式String nextToken null; do { ListObjectsV2Request req new ListObjectsV2Request(); req.setBucketName(bucket); req.setPrefix(currentPrefix); req.setDelimiter(/); req.setMaxKeys(1000); if (nextToken ! null) { req.setContinuationToken(nextToken); } ListObjectsV2Response resp ossClient.listObjectsV2(req); processCommonPrefixes(resp.getCommonPrefixes()); processObjectSummaries(resp.getObjectSummaries()); nextToken resp.getNextContinuationToken(); } while (nextToken ! null);注意判断循环结束的唯一依据是nextContinuationToken ! null不是isTruncated布尔值虽然二者大多数情况下等价但流式接口里 token 更精准。5. 工具函数库开箱即用的树操作5.1 路径拆分的 3 个边界情况写一个通用工具类把所有兜底逻辑收拢public class OssPathUtils { // 取路径最后一段兼容末尾斜杠 public static String getLastSegment(String path) { if (path null || path.isEmpty()) { return /; } // 去掉末尾斜杠 while (path.endsWith(/)) { path path.substring(0, path.length() - 1); } int idx path.lastIndexOf(/); if (idx 0) { return path; } return path.substring(idx 1); } // 取父路径 public static String getParentPath(String path) { if (path null || path.isEmpty() || /.equals(path)) { return null; } while (path.endsWith(/)) { path path.substring(0, path.length() - 1); } int idx path.lastIndexOf(/); if (idx 0) { return null; } return path.substring(0, idx 1); } // 按分隔符拆段忽略中间空段 public static ListString splitPath(String path) { ListString segments new ArrayList(); if (path null || path.isEmpty()) { return segments; } for (String seg : path.split(/)) { if (seg ! null !seg.isEmpty()) { segments.add(seg); } } return segments; } }三个函数各管一个典型场景getLastSegment把photos/2023/01/变成01getParentPath把photos/2023/01/变成photos/2023/splitPath把photos//2023/01/变成[photos, 2023, 01]中间的空串被忽略。这些工具函数建议在项目一开始就沉淀后面接其它云厂商比如兼容 S3 协议的存储还能复用同一套逻辑。5.2 树节点的 JSON 输出格式前端收到树形 JSON 时最好是已经排好序、字段精简的格式{ name: root, isDir: true, children: [ { name: photos, fullPath: photos/, isDir: true, children: [ { name: 2023, fullPath: photos/2023/, isDir: true, children: [ { name: IMG_001.jpg, fullPath: photos/2023/IMG_001.jpg, isDir: false, size: 20480, lastModified: 2024-03-15T10:30:00Z } ] } ] } ] }前端组件不管你是 react、vue 还是小程序拿到这种结构基本上零成本渲染。有两点值得注意不输出的字段就别塞进 JSON。比如 etag一般只在文件详情页用到如果塞进树节点50 万个文件会多出 500 万个 string 引用网络传输也多出大量冗余字节。前端懒加载场景下children可以初始为空数组前端判断isDir children.length 0就渲染一个展开时请求的交互。5.3 稳定高效的目录层级去重当同一个目录被多条路径收敛时比如photos/2023/同时出现在photos/2023/01/a.jpg和photos/2023/02/b.jpg中树里可能出现重复子树的隐患。一个最稳妥的方案是在插入节点前维护一个全局的路径到节点的 HashMap。MapString, TreeNode pathToNode new HashMap(); public TreeNode getOrCreateNode(String fullPath, boolean isDir) { TreeNode node pathToNode.get(fullPath); if (node ! null) { return node; } node new TreeNode(); node.setFullPath(fullPath); node.setName(getLastSegment(fullPath)); node.setDir(isDir); // 设置父节点关联 String parentPath getParentPath(fullPath); TreeNode parent getOrCreateNode(parentPath ! null ? parentPath : , true); parent.getChildren().add(node); pathToNode.put(fullPath, node); return node; }验证时注意两点如果两个节点的 fullPath 相同但大小写不同OSS 是大小写敏感的不能合并如果业务允许目录和文件同名比如a/b/目录和a/b文件并存需要额外用类型区分 key否则会互相覆盖。这种数据在对象存储里是合法的但在文件系统里不可能出现不处理会搅乱树。6. 性能优化与接口演进6.1 缓存策略对象存储的数据是最终一致的业务端加缓存需要接受这个前提。我的实际做法根目录层变化不频繁的目录结构缓存 30 秒具体文件列表缓存 10 秒对立即生效要求高的场景比如刚上传的文件必须立刻出现在列表里缓存统一设在 5 秒以内。因为 OSS List 接口默认是强一致读在新版 OSS 已支持强一致所以只要请求发出就能拿到最新数据。缓存反而要小心导致刚传的文件不出现的诡异 bug。我个人强烈建议生产环境缓存层只在目录 5000 个时启用小规模不缓存否则你会在改了 OSS 文件但列表不变的工单里消耗大量精力。6.2 异步预取与增量构建如果目录树要用于文件管理器式的产品可以考虑异步预取用户登录后后台异步把一级目录 List 一遍并缓存用户点击某个目录时如果缓存命中秒开如果没命中实时请求并同步写入缓存对高频目录比如最近打开做 LRU 淘汰。这种方式下树的构建被分摊到了每次用户交互而不是集中在启动时。好处是峰值内存低坏处是需要额外处理缓存项失效的问题。增量构建的思路是每次 List 完成后只把新增的CommonPrefixes合并到已有的树里不重建整棵树。配合 OSS 的事件通知甚至可以在有新文件上传时增量刷新某个目录节点。6.3 大规模场景下的替代方案如果对象数量达到亿级别甩开内存里建树的执念转为数据库存储目录元数据是更合理的选择。常见组合对象上传时通过服务侧把 key 解析出的层级结构写入数据库如关系型库或图数据库查询目录树时直接查数据库OSS 只作为文件内容存取层定期比如每小时做一次全量扫描修正目录结构。这种方案的收益是查询速度从调用 OSS List 的几百毫秒下降到数据库索引命中的几十毫秒树形结构可以支持更深度的功能权限、收藏、搜索。代价是引入额外的存储成本和同步逻辑。对于目录树即管理后台的轻量场景还是直接用 OSS List 树构建最省事。7. 一个完整的实战案例复盘最后分享一个我在模拟项目中的完整落地过程便于你把前面内容串起来。需求是某个素材管理后台用户上传素材按素材类型/年份/月份/文件分目录存储。需要左侧显示目录树右侧显示当前目录下的文件列表。文件量级约 60 万目录节点约 2000 个。我当时的设计是这样的前端首次加载请求/api/dirs?prefix素材类型/接口后端执行一次 List返回全部一级子目录和文件用户点击任意目录节点再请求该目录的子内容后端实时执行一次 List返回子项每个列表接口内部都做了完整的分页循环最多拉取 1000 条超过部分前端滚动加载目录节点的排序统一目录优先、文件按名称升序缓存了根目录层 30 秒避免每次进页面都打 OSS。写完后做了压力测试60 万对象下根目录列表接口 P95 在 180ms 内点击任意二级目录接口 P95 在 220ms 内内存占用单实例稳定在 200MB 以下主要被缓存和请求对象占用。在整个开发过程中最花时间的是两件事一是分页循环的边界。当某目录下子目录恰好 1000 个时List 第一次返回 1000 个 CommonPrefixesNextContinuationToken为空容易误以为没有更多数据实际第二次 List 才能拿到第 1001~2000 个。正确做法是完全依赖 token 判断。二是目录与文件的同名互斥。因为 OSS 里photos/2023/和photos/2023可以并存业务上又允许上传一个不带扩展名、名字刚好是 2023 的文件导致树里出现了两个2023节点。最后的处理是在构建节点时给每个节点增加一个type字段目录/文件并禁止在同一父节点下出现同名但不同类型的节点直接以后者覆盖前者并打印告警日志。现在回看整个方案我认为最关键的决策不是选了哪种树构建算法而是明确了树的构建必须按需进行。OSS 是海量对象存储灌进内存建立全量树是违背它设计哲学的错误姿势。当你把一次性构建完整树这个执念放下很多看似复杂的性能和内存问题都会瞬间消失。