 完全指南：目录列举、分页遍历与递归读取)
Puter 云端文件系统 readdir() 完全指南目录列举、分页遍历与递归读取【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.fs.readdir()是 Puter 云端文件系统Cloud Storage中用于列出目录内容的核心 API支持按路径或 UID 定位目录、按字段排序、递归列出子目录并提供基于cursor的分页与流式遍历能力。本指南围绕 readdir 官方文档 展开结合 puter-js SDK 在 operations/readdir.js 中的真实实现帮助你在网站、App、Node.js 与 Workers 四种平台上正确、高效地使用目录列举能力并理解其在客户端的分页抓取、缓存与去重机制。一、方法总览与调用形式puter.fs.readdir()读取指定目录的内容返回其中所有条目文件和子目录的数组。该 API 由 puter-js 的 FileSystem 模块 提供支持下述三种调用形式puter.fs.readdir(path) puter.fs.readdir(path, options) puter.fs.readdir(options)当path作为第一个字符串参数传入时它是一个位置参数当仅传入一个对象时目录目标必须写在对象的path或uid字段里SDK 还兼容旧式的成功/失败回调形式readdir(path, successCallback, errorCallback)回调与 Promise 会同时生效参见 scaffold.js 中的参数归一化逻辑以及 operations.test.js 对裸回调的测试。该 API 适用于文档 frontmatter 声明的全部平台websites网页、apps、nodejs与workers。二、参数详解pathString要读取的目录路径。如果path不是绝对路径则相对于应用的根目录进行解析。在 SDK 实现中相对路径会经过 getAbsolutePathForApp 归一化为绝对路径后再随请求发送因此readdir(./)等价于列出应用根目录。若省略path则必须提供uid否则请求会被拒绝。optionsObject可选options 对象支持以下属性与 types.js 中 ReaddirOptionsOwn 定义 一一对应属性类型说明pathString要读取的目录路径。仅以 options 对象作为唯一参数时必须提供。uidString可选要读取目录的 UID可替代path使用。limitNumber可选返回条目的最大数量。offsetNumber可选跳过指定数量的条目。遍历大目录时推荐优先使用cursor。sortByString可选排序字段name、modified、type或size默认name。sortOrderString可选asc或desc默认asc。recursiveBoolean可选为true时同时列出子目录中的内容默认false。depthNumber可选当recursive为true时向下递归的层数默认不限深度。cursorString | null可选启用分页结果。首屏传null之后把上一页返回的cursor传入即可获取下一页。cursor 会固定排序方式后续页不得再请求不同的sortBy/sortOrder。includeTotalBoolean可选为true时分页结果会携带该目录全部条目的total总数。streamBoolean可选为true时方法不再返回 Promise而是返回页面对象的异步迭代器用于for await ... of。可与limit结合控制页大小或用cursor从上一页断点续读不能与offset组合。开启includeTotal时仅第一页携带total。除上述字段外SDK 的 types 定义还额外暴露no_thumbs、no_assocs、consistency三个请求控制项见 types.jsno_thumbs/no_assocs用于关闭缩略图与关联应用信息的附带返回consistency可取strong默认强制走后端最新数据或eventual允许命中本地缓存见下文缓存机制。三、返回值详解默认形态FSItem 数组不带任何分页参数时方法返回一个解析为FSItem对象数组的Promise。FSItem表示 Puter 文件系统中的单个文件或目录包含id、uid、name、path、dirname、is_dir、type、size、created、modified等字段。每个条目上的is_shared字段含义为true该条目已与他人共享false未共享null该条目不属于你例如别人分享给你的内容。需要注意它只统计条目自身上的共享关系——你共享了一个文件夹则该文件夹的子项会报告false因为共享关系是挂在该文件夹上的。要查看某个条目可被哪些人访问包括继承自父目录的访问权限请对该条目调用getShares()。分页形态页面对象当请求中带有cursor即使是null或includeTotal时Promise 解析为如下页面对象envelopeitemsArray本页的FSItem对象cursorString可选只要还存在更多页就会出现把它传给下一次调用即可取下一页totalNumber可选目录中条目总数仅在设置了includeTotal时出现。不带分页参数的请求仍然以普通数组形式返回完整列表旧代码行为不受影响——SDK 在内部实际上会逐页抓取后再拼接成完整数组返回。流式形态异步迭代器设置stream: true后方法返回页面对象的异步迭代器配合for await ... of逐页消费适合超大目录的场景for await (const page of puter.fs.readdir({ path: ./large-dir, stream: true })) { for (const item of page.items) { console.log(item.name); } }页面对象的停止信号是cursor缺失因此不要用items.length limit判断列表是否结束——部分后端在权限过滤等场景下可能返回短页甚至空页却仍带cursor详见仓库中的分页约定文档 pagination.md。四、完整可运行示例示例一读取一个目录并打印条目路径html body script srchttps://js.puter.com/v2//script script puter.fs.readdir(./).then((items) { // print the path of each item in the directory puter.print(Items in the directory:br${items.map((item) item.path)}br); }).catch((error) { puter.print(Error reading directory: ${error}); }); /script /body /html示例二限定数量、指定排序// 按修改时间倒序只取前 10 个条目 const items await puter.fs.readdir(/photos, { limit: 10, sortBy: modified, sortOrder: desc, });该调用会原样把limit、sortBy、sortOrder写入请求体在 operations/readdir.js 与对应测试 operations.test.js 中均可验证。示例三递归列出子目录限制深度// 递归两层列出 /docs 下所有子目录的内容 const all await puter.fs.readdir(/docs, { recursive: true, depth: 2, }); console.log(all.length, entries found recursively);注意递归列表在客户端不会被缓存它可能与直接列表的缓存键冲突见 readdir.js 的实现注释频繁全量递归请自行控制调用频率。示例四用 cursor 手动逐页翻取let cursor null; // null 请求第一页 do { const page await puter.fs.readdir(./large-dir, { cursor, limit: 100, includeTotal: true, }); console.log(Page with ${page.items.length} items; total ${page.total}); for (const item of page.items) { // 处理每个条目 } cursor page.cursor; // 没有更多页时 cursor 为 undefined循环结束 } while (cursor);分页时的排序约束很严格cursor 会固定排序方式一旦某页基于sortBy: name发起后续页必须沿用同一组sortBy/sortOrder否则后端无法保证游标语义一致。示例五按 UID 读取目录当你知道目录的 UID例如来自stat()或一次readdir的结果时可以跳过路径解析直接用 UID 定位适合目录被移动、路径变化的场景const items await puter.fs.readdir({ uid: d3f1a9c2-… });path与uid二选一两者都不提供时SDK 会直接抛出{ code: NO_PATH_OR_UID, message: Either path or uid must be provided. }见 operations.test.js 对该错误路径的测试。五、源码级原理一次 readdir 请求发生了什么理解背后的实现能帮你更好地把握性能与一致性行为。客户端逻辑集中在 operations/readdir.js核心流程如下1. 单页请求requestOnce所有形态最终都收敛到requestOnce它向后端/fs/readdir端点发起一次 HTTP 请求limit、offset、sortBy、sortOrder、recursive、depth在声明时写入请求体存在分页参数时追加cursor默认为null与includeTotal认证令牌放在请求体内的auth_token字段而非 Authorization 头authHeader: false后端 v2 路由返回camelCase条目客户端统一经过 mapV2EntryToV1.js 归一化为 v1 的 snake_case 形态uuid→uid、isDir→is_dir、isShared→is_shared等保证老调用方看到的返回结构完全不变——这一点由 operations.test.js 明确验证每个返回条目还会被写入客户端的item:前缀缓存便于后续按路径直接命中。2. 全量列表内部逐页抓取当调用不带任何分页参数即unbound时SDK 并没有向后端要一个超大响应而是用 lib/pagination.js 的fetchAllPages以cursor逐页抓取最后把所有页的items拼接成传统数组返回。这正是原文档所说“旧代码返回完整数组、底层已分页抓取”的落点。拼接结果若序列化后不超过100 MBMAX_CACHE_SIZE才会被缓存。3. 流式迭代iteratePagesstream: true走的是同一份分页逻辑的异步生成器版本iteratePages首屏携带{ cursor: null, includeTotal }此后每次只把上一页返回的cursor传给下一页直到响应不再携带cursor。流式形态不做缓存也不做请求去重——生成器无法在多个消费者之间共享。若同时传了offsetSDK 会抛出{ code: invalid_request, message: ... }因为偏移量无法在游标遍历中表达。4. 一致性、缓存与请求去重默认强一致readdirPaged在未指定consistency时默认设为strong请求直达后端最新数据eventual一致性仅在缓存键存在即“不带分页参数 非递归 给了 path”时生效命中则直接返回缓存结果不发网络请求。相关测试 operations.test.js 演示了第二次eventual调用零请求请求去重相同参数path/uid/排序/分页等同时发出的请求会共享同一次后端调用dedupe避免并发重复拉取缓存失效FileSystem 模块在 index.js 中通过 socket 监听item.added、item.removed、item.renamed、item.updated、item.moved等事件新增文件时会精确删除其父目录的readdir:parent缓存键其它结构性变更则直接flushall()清空本地缓存从而保证 GUI 等长生命周期环境中列表数据的正确刷新。六、常见错误与注意事项场景正确做法目录不存在或无权限捕获 Promise rejection错误消息会由后端返回可展示给用户既没给path也没给uid抛出NO_PATH_OR_UID属于编程错误应在调用前校验stream与offset混用非法组合抛invalid_request续读请用cursor大目录逐页翻取用cursor而非offsetoffset是旧式能力官方明确推荐前者分页过程中改变排序不允许——cursor 已固定sortBy/sortOrder必须保持一致依赖items.length limit判断结尾不可靠——短页不代表结束应以cursor是否存在为准七、延伸阅读FSItem 对象readdir()返回条目中每个字段含is_shared的完整说明stat()读取单个目录/文件的元数据getShares()查看某个条目上的共享关系listShared() 与 listSharedByMe()从共享视角列举条目分页约定文档 pagination.md所有列表类 API 共享的{ items, cursor?, total? }信封契约与向后兼容规则puter-js SDK 测试集 operations.test.js包含 readdir 全部调用形态的 Mock 测试示例可作为你接入行为的参考基线。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puter 云端文件系统 readdir() 完全指南：目录列举、分页遍历与递归读取
Puter 云端文件系统 readdir() 完全指南目录列举、分页遍历与递归读取【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.fs.readdir()是 Puter 云端文件系统Cloud Storage中用于列出目录内容的核心 API支持按路径或 UID 定位目录、按字段排序、递归列出子目录并提供基于cursor的分页与流式遍历能力。本指南围绕 readdir 官方文档 展开结合 puter-js SDK 在 operations/readdir.js 中的真实实现帮助你在网站、App、Node.js 与 Workers 四种平台上正确、高效地使用目录列举能力并理解其在客户端的分页抓取、缓存与去重机制。一、方法总览与调用形式puter.fs.readdir()读取指定目录的内容返回其中所有条目文件和子目录的数组。该 API 由 puter-js 的 FileSystem 模块 提供支持下述三种调用形式puter.fs.readdir(path) puter.fs.readdir(path, options) puter.fs.readdir(options)当path作为第一个字符串参数传入时它是一个位置参数当仅传入一个对象时目录目标必须写在对象的path或uid字段里SDK 还兼容旧式的成功/失败回调形式readdir(path, successCallback, errorCallback)回调与 Promise 会同时生效参见 scaffold.js 中的参数归一化逻辑以及 operations.test.js 对裸回调的测试。该 API 适用于文档 frontmatter 声明的全部平台websites网页、apps、nodejs与workers。二、参数详解pathString要读取的目录路径。如果path不是绝对路径则相对于应用的根目录进行解析。在 SDK 实现中相对路径会经过 getAbsolutePathForApp 归一化为绝对路径后再随请求发送因此readdir(./)等价于列出应用根目录。若省略path则必须提供uid否则请求会被拒绝。optionsObject可选options 对象支持以下属性与 types.js 中 ReaddirOptionsOwn 定义 一一对应属性类型说明pathString要读取的目录路径。仅以 options 对象作为唯一参数时必须提供。uidString可选要读取目录的 UID可替代path使用。limitNumber可选返回条目的最大数量。offsetNumber可选跳过指定数量的条目。遍历大目录时推荐优先使用cursor。sortByString可选排序字段name、modified、type或size默认name。sortOrderString可选asc或desc默认asc。recursiveBoolean可选为true时同时列出子目录中的内容默认false。depthNumber可选当recursive为true时向下递归的层数默认不限深度。cursorString | null可选启用分页结果。首屏传null之后把上一页返回的cursor传入即可获取下一页。cursor 会固定排序方式后续页不得再请求不同的sortBy/sortOrder。includeTotalBoolean可选为true时分页结果会携带该目录全部条目的total总数。streamBoolean可选为true时方法不再返回 Promise而是返回页面对象的异步迭代器用于for await ... of。可与limit结合控制页大小或用cursor从上一页断点续读不能与offset组合。开启includeTotal时仅第一页携带total。除上述字段外SDK 的 types 定义还额外暴露no_thumbs、no_assocs、consistency三个请求控制项见 types.jsno_thumbs/no_assocs用于关闭缩略图与关联应用信息的附带返回consistency可取strong默认强制走后端最新数据或eventual允许命中本地缓存见下文缓存机制。三、返回值详解默认形态FSItem 数组不带任何分页参数时方法返回一个解析为FSItem对象数组的Promise。FSItem表示 Puter 文件系统中的单个文件或目录包含id、uid、name、path、dirname、is_dir、type、size、created、modified等字段。每个条目上的is_shared字段含义为true该条目已与他人共享false未共享null该条目不属于你例如别人分享给你的内容。需要注意它只统计条目自身上的共享关系——你共享了一个文件夹则该文件夹的子项会报告false因为共享关系是挂在该文件夹上的。要查看某个条目可被哪些人访问包括继承自父目录的访问权限请对该条目调用getShares()。分页形态页面对象当请求中带有cursor即使是null或includeTotal时Promise 解析为如下页面对象envelopeitemsArray本页的FSItem对象cursorString可选只要还存在更多页就会出现把它传给下一次调用即可取下一页totalNumber可选目录中条目总数仅在设置了includeTotal时出现。不带分页参数的请求仍然以普通数组形式返回完整列表旧代码行为不受影响——SDK 在内部实际上会逐页抓取后再拼接成完整数组返回。流式形态异步迭代器设置stream: true后方法返回页面对象的异步迭代器配合for await ... of逐页消费适合超大目录的场景for await (const page of puter.fs.readdir({ path: ./large-dir, stream: true })) { for (const item of page.items) { console.log(item.name); } }页面对象的停止信号是cursor缺失因此不要用items.length limit判断列表是否结束——部分后端在权限过滤等场景下可能返回短页甚至空页却仍带cursor详见仓库中的分页约定文档 pagination.md。四、完整可运行示例示例一读取一个目录并打印条目路径html body script srchttps://js.puter.com/v2//script script puter.fs.readdir(./).then((items) { // print the path of each item in the directory puter.print(Items in the directory:br${items.map((item) item.path)}br); }).catch((error) { puter.print(Error reading directory: ${error}); }); /script /body /html示例二限定数量、指定排序// 按修改时间倒序只取前 10 个条目 const items await puter.fs.readdir(/photos, { limit: 10, sortBy: modified, sortOrder: desc, });该调用会原样把limit、sortBy、sortOrder写入请求体在 operations/readdir.js 与对应测试 operations.test.js 中均可验证。示例三递归列出子目录限制深度// 递归两层列出 /docs 下所有子目录的内容 const all await puter.fs.readdir(/docs, { recursive: true, depth: 2, }); console.log(all.length, entries found recursively);注意递归列表在客户端不会被缓存它可能与直接列表的缓存键冲突见 readdir.js 的实现注释频繁全量递归请自行控制调用频率。示例四用 cursor 手动逐页翻取let cursor null; // null 请求第一页 do { const page await puter.fs.readdir(./large-dir, { cursor, limit: 100, includeTotal: true, }); console.log(Page with ${page.items.length} items; total ${page.total}); for (const item of page.items) { // 处理每个条目 } cursor page.cursor; // 没有更多页时 cursor 为 undefined循环结束 } while (cursor);分页时的排序约束很严格cursor 会固定排序方式一旦某页基于sortBy: name发起后续页必须沿用同一组sortBy/sortOrder否则后端无法保证游标语义一致。示例五按 UID 读取目录当你知道目录的 UID例如来自stat()或一次readdir的结果时可以跳过路径解析直接用 UID 定位适合目录被移动、路径变化的场景const items await puter.fs.readdir({ uid: d3f1a9c2-… });path与uid二选一两者都不提供时SDK 会直接抛出{ code: NO_PATH_OR_UID, message: Either path or uid must be provided. }见 operations.test.js 对该错误路径的测试。五、源码级原理一次 readdir 请求发生了什么理解背后的实现能帮你更好地把握性能与一致性行为。客户端逻辑集中在 operations/readdir.js核心流程如下1. 单页请求requestOnce所有形态最终都收敛到requestOnce它向后端/fs/readdir端点发起一次 HTTP 请求limit、offset、sortBy、sortOrder、recursive、depth在声明时写入请求体存在分页参数时追加cursor默认为null与includeTotal认证令牌放在请求体内的auth_token字段而非 Authorization 头authHeader: false后端 v2 路由返回camelCase条目客户端统一经过 mapV2EntryToV1.js 归一化为 v1 的 snake_case 形态uuid→uid、isDir→is_dir、isShared→is_shared等保证老调用方看到的返回结构完全不变——这一点由 operations.test.js 明确验证每个返回条目还会被写入客户端的item:前缀缓存便于后续按路径直接命中。2. 全量列表内部逐页抓取当调用不带任何分页参数即unbound时SDK 并没有向后端要一个超大响应而是用 lib/pagination.js 的fetchAllPages以cursor逐页抓取最后把所有页的items拼接成传统数组返回。这正是原文档所说“旧代码返回完整数组、底层已分页抓取”的落点。拼接结果若序列化后不超过100 MBMAX_CACHE_SIZE才会被缓存。3. 流式迭代iteratePagesstream: true走的是同一份分页逻辑的异步生成器版本iteratePages首屏携带{ cursor: null, includeTotal }此后每次只把上一页返回的cursor传给下一页直到响应不再携带cursor。流式形态不做缓存也不做请求去重——生成器无法在多个消费者之间共享。若同时传了offsetSDK 会抛出{ code: invalid_request, message: ... }因为偏移量无法在游标遍历中表达。4. 一致性、缓存与请求去重默认强一致readdirPaged在未指定consistency时默认设为strong请求直达后端最新数据eventual一致性仅在缓存键存在即“不带分页参数 非递归 给了 path”时生效命中则直接返回缓存结果不发网络请求。相关测试 operations.test.js 演示了第二次eventual调用零请求请求去重相同参数path/uid/排序/分页等同时发出的请求会共享同一次后端调用dedupe避免并发重复拉取缓存失效FileSystem 模块在 index.js 中通过 socket 监听item.added、item.removed、item.renamed、item.updated、item.moved等事件新增文件时会精确删除其父目录的readdir:parent缓存键其它结构性变更则直接flushall()清空本地缓存从而保证 GUI 等长生命周期环境中列表数据的正确刷新。六、常见错误与注意事项场景正确做法目录不存在或无权限捕获 Promise rejection错误消息会由后端返回可展示给用户既没给path也没给uid抛出NO_PATH_OR_UID属于编程错误应在调用前校验stream与offset混用非法组合抛invalid_request续读请用cursor大目录逐页翻取用cursor而非offsetoffset是旧式能力官方明确推荐前者分页过程中改变排序不允许——cursor 已固定sortBy/sortOrder必须保持一致依赖items.length limit判断结尾不可靠——短页不代表结束应以cursor是否存在为准七、延伸阅读FSItem 对象readdir()返回条目中每个字段含is_shared的完整说明stat()读取单个目录/文件的元数据getShares()查看某个条目上的共享关系listShared() 与 listSharedByMe()从共享视角列举条目分页约定文档 pagination.md所有列表类 API 共享的{ items, cursor?, total? }信封契约与向后兼容规则puter-js SDK 测试集 operations.test.js包含 readdir 全部调用形态的 Mock 测试示例可作为你接入行为的参考基线。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
