公共项目开发:我为什么用 JSDoc,而不用 ts

  • A+
所属分类:Web前端
摘要

公共模块,通常会被多个项目、不同的开发人员使用,所以开发公共模块时,你自己会用还不够,要让所有人都能很快的知道怎么去使用,这一点很关键。通常会从3个方面做到这点:

公共模块,通常会被多个项目、不同的开发人员使用,所以开发公共模块时,你自己会用还不够,要让所有人都能很快的知道怎么去使用,这一点很关键。通常会从3个方面做到这点:

  1. 精心分割代码逻辑,遵循开闭原则;
  2. 变量名采用自解释性的标识符;
  3. 依赖完善的使用提示。

第1点用户体验不到,如果没有做好第3点,第2点用户也是体验不到的,只有第3点时真正面对用户的,所以做好第3点很重要!本篇文章就是教你如何在实现js模块时,做好完善的使用提示。

是否要用ts写公共项目?

目前不建议使用ts开发公共组件,理由如下:

你的项目正常应该是打包成 umd包,并且和源码一起发布。因为:

umd包使用非常灵活,支持script标签隐式引用,amd,cmd,commonjs,esm引用,也是当前最流行的公共模块包。但umd包不能使用tree-shaking。
tree-shaking作为官方的项目优化方案,目前越来越流行,几乎已是必备的项目优化技术。tree-shaking是基于es module的,单纯的umd无法实现。
通常恰好你的公共模块源码就是通过es module编写的,所以将源码一起发布,不只是让使用者能够查看,还为了让使用者方便tree-shaking优化。

 

如果业务项目(这里指 引用你的公共项目模块的其他项目,以下都是这个意思)不会用到源码,只是引用umd包,那么采用ts编写源码不会有任何影响。
但如果要做tree-shaking而引用源码时,而你的源码是用ts编写,问题就来了:业务项目无形中被绑上了ts的“贼船”,引用你的源码,同时打包编译脚本要支持ts。
如果业务项目不想引入ts怎么办?

ts的很多优点,但的确不太适合开发公共项目,而且运用js Doc 注释,ts的绝大多数有点也能轻松实现。
而且即便业务项目使用ts开发,也能引用你的js模块。

为了不给业务项目带来副作用,就采用js语言吧。

js中使用ts

尽管确定使用 js语言编写公共项目,你依然享受到 ts的便利。ts天生就支持js!

// @ts-check // js文件开头,使用上面这个注释,开启ts支持。接下来整个文件,都有了ts校验的功能,会出现类型错误提示等。   let a = 22   // @ts-ignore a="string" // 将一个string赋给number类型的a,正常情况会有类型报错。但 // 上一行 // @ts-ignore 这个注释表示,接下来的一条语句忽略ts校验,所以这里不报错

开启 ts 校验后,接下来就使用 jsDoc了,如果你还安装了typeScript:

#全局安装: npm install -g typescript  #或 项目局部安装: npm install --save-dev typescript

那么接下来,使用命令 :  tsc --declaration src/lib/service.js --allowJs   就可以根据你所写的 JSDoc,为你的service.js文件生成 .d.ts文件了。

转换的示例(下方示例的js代码生成的.d.ts):

export type MethodType = "get" | "post" | "delete" | "put" | "patch"; export type RequesFn = (method: MethodType, url: string, params: any) => Promise<object>; export type Person = {     name: string;     age: number;     sex: 'male' | 'female'; }; export type AxiosRes<T> = {     code: number;     data: T;     msg: string; };  export type TokenRes = {     mediaId: string;     mediaKey: string;     token: string; };

JSDoc示例

1、定义复杂类型+对变量添加类型

// @ts-check  /**  * @typedef {{name:string,age:number,sex:'male'|'female'}} Person   */ /**  * @type Person  */ let jim = {name:'jim',age:28,sex:'female'}

把鼠标移到 jim变量上,还有类型提示,就像ts中一样:

公共项目开发:我为什么用 JSDoc,而不用 ts

 

 关于类型提示的示例截图,接下来就不贴上了,你可以在 vscode 试一下。

2、函数的类型

/**  * @typedef {'get'|'post'|'delete'|'put'|'patch'} MethodType  */ /**  * @returns { Promise<object>}  // 定义返回的类型  * @param {MethodType} method   // 注意是@param,不再是@type了,MethodType是前面定义好的类型  * @param {string} url   * @param {*} [params]     // 中括号表示可选参数,*表示any类型  */ function myAjax(method,url,params){     return new Promise(resolve=>{         // other code ...     }) }

js里也有类型推断,如果不指明返回的是 Promise<object>  这里会自动推断出返回的是 Promise<any>

你也可以这样定义函数类型:

/**  * @typedef {(method:MethodType,url:string,params:any)=>Promise<object>} RequesFn  */ // /**  * @typedef {{(method:MethodType,url:string,params:any):Promise<object>}} RequesFn  */   // 使用:  /**   * @type {RequesFn}    */ function myAjax(method, url, params) {   }

注意两种定义函数类型类型 RequestFn 的方式,和 ts 是完全一样的!

3、定义和使用泛型 

/**  * @template T    // 这里用 @template声明泛型类型T  * @typedef {{code:number,data:T,msg:string}} AxiosRes  */  /**  * @typedef  {{mediaId:string, mediaKey:string, token:string }} TokenRes          * @type {TokenRes|AxiosRes<TokenRes>}    // 这里是泛型的使用  */ let res

 鼠标放到res变量上:

公共项目开发:我为什么用 JSDoc,而不用 ts

 记住这个res,它是个复合类型的变量,下一节的类型强转就用它了

4、类型的强转(即ts中的类型断言)

if (/**@type {AxiosRes<TokenRes>} */(res).data === undefined) {     console.log('res 是TokenRes类型')     let mediaId = /**@type{TokenRes} */(res).mediaId } else {     console.log('res 是AxiosRes<TokenRes>类型')     let mediaId = /**@type {AxiosRes<TokenRes>} */(res).data.mediaId }

 把注释去掉,其实很简单:

if (res.data === undefined) {     console.log('res 是TokenRes类型')     let mediaId = res.mediaId } else {     console.log('res 是AxiosRes<TokenRes>类型')     let mediaId = res.data.mediaId }

 类型断言的方法就是 @type 注释后面将要断言的变量用括号括起来    /**@type{TokenRes} */(res)  

 

更多示例,我就不列举了,可以查看官网:https://www.html.cn/doc/jsdoc/about-namepaths.html 自己学习了

加上jsDoc的好处

回到最开始的话题,你的公共项目如何给使用者完善的使用提示?

当你使用jsDoc时,你会发现 业务项目如果引用你的源码,会自然的带上提示

如果是引用你的dist压缩包,那么我们合理的组织代码,然后用   tsc --declaration --allowJs xxx.js  命令,生成 .d.ts 发布出去,一样会有良好的提示。