typescript 编写类型声明文件注意事项

注：本文主要内容来自于官方文档的理解

当我们需要为第三方不支持ts的库编写类型声明文件时，本文包含一些需要避免的不太建议的用法，本文主要内容来源在此处： Do's and Don'ts

不要使用 Number String Boolean Symbol Object等类型，而是使用 number string boolean symbol object 等类型，因为大写开头的都是js中的自执行的基本包装类型，而非原始类型，比如 var a = 'ddd'中自执行的 a = new String('ddd');，很怪不，

在使用泛型时，泛型参数一定要被使用

interface Something<T> {
  name: string;
}

上述泛型接口例子，泛型T没被使用，这会导致当我们传入不同类型时，产生的变量可以被互相赋值，贴出官方FAQ例子

interface Something<T> {
  name: string;
}
let x: Something<number>;
let y: Something<string>;
x = y;

x 和 y可以被互相赋值，这很怪异，泛型根本没有作用，正确的使用泛型应该是这个姿势才对

interface Something<T> {
  name: T;
}

否则，就别强行使用泛型了。。。

当函数没有返回值时，使用void 而不是 any

function test(): any{
}
const a = test();
a.run();

ts 不会报错，但是本身，test函数没有返回值，自然a.run() 应该报错才对，所以，不要偷懒把该写void的地方写成any ！！

回调函数中，无需使用可选参数 因为函数参数在被赋值时，被赋值的函数参数数量本身是可以缺少的

function test(callback: (num: number) => void) {
    callback(5);
}

test((num: string) => { // 报错
    console.log("What");
});

test(() => { // 通过
    console.log("What");
});

本例我们的test函数在声明需要的callback参数时，声明了callback 有一个number类型参数，ts中进行函数兼容性判断时，函数参数是双向协变的（通过严格模式可以设置成逆变），返回值是协变的（ps：为什么这么设计呢，大概是因为我们平时js中使用map reduce filter时也并没有三个参数全用上。因为强行写上简直是无用功。。），

所以，在回调函数中使用可选参数是多余的，因为加不加，他都是可选的。另外可选参数的意义是会根据参数数量的不同而产生不同的调用，用在这里也不合适

interface Fetcher {
    getObject(done: (data: any, elapsedTime?: number) => void): void;
}

interface Fetcher {
    getObject(done: (data: any, elapsedTime: number) => void): void;
}

两者等价。

和上面同理，编写仅在回调函数参数数量上面不同的函数重载是没有意义的

declare function beforeAll(action: () => void, timeout?: number): void;
declare function beforeAll(action: (done: DoneFn) => void, timeout?: number): void;
// 无需写重载
declare function beforeAll(action: (done: DoneFn) => void, timeout?: number): void;

上面两行和下面一行等价！

函数重载过程中，要按照参数复杂度从小到大排序，因为typescript在匹配函数类型时是按照声明顺序匹配的

declare function fn(x: HTMLDivElement): string;
declare function fn(x: HTMLElement): number;
declare function fn(x: any): any;

按照一个包含另一个的从小到大顺序排列

当函数重载的返回值类型相同时，使用可选参数而不是函数重载，

// 错误
interface Example {
    diff(one: string): number;
    diff(one: string, two: string): number;
    diff(one: string, two: string, three: boolean): number;
}
// 正确
interface Example {
    diff(one: string, two?: string, three?: boolean): number;
}

为什么呢，当返回值类型相同时使用函数重载会导致两个问题，

赋值给回调函数时因为某个重载满足条件而错误赋值

function fn(callback: (a: string, b: number, c: number) => void) { }

interface Example {
    diff(one: string): number;
    diff(one: string, two: string): number;
    diff(one: string, two: string, three: boolean): number;
}

var x: Example;
fn(x.diff);

我们定义了fn函数，接受的回调函数有一个string 两个number类型的参数，当我们对diff函数使用重载时，我们可以将diff函数赋值给callback回调函数，因为第一个重载满足一个string参数，这显然使我们不想见到的，因为第二个重载第三个重载都不满足callback函数，是用可选参数可以避免此问题

function fn(callback: (a: string, b: number, c: number) => void) { }

interface Example {
    diff(one: string, two?: string, three?: boolean): number;
}

var x: Example;
fn(x.diff);

ts报错，这样才是我们想要的

2.当我们显式传入undefined时，函数重载会导致报错，

interface Example {
    diff(one: string): number;
    diff(one: string, two: string): number;
    diff(one: string, two: string, three: boolean): number;
}
var x: Example;
x.diff("something", true ? undefined : "hour")

当时用重载时，ts会报错undefined不能赋值给string，

interface Example {
    diff(one: string, two?: string, three?: boolean): number;
}
var x: Example;
x.diff("something", true ? undefined : "hour")

使用用可选参数可以避免此问题，因为我们未传参数时默认的值就是undefined，因此，显式传入undefined应该与未传表现一致才对，这才符合js的运行过程，可选参数可以解决这个问题。

当函数重载时，只有参数类型不一样时，使用联合类型

// 错误
interface Moment {
    utcOffset(b: number): Moment;
    utcOffset(b: string): Moment;
}
// 正确
interface Moment {
    utcOffset(b: number|string): Moment;
}

因为使用联合类型可以既接收单一类型的值，也可以接收联合类型的值，函数重载只能接收单一类型的值

function fn(x: number|string) {
    return moment().utcOffset(x);
}

函数重载时传入联合类型x报错，是用联合类型时可以传入联合类型，

最后希望大家为优秀的第三方库多做贡献，一起丰富typescript生态！