SuperAPI AI 工具集

data-client-v0.18-migration

编程与开发

查看项目

更新于 10-16 07:26

技能介绍

用途:把使用 @data-client 的项目迁移到 v0.18 的 delegate 签名。适用于自定义 Schema 的实现者,包括 SchemaSimple、SchemaClass、多态包装器,以及直接继承 EntityMixin 的类型;内置 schema(Entity、resource()、Collection、Union、Values、Array、Object、Query、Invalidate、Lazy)由库自行迁移。

主要变化:Schema.denormalize 与 Schema.normalize 改为接收单个 delegate,取代原来的 (args, unvisit) 和 (args, visit, delegate)。关键语义变化是读取 delegate.args 不再参与缓存失效,输出随 endpoint 参数变化的 schema 必须通过 delegate.argsKey(fn) 注册依赖,且 fn 需引用稳定(绑定在实例或模块作用域,内联箭头函数会每次生成新引用导致缓存失效)。

使用方式:先做预检查,在仓库根目录运行 rg 或 grep 搜索 extends Schema/SchemaSimple/SchemaClass/EntityMixin、normalize/denormalize、unvisit、visit 等模式;若无结果则无需改动,仅升级版本。否则先提交代码,再对源码根目录运行 codemod:npx jscodeshift -t https://dataclient.io/codemods/v0.18.js --extensions=ts,tsx,js,jsx <source-root>。注意不要指向仓库根目录,jscodeshift 不遵守 .gitignore 会进入 node_modules。

codemod 无法自动处理、需手工迁移的情况:没有 @data-client/* 导入的文件;类字段形式的 denormalize;const denormalize = function... 形式;计算或动态方法键;接口中名为 _denormalize/_denormalizeNullable 的 TSMethodSignature;包装 (args, unvisit) 的自定义辅助函数。Vue/Svelte/Astro/MDX 单文件组件无法被 tsx 解析器处理,建议先抽出为 .ts 或手工迁移。

验证:运行类型检查器,残留的 unvisit、visit、args 或 delegate 参数数量错误指向遗漏处;运行测试套件,参数变化时出现陈旧的反规范化值通常意味着缺少 argsKey;再 grep 检查残留的三参数 denormalize、裸 unvisit/visit 调用和 ...args 展开。

限制:argsKey 注册不可自动化;codemod 干净运行显示 0 errors、N unmodified、0 skipped 属正常。可选内容:v0.18 允许单个 Collection 同时携带 argsKey 和 nestKey。