SuperAPI AI 工具集

adding-deprecation-warnings

编程与开发

查看项目

更新于 10-15 20:14

技能介绍

用途:当属性或 API 被重命名、或被移除但需要过渡期时,为其添加向后兼容的弃用警告,在保留兼容性的同时推动迁移。适用于自定义节点仍使用旧名称的场景。

主要能力与用法:先评估影响,使用 comfy_codesearch 工具搜索旧属性名,同时搜索 widget.oldProp 和 oldProp 以覆盖各种模式,并记录访问方式(属性访问、真值判断、缓存到局部变量、样式修改等),这些都必须继续可用。随后从 src/lib/litegraph/src/utils/feedback.ts 引入 defineDeprecatedProperty 并调用,示例:import { defineDeprecatedProperty } from '@/lib/litegraph/src/utils/feedback';defineDeprecatedProperty(obj, 'oldProp', 'newProp', 'obj.oldProp is deprecated. Use obj.newProp instead.')。需在新属性赋值之后调用,并在调用上方添加 JSDoc @deprecated 标签以支持 IDE。

检查清单:完成生态搜索且所有使用模式兼容;添加 defineDeprecatedProperty 调用;添加 JSDoc 标签;警告信息明确写出新旧属性名;pnpm typecheck 与 pnpm lint 通过。PR 中需评论说明生态搜索结果:哪些仓库使用该弃用属性、发现的访问模式,以及确认所有模式与 ODP 的 getter/setter 兼容。

工作原理:在目标对象上创建 Object.defineProperty getter/setter;getter 返回 this[currentKey],setter 赋值给 this[currentKey];两者通过 warnDeprecated 记录,且按唯一消息去重(每会话一次,基于 Set);enumerable: false 使别名不出现在 Object.keys()、for...in 或 JSON.stringify 中;configurable: true 允许再次重定义。

边界情况:真值判断、缓存到局部变量、样式/属性修改均可正常工作;序列化会被 enumerable: false 排除;循环中大量访问由 warnDeprecated 去重,每会话仅警告一次。