恒美微站
首页
关于我们
建站服务
主题模板
案例展示
资讯中心
联系我们
Puter.js `puter.kv.expireAt()` 深度指南:为键设置绝对过期时间戳
首页
资讯中心
/
Puter.js `puter.kv.expireAt()` 深度指南:为键设置绝对过期时间戳
Puter.js `puter.kv.expireAt()` 深度指南:为键设置绝对过期时间戳
发布时间:2026/9/9 20:29:32
Puter.jsputer.kv.expireAt()深度指南为键设置绝对过期时间戳【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.kv.expireAt()是 Puter 云键值存储Key-Value StoreAPI 中用于按绝对 Unix 时间戳控制键生命周期的核心方法适用于 Web 网站、App、Node.js 及 Serverless Worker 等多种平台场景。通过本文你将掌握expireAt的完整语法、参数语义与返回约定理解它与相对 TTL 的expire()在实现上的关键差异并学会用它构建定时失效的缓存、临时凭证与限时数据等真实场景。背景一个托管于用户账户的键值存储在深入expireAt之前先厘清它的运行环境。Puter 的 KV Store 允许应用以键值对的形式在云端存取数据其基础设施完全由 Puter 托管开发者无需自建服务器、无需关心扩容与备份。关键特性在于隔离边界KV 模块索引说明 明确指出每个应用在每位用户的账户内拥有自己独立的存储应用之间无法访问彼此的存储。因此puter.kv.expireAt()操作的对象始终是当前用户自己账户内、当前应用命名空间下的键单靠 KV API 无法跨用户读取数据。若需要所有用户共享的集中式存储官方 KV 概览建议改用 Serverless Worker由 Worker 代码代表其所有者访问资源。此外借助appUuid配置项配合puter.perms.requestAppData()权限也可以让一个应用寻址另一个应用的命名空间见 types.js 中KVOptConfig的定义。方法与函数签名根据原文档方法签名只有一个puter.kv.expireAt(key, timestampSeconds)将过期语义对照到 SDK 实现会得到一个重要的设计提示。expireAt.js 的实现注释写道Sets the expiration for a key as a UNIX timestamp in seconds; after that time the key is deleted.Clients whose clock is out of sync with the server may see keys expire early or late — preferexpirefor a server-relative TTL.即expireAt用一个绝对时间点定义何时删除该键由于该时间点由客户端时钟换算而来一旦客户端设备与服务器之间存在时钟偏差键就可能提前或滞后过期。这正是它与expire()相对 TTL以服务器时间为基准计算的本质区别下文会专门展开。与expire()的关系KV Store 同时提供两种过期 API二者的关系可以概括为同一底层机制的两种取值方式方法语义参数适用场景puter.kv.expire(key, ttlSeconds)相对 TTL从现在起 N 秒后删除秒数服务端计时无需关心客户端时钟puter.kv.expireAt(key, timestampSeconds)绝对时间戳在指定 Unix 时刻删除Unix 秒级时间戳存在一个墙上时间业务约定如某日 0 点失效时二者在 SDK 层几乎是镜像实现expire.js 通过makeDriverMethod({ iface: puter-kvstore, method: expire, argNames: [key, ttl] })调用后端驱动而 expireAt.js 以method: expireAt、argNames: [key, timestamp]调用同一puter-kvstore接口。JSDoc 中的原始描述则互为建议expire的注释expire.js提醒当时间戳应由服务端决定时优先使用expire以避免时钟漂移问题。对于expire()官方文档KV/expire.md同样定义了expire(key, ttlSeconds)形式两者均返回一个 resolve 为true的Promise表示过期设定已生效。参数详解expireAt接收两个必填位置参数SDK 层还会在请求发出前做一次键名校验。keyString必填包含目标键名的字符串。在 expireAt.js 中参数首先经过assertKeySize(key)校验若键长度超过1 KB1024 字节会抛出带有稳定错误码key_too_large的{ message, code }对象见 lib/validate.js。键名在调用真正发出前即被拒绝因此无需等待网络往返即可捕获这类低级错误。同时set()文档KV/set.md明确 key 为空undefined/null会由assertKeyPresent抛出key_undefined错误。timestampSecondsNumber必填键将被从存储中移除的 Unix 时间戳秒级。这是本方法与expire()的核心差异点这里传的不是从现在起的秒数而是一个绝对时间点。实践中通常用Date.now()/1000 offsetSeconds计算得到原文档示例即采用(Date.now()/1000) 1。需要注意若该值已经位于过去则键的过期行为由后端对该时间点的判断决定——按文档语义到达该时刻键即被删除因此传入过去的时间戳可视为要求立即失效。返回值返回一个Promise当过期时间被成功设定时Promise resolve 为布尔值true该 Promise 仅在服务端确认设定成功后 resolve配合await使用可保证后续逻辑发生在设定生效之后。平台支持原文档 front matter 标注的platforms为[websites, apps, nodejs, workers]即以下四种运行形态均可直接调用websites通过script srchttps://js.puter.com/v2//script引入浏览器端 SDK 的网页appsPuter 生态内的应用nodejsNode.js 环境SDK 的 Node 入口workersPuter 的 Serverless Worker 运行时。此外puter.kv.expireAt与其它方法一样由 KVModule 在构造时以bind重绑为模块方法因此无论puter.kv.expireAt(...)整体调用还是先解构出const { expireAt } puter.kv再单独调用语义保持一致。完整示例读取一个已到期的键原文档给出的示例演示了创建 → 设定绝对过期时刻 → 等待后读取为空的完整闭环直接可复制到浏览器控制台或网页运行html body script srchttps://js.puter.com/v2//script script (async () { // (1) Create a new key-value pair await puter.kv.set(name, Puter Smith); puter.print(Key-value pair name created/updatedbr); // (2) Set key to expire in 1 second await puter.kv.expireAt(name, (Date.now()/1000) 1); // (3) Wait 2 seconds and get the value setTimeout(async () { const name await puter.kv.get(name); puter.print(Value :, name); }, 2000); })(); /script /body /html分步解读puter.kv.set(name, Puter Smith)写入键值对并await其完成puter.kv.expireAt(name, (Date.now()/1000) 1)把过期时刻设定为当前 Unix 秒 1 秒。Date.now()返回毫秒因此必须除以 1000 换算为秒后才能与 API 的秒级约定匹配这是最常见的笔误点等待 2 秒后调用puter.kv.get(name)此时过期窗口1 秒已过读取结果应为空null。数值约定提示与过期时间戳不同写入 KV 的值遵循set()文档KV/set.md中的精度规则每个数字包括嵌套在对象或数组中的必须在Number.MAX_SAFE_INTEGER±9,007,199,254,740,991范围内超出部分会被钳制而非拒绝NaN则以null存储。需要精确保存的 ID 或累计值请以字符串形式存储。expireAt 与 expire 的选型建议结合两个方法的 SDK 实现注释expireAt.js、expire.js与官方文档给出可落地的选型准则服务端负责计时当语义是从现在起 60 秒后失效优先选择puter.kv.expire(key, 60)。TTL 由服务器解释不受客户端设备时钟偏差影响是防止用户把系统时间调前/调后导致缓存提前/延后失效的首选。业务有绝对截止点当失效时刻必须锚定在业务约定的墙上时间——例如会话在当天 23:59:59 作废限时优惠到某日结束临时访问令牌在固定时刻回收——用expireAt更自然也便于直接与后端计算出的截止时间戳对接。注意时钟一致性问题expireAt的timestampSeconds来自客户端本地时钟换算一旦客户端时钟与服务端偏差明显键的实际删除可能早于或晚于预期。若你的业务对时间误差敏感请优先评估expire方案若必须使用绝对时间戳可考虑在服务端/Worker 侧计算时间戳后传入让计时基准尽量靠近服务端。两个方法都先经assertKeySize做键长校验再经puter-kvstore接口发往后端 KV 驱动见 expireAt.js整体行为一致差异仅在时间取值语义。扩展应用把过期时间戳带进set()值得留意的是绝对过期时间并非只能事后调用expireAt。SDK 的puter.kv.set()本身就支持内联的expireAt字段且该参数在后端与独立调用的expireAt语义一致见 KVSetItem 的类型注释Timestamp, in seconds, at which the key should expire。例如// 写入时即声明该键于 1 小时后失效 await puter.kv.set(sessionToken, abc123, (Date.now() / 1000) 3600); // 对象形式亦可详见 set 文档的多种重载 await puter.kv.set({ key: otp, value: 483920, expireAt: (Date.now() / 1000) 300 });批量形式puter.kv.set([{ key, value, expireAt }, ...])同样允许逐条携带过期时间。这样可以在单次写入请求内完成数据 生命周期的原子设定减少一次额外的过期调用也让一次性数据的意图在代码中自解释。典型实战场景综合官方 KV 概览KV.md与本文方法语义expireAt在真实业务中适合支撑以下能力带截止时刻的缓存缓存某个到整点就必须失效的数据如汇率快照、当日排行榜用expireAt(key, nextHourTimestamp)精确对齐刷新边界限时内容与临时凭据一次性链接、OTP、临时 token 等在业务上到点必须作废的条目临时状态位如该用户 24 小时内不再提示之类的标记配合incr/decr构成带有生命周期的计数逻辑与disableSharing组合的隐私条目用set(key, value, { disableSharing: true, expireAt })写一条既私有又按时销毁的数据如缓存中的访问令牌即便用户之后授权其它应用访问本命名空间该条目也对其不可见见 KV/set.md 的disableSharing说明。总结puter.kv.expireAt(key, timestampSeconds)用最直接的方式为键挂上墙上时钟型的生命周期传入 Unix 秒级时间戳到点即删成功即返回true。它与相对 TTL 的puter.kv.expire()形成互补前者适合锚定业务截止时刻后者适合规避客户端时钟漂移。若要深入理解其底层可以沿着这条路径继续阅读当前仓库SDK 实现 expireAt.js参数校验与驱动方法封装SDK 实现 expire.js相对 TTL 的镜像实现KV 模块聚合 index.js模块结构、方法绑定与MAX_KEY_SIZE/MAX_VALUE_SIZE常量客户端校验 lib/validate.jskey_too_large、value_too_large等稳定错误码类型与选项 types.jsexpireAt在各批量接口中的内联形态官方文档 KV/expire.md 与 KV/set.md相邻 API 的完整语法与限制key ≤ 1 KB、value ≤ 400 KB。至此你可以直接在自己的页面、Node 脚本或 Worker 中按上文示例落地定时过期的数据管理并依据时钟敏感度在expire与expireAt之间做出正确取舍。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考