TypeScript 如何做 SDK 类型

在开发 App 或小程序时，你肯定用过那些封装好的功能插件——比如支付、地图定位、分享组件，这些能直接用的工具代码，就叫 SDK（软件开发工具包）。但很多人不知道，给 SDK 加上 TypeScript 类型，能让用它的人少踩很多坑，今天就用生活化的例子，把这件事说清楚。

为什么要给 SDK 加类型？

假设你开发了一个微信分享的 SDK，功能是让用户调用它弹出分享框。如果只用 JavaScript 写，用户调用时可能犯各种错：比如把必填的“分享链接”写成了空字符串，或者把“分享标题”传成了数字。

有一次我做小程序开发，用了个没加类型的 SDK，明明要传字符串的分享内容，我不小心传了数组，结果代码跑了半天没反应，查了半小时才发现问题。但如果 SDK 自带类型，在写代码的时候，编辑器就会直接弹出提醒“这里要填字符串，不能是数组”，根本不会让错误出现在运行阶段——这就是类型的作用：提前挡住低级错误，让用 SDK 的人更省心。

怎么用 TypeScript 给 SDK 加类型？

不用搞复杂的配置，就像给朋友写便条一样，把“这里要写什么”明明白白标出来就行，核心是三步。

第一步，定义“用 SDK 时传什么参数”。还是说分享的例子，SDK 需要三个东西：分享标题（字符串）、分享链接（字符串）、分享的图片地址（选填，可写可不写）。这时候用 TypeScript 的 interface 就能搞定，它就像一张“参数说明书”：

`typescript

// 分享参数的类型说明

interface ShareParams {

title: string; // 必填，分享标题是字符串

url: string; // 必填，分享链接是字符串

imageUrl?: string; // 选填，前面的?表示可省略

}

`

这里的 ? 很关键，就像便条里标了“可选”，不用写也没关系。

第二步，定义“SDK 返回什么结果”。用户调用 SDK 后，可能成功分享，也可能失败，这时候要把返回的东西说清楚。比如成功会返回分享成功的提示，失败会返回错误信息，用 type 就能把这些结果归类：

`typescript

// 分享结果的类型说明

type ShareResult =

| { success: true; message: string } // 成功的情况

| { success: false; error: string }; // 失败的情况

`

就像给朋友说“不管你给我看结果，我都知道是成功还是失败，成功了有提示，失败了有错误原因”。

第三步，把类型“挂”到 SDK 的函数上。最后一步就是把写好的类型和 SDK 的核心函数绑在一起，让用户调用的时候自动生效：

`typescript

// 把类型加到 SDK 的函数上

export function share(params: ShareParams): ShareResult {

// 这里是 SDK 实际的代码逻辑

if (!params.title || !params.url) {

return { success: false, error: "标题和链接不能空" };

}

return { success: true, message: "分享成功" };

}

`

就像你给朋友递工具的时候，顺便递上一张使用说明，告诉“怎么用、用错了会怎么样”。

加了类型后，用户能得到什么好处？

除了提前挡错误，用户还能直接在编辑器里看到 SDK 的说明，不用翻文档。比如输入 share( 的时候，编辑器就会自动弹出“需要传title、url，imageUrl可选”，就像点外卖时自动弹出“加冰要备注，可选”一样方便。

而且如果之后你给 SDK 加了新功能，比如“增加分享按钮颜色的参数”，只要改类型里的说明，用户的编辑器就会直接提醒“有新参数可以用”，不用你再特意发更新通知。

这么看，给 SDK 加 TypeScript 类型，就像给普通工具包贴了清晰的使用标签，既省了开发者的维护时间，也让用的人少踩坑，是件双赢的小事。