如何在TypeScript中正确设计API模块？

Question

我想设计一个TypeScript（2.7）模块来访问外部IS，我们称之为InfoSys。我使用了以下方法。

我创建了info-sys.ts，它定义了API类和相关的接口和枚举，如：

class Api {
    constructor(private endpoint: Endpoint) {
        // ...
    }
}

enum Endpoint {
    CONTACTS = "contacts"
}

interface Contact {
    name: string;
}

现在我想以特定名称导出所有内容。所以我附上了导出声明：

export const InfoSys = {
    Api,
    Endpoint,
    Contact
};

当我尝试在另一个文件中使用该模块时，例如：

import { InfoSys } from "info-sys";

// this line throws error: "Cannot find namespace 'InfoSys'"
private api: InfoSys.Api;

// but this line is ok
api = new InfoSys.Api(InfoSys.Endpoint.CONTACTS);

可行的方法如下 - 单独导出每个部分：

export class Api {
    constructor(private endpoint: Endpoint) {
        // ...
    }
}

export enum Endpoint {
    CONTACTS = "contacts"
}

export interface Contact {
    name: string;
}

并将它们全部导入到一个变量中：

import * as InfoSys from "info-sys";

但变量的名称可以是任何东西。它对功能并不重要，但我想强制开发人员（将使用info-sys模块）在访问时使用特定名称（为了更易于阅读和维护）。如何正确设计这样的模块？

Answer 1

你可以使用namespace：

export namespace InfoSys {
  Api,
  Endpoint,
  Contact
};

通常，应该避免这种方法。但是在你的情况下，你可以提供紧密相关的东西。

如果Api是所有这些的单一切入点，我也会建议：

export class InfoSysApi { ... }
export namespace InfoSysApi {
  export enum Endpoint = { ... }
  export interface Contact { ... }
}  

更新：为确保我明白这一点，请勿执行以下操作：

export namespace Foo {
  export function X() { return 'x' }
  export function Y() { return 'y' }
}

只使用export namespace导出“tugged in types”，而不是值。

在TypeScript手册中：https://www.typescriptlang.org/docs/handbook/declaration-merging.html

尽管该表说命名空间可以包含值，但如果您正在编写ESM（导入/导出），则认为这是不好的做法。

命名空间和ESM是实现类似结果的两种不同机制。不要将它们混合在一起。