SuperAPI AI 工具集

zod-migration

编程与开发

查看项目

更新于 10-16 10:11

技能介绍

用途

zod-migration 用于把 CLI for Microsoft 365 的命令从旧版 #initOptions()、#initValidators()、#initTelemetry() 模式迁移到基于 Zod schema 的校验。当命令仍带有这些旧方法,或没有 schema getter、没有导出的 options Zod schema 时,适合使用该技能。

主要流程

迁移前先阅读命令源文件(.ts)及其测试文件(.spec.ts),识别选项、别名、校验器、遥测、选项集和类型,并检查是否有自动补全值,以及表示 GUID 或 UPN 的选项是否接受运行时令牌 @meid 或 @meusername。

迁移步骤如下:

  1. 在命令 .ts 文件中定义 Zod schema,替换导入,并导出 options。
  2. 为类添加 schema getter:public get schema(): z.ZodType | undefined { return options; }。
  3. 删除旧的初始化方法,包括构造函数(若其仅调用初始化方法)、#initOptions()、#initValidators()、#initTelemetry()、#initTypes()、#initOptionSets()。
  4. 对跨字段校验使用 getRefinedSchema(),例如选项集(互斥或“二选一”)、条件必填、set 命令的“至少更新一项”模式。
  5. 把必须保留的校验器(文件系统检查、URL 校验等)移入 .refine(),因为命令定义 schema 后 CLI 不再运行 this.validators。
  6. 对接受未知选项的宽松命令(如 user-set、user-add、groupsetting-set),使用 z.object() 配合 .catchall(z.unknown())。
  7. 迁移测试文件,更新导入、声明 commandOptionsSchema、用 safeParse 重写校验测试、用 commandOptionsSchema.parse() 重写动作测试,删除旧“supports specifying”测试,并补充未知选项失败和无可选选项时通过的测试。

关键规则

  • 始终使用 z.strictObject(),除非命令接受未知选项;仅含全局选项时使用 globalOptionsZod.strict()。
  • 始终展开 ...globalOptionsZod.shape,并始终导出 options。
  • 不要对接受 @meid 的字段使用 z.uuid(),改用 .refine() 自定义 GUID 校验。
  • 保持选项名称不变,保留大小写不敏感行为,固定自动补全值优先用 z.enum()。
  • 逗号分隔的 GUID/UPN 校验错误只报告无效值,而非整个输入。
  • CLI 参数是字符串;数值转换在 commandAction 中显式处理。

适用场景与限制

适用于需要批量迁移 CLI for Microsoft 365 命令的项目。技能强调测试文件必须全部更新,动作测试必须使用 commandOptionsSchema.parse() 而不是 options.parse(),使用 @meid/@meusername 的测试保留 as any。文档未说明该技能自身的安装方式、收费、价格或平台信息。