node.js - 如何在 TypeScript 中正确设计 API 模块？

Question

我想设计一个用于访问外部 IS 的 TypeScript (2.7) 模块，我们称它为 InfoSys。我使用了以下方法。

我创建了 info-sys.ts，它定义了一个 API 类以及相关的接口(interface)和枚举，例如:

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

您可以使用命名空间:

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 来导出“类型”，而不是值。

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

虽然表中说命名空间可以包含值，但如果您正在编写 ESM(导入/导出)，这被认为是不好的做法。

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