如何在带有 NodeJS 目标的 TypeScript 中正确使用模块和接口？

Question

我和我的团队是 TypeScript 和 NodeJS 的新手，我们在启动这个项目时遇到了一些严重的问题。它是一个用 TypeScript 编写的模块化游戏资产管道，用于 NodeJS（我没有参与这里的决策，讨论仍在进行中，但我们仍然需要一个原型）。

我们已经对架构有了一个很好的了解，但是让原型运行起来还是有点困难，因为我似乎无法理解模块如何与接口和外部依赖项结合使用。我们的一些组件还需要使用 NodeJS 或其他库模块（例如 NodeJS.fs 用于读取/写入文件），我们希望能够使用 ///reference 添加适当的 d.ts 文件以保持类型安全在开发时。

假设项目结构的一个例子是：

/pipeline
    /log
        - ILog.d.ts
        - StdOutLog.ts
        - FileLog.ts
        - ...
    /reader
        - IReader.d.ts
        - TextReader.ts
        - ...
    /parser
        - IParser.d.ts
        - XmlParser.ts
        - JsonParser.ts
        - ...
    /task
        - ITask.d.ts
        - JsTask.ts
        - CliTask.ts
        - ...
    /...

我们希望使用它的方式是为我们的接口提供默认实现（涵盖基础知识，例如运行控制台命令、记录到文件或流、读取 JSON 和 XML 配置...），以及接口本身，以便其他团队可以创建自己的扩展（例如 class GitTask extends CliTask 来封装存储库操作，或 class JpgReader implements IReader）。

在调用方，在不同的项目/运行器应用程序中，它应该像这样工作：

import pipeline = require('pipeline');

//...

var log = new pipeline.log.FileLog();
log.info("filelog started");

var parser = new pipeline.parser.XmlParser();
parser.parse(somexmldata);
log.info("parsing XML");

// ...

我很可能只是做错了（tm），但我觉得用 TypeScript 做我们想做的事情并不容易，特别是考虑到例如日志组件的定义可以很容易地有多个接口和枚举（工厂、记录器、logitem、logtarget、loglevel）。据我了解，NodeJS 模块需要是单个 JS 文件，但即使使用单个 import 也会将您的模块变成外部模块，并且这些模块不会再编译成单个文件，所以这看起来很陡峭对我来说是个障碍。

有没有办法实现针对 NodeJS 的 TypeScript 的结构和预期用途？如果是，文件需要是什么样子（尤其是关于模块层次结构和组件 FQN，例如 pipeline.log.X、pipeline.task.Y 等；我将如何正确使用 module 和 export ）？如果不是，有哪些合适的替代方案可以实现我们的目标？

---

[更新] 我已经按照 basarat 的建议重构了我的原型，它已经看起来比以前好多了。但是，我在使用另一个类时遇到了编译错误：

error TS2095: Could not find symbol 'LogItem'.

LogItem 是在/log 中定义的一个类，它被同一文件夹中的StdOutLog.ts 使用。 IntelliJ 为我提供了多个定义（显然，一个是LogItem 类本身，另一个在/log 导出的索引文件中）。我试过使用模块符号log.LogItem，但没有用。将所有默认实现文件添加到全局声明文件也不起作用。 [/更新]

[Update2]这里还有一些关于错误发生位置的代码。仅在运行 grunt-ts 任务时，我在 IntelliJ 中没有收到任何错误/标记。

// src/log/LogItem.ts:

///<reference path='../pipeline.d.ts'/>
class LogItem implements ILogItem {
    // ...

    constructor(level:LogLevel, message:string) {
        // ...
    }

    public static create(level:LogLevel, message:string):ILogItem {
        return new LogItem(level, message);
    }

    // ...
}

export = LogItem;

// src/log/Log.ts:

///<reference path='../pipeline.d.ts'/>
class Log implements ILog {
    // ...

    private getLogItem(level:LogLevel, message:string):ILogItem {
        return LogItem.create(level, message); // <-- that's where I get the "symbol not found" error
    }

    // ...
}

export = Log;

// src/pipeline.d.ts:

///<reference path="../typings/node/node.d.ts" />

//grunt-start
/// <reference path="pipeline.ts" />
/// <reference path="log/Log.ts" />
/// <reference path="log/LogFactory.ts" />
/// <reference path="log/LogItem.ts" />
/// <reference path="log/StdLogEmitter.ts" />
/// <reference path="log/log.d.ts" />
/// <reference path="log/log.ts" />
/// <reference path="parser/JsonParser.ts" />
/// <reference path="parser/parser.d.ts" />
/// <reference path="parser/parser.ts" />
//grunt-end

[/Update2]

Answer 1

在全局globals.d.ts 文件中引用您的所有.d.ts 文件，该文件具有///<reference 标记到您的所有个人引用+ vendor.d.ts（例如node.d.ts）文件。

/pipeline
    /globals.d.ts
    /log
        - ILog.d.ts
        - StdOutLog.ts
        - FileLog.ts
        - ...
    /reader
        - IReader.d.ts
        - TextReader.ts
        - ...
    /parser
        - IParser.d.ts
        - XmlParser.ts
        - JsonParser.ts
        - ...
    /task
        - ITask.d.ts
        - JsTask.ts
        - CliTask.ts
        - ...
    /...

这可以防止您不断引用.d.ts 文件。

现在每个打字稿文件都会导出一些类，例如XmlParser.ts：

/// <reference path='../globals.d.ts'/>
class XMLParser implements IParser{
}
export = XMLParser;

每个文件夹还有一个index.ts，用于导入和导出该文件夹中的所有类外部模块样式：

export import XmlParser = require('./xmlParser'); 
// so on 

上一层也一样 (pipeline/index.ts)：

export import parser = require('./parser/index');

现在，如果您导入 pipeline/index.ts，您的代码将按预期工作：

import pipeline = require('./pipeline/index');


var parser = new pipeline.parser.XmlParser();
parser.parse(somexmldata);
log.info("parsing XML");

注意：Grunt-ts 可以为您创建这些 import / export 语句，这样您就无需担心文件路径：https://github.com/grunt-ts/grunt-ts/issues/85