TypeScript 类型体操:如何为 SDK 编写优雅的类型定义

背景

作为一款 SDK,提供完善的 TypeScript 类型定义(.d.ts)是对用户最基本的尊重。 AutoForm 的配置项非常复杂,且存在很多联动关系。如何用 TS 准确描述这些关系?

今天带大家做一套类型体操。

挑战一:互斥属性

如果配置了 mode: 'auto',则 interval 必填;如果 mode: 'manual',则 interval 不可填。

错误写法:

typescript 复制代码
interface Config {
  mode: 'auto' | 'manual';
  interval?: number;
}

正确写法(Discriminated Unions):

typescript 复制代码
type AutoConfig = {
  mode: 'auto';
  interval: number;
};

type ManualConfig = {
  mode: 'manual';
  interval?: never; // 关键:禁止出现
};

type Config = AutoConfig | ManualConfig;

挑战二:事件回调的类型推导

我们希望用户在监听事件时,能自动推导出 event 对象的类型。

typescript 复制代码
sdk.on('success', (e) => {
  console.log(e.data); // e 应该是 SuccessEvent
});

sdk.on('error', (e) => {
  console.log(e.message); // e 应该是 ErrorEvent
});

实现:

typescript 复制代码
type EventMap = {
  success: { any };
  error: { message: string; code: number };
};

class SDK {
  on<K extends keyof EventMap>(
    type: K, 
    handler: (event: EventMap[K]) => void
  ) {
    // ...
  }
}

挑战三:深度 Partial

用户配置时,通常只需要覆盖默认配置的一部分。我们需要一个递归的 Partial。

typescript 复制代码
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

总结

TypeScript 不仅仅是类型检查工具,更是最好的文档。写好类型定义,能让用户在使用 SDK 时获得极致的智能提示体验,减少查阅文档的时间。

👉 官网地址:51bpms.com

相关推荐
Mh2 小时前
我是如何设计品牌站组件库的?
前端·css·设计模式
ZhengEnCi2 小时前
AI 读不懂你的代码怎么办:用高价值注释消除曲解、过度优化与上下文膨胀
aigc·ai编程
程序员大阳2 小时前
副队长Vue3教程(2)--Vite 搭建 Vue 项目,认识目录结构
前端·javascript·vue.js·vite·创建项目·目录结构·项目结构
濮水大叔3 小时前
Cabloy/Zova 与 Next.js 的 SSR 水合差异
前端·typescript·next.js
SoaringHeart3 小时前
Flutter最佳实践:用 flutter_html 渲染富文本
前端·flutter
Flynt4 小时前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
北城笑笑5 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
程序员韩星5 小时前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson5 小时前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
爱查宝小二5 小时前
爱查宝降AIGC效果实测与过检能力展示
aigc