AI 考拉技术分享会--API 接口与 Typescript Interface

赶在祖国生日放假前，考拉 Dev team 的成员进行了小范围的技术分享会，Nick 格格分享了自己在工作中踩过的一些坑以及填坑大法。希望大家也能避开 bug，修得 node 大法！

前言

Interface 就是接口，在 typescript 用于类型限定。
在 Node 项目中，我们常用 apidoc 来定义接口文档。
那么，他们俩是否能结合起来呢？

一、apidoc 的痛点

apidoc Inline Documentation for RESTful web APIs，使用起来非常方便，直接在 api 上添加注释，就可以生成可视化的文档。
但是，在实际业务中，我们有些接口比较复杂，定义返回值是一件比较痛苦的事情，如图：
而且，过了一段时间之后，出于惰性，开发人员会放弃更新 API 文档，导致文档落后于实际。

二、API Interface

（一） API 未定义的问题

在 js 项目中，api 返回结构一般是无法清晰地看出来的，你得跑一下接口，才知道会返回什么，或者仔细看一遍代码。这种情况下，开发人员维护 API 会面临以下问题：

• 文档缺失：接口文档缺少对某个字段的定义，不知道该字段作何用处；
• 字段混乱：明明是一个字段，可能在 接口 A 是叫 amount， 在接口 B 却叫 number ；
• 重复定义：多个接口中都用到一个叫 Banner 的东西，需要在每个接口文档中定义一遍，稍有改动，需要更改多处。

（二）使用 interface 的好处

所以可以尝试使用 typescript 的 interface 来定义 API 的返回值结构，一个接口对应一个 interface。

假设一个 api 是 product info，定义结构如下：

/** * 产品明细 */ export interface IProductInfo { /** * 基础利息 */ baseRate: number /** * 加息 */ bonusRate: number /** * 加息提示 */ bonusRateStr: string } 

另一个 api 是 product list，可以很方便地进行复用：

/** * 产品列表 */ export interface IProductList { list: Array<IProductInfo> } 

这些接口定义也可以共享给前端（前端也用 typescript 的话）

（三） apidoc + interface

很多时候，你的痛点其实也是其他人的痛点，所以就有了开源项目，通过搜寻，我们可以找到一个 apidoc 的插件 apidoc-plugin-ts，这个插件可以根据 interface 的定义帮你生成 apidoc 需要的 @apiSuccess 内容。
定义一个接口：

filename: ./employers.ts export interface Employer { /** * Employer job title */ jobTitle: string; /** * Employer personal details */ personalDetails: { name: string; age: number; } } 

引入 interface:

 @apiInterface (./employers.ts) {Person} 

翻译的效果:

 @apiSuccess {String} jobTitle Job title @apiSuccess {Object} personalDetails Empoyer personal details @apiSuccess {String} personalDetails.name @apiSuccess {Number} personalDetails.age 

还支持数组结构定义呢~
有了这个插件，就可以通过维护 interface 来维护 apidoc 了。

三、注意

该插件不支持匿名接口定义数组结构， 如下：

export interface IProductList { list: Array<{ a: string, b: string }> } 

AST 解析代码的时候会拿不到某些属性，会报错。

写在最后的

今天是属于大家的 1024 节，在今天这个值得庆祝的日子，祝大家节日快乐，向程序猿致敬，向加班 SAY NO ！

著作权归本文作者所有，未经授权，请勿转载，谢谢。