Eclipse Theia 揭秘之启动流程篇

前言

在《Eclipse Theia 框架技术架构揭秘》一文中简单介绍了 Theia 框架整体的技术架构，接下来将通过系列文章从源码角度入手看一下 Theia 核心设计思路，本文从启动流程入手开始介绍 Theia 的运行原理。

基础

示例代码结构

根据 Build your own IDE 的文档创建示例工程，工程结构如下：

├── lib                   # 构建生成的 Bundle 包
├── plugins               # package.json 中 theiaPlugins 字段配置的插件
├── src-gen               # 自动生成的工程文件
|   ├── backend
|   └── frontend
├── gen-webpack.config.js # 自动生成的 Webpack 配置
├── package.json          # 应用配置包
└── webpack.config.js     # 引用 gen-webpack.config.js 配置文件

这个工程除了 package.json 和 webpack.config.js 文件外，其他文件都是通过 @theia/cli 包自动生成的，使用 theia build 命令会默认覆盖工程中的文件，为了后续的升级维护，原则上不能直接修改 lib、plugins、src-gen、gen-webpack.config.js，那么我们如果想构建自定义 IDE，显然这种基础的工程结构是不能满足要求的，如果想进一步定制开发脚手架，需要先了解官方默认的运行原理。

package.json 配置

基于 Theia 框架的应用可以在 package.json 中增加 theia、theiaPluginsDir、theiaPlugins 字段的配置，主要分为以下几类：

Application Properties

应用属性配置，例如应用名称：

"theia": {
    "frontend": {
        "config": {
        "applicationName": "Custom Application Name"
        }
    }
},

Default Theme

默认主题配置，例如：

"theia": {
    "frontend": {
        "config": {
        "defaultTheme": "light",
      "defaultIconTheme": "vs-seti"
        }
    }
},

Default Preferences

默认首选项提供了应用运行的默认配置。

"theia": {
    "frontend": {
        "config": {
            "preferences": {
                "files.enableTrash": false
            }
        }
    }
},

Default Generator

配置启动模板：

"theia": {
  "generator": {
    "config": {
      "preloadTemplate": "
"
    }
  }
}

Build Target & Target Config

Theia 支持 browser 和 electron 两种构建目标，默认目标是 browser。

{
    "theia": {
    "target": "electron",
    "frontend": {
      "config": {
        "electron": {
          "windowOptions": {
            "titleBarStyle": "hidden",
            "webPreferences": {
              "webSecurity": false,
              "nodeIntegration": true,
              "allowRunningInsecureContent": true,
              "webviewTag": true
            }
          }
        }
      }
    }
  },
    "dependencies": {
        "@theia/electron": "latest"
    }
}

Using Latest Builds

使用最新版本

{
    "theia": {
        "next": "true"
    }
}

Theia Plugins

Theia 插件相关的配置，theiaPluginsDir 定义插件下载后存放的位置，theiaPlugins 定义应用依赖的插件。

"theiaPluginsDir": "plugins",
"theiaPlugins": {
    "vscode-builtin-bat": "https://github.com/theia-ide/vscode-builtin-extensions/releases/download/v1.39.1-prel/bat-1.39.1-prel.vsix",
    "vscode-builtin-clojure": "https://github.com/theia-ide/vscode-builtin-extensions/releases/download/v1.39.1-prel/clojure-1.39.1-prel.vsix",
}

Theia CLI 基本命令

命令	含义及备注
theia build --mode development	开发模式构建
theia build	生成模式构建
theia build --watch --mode development	监听构建
theia clean	清理构建产物
theia rebuild	electron 目标模式下开发，回滚 Native 模块，切换到 browser 目标模式下等需要执行该命令
theia start	启动后端服务
theia start --inspect	调试后端服务
theia download:plugins	下载插件

Theia 源码目录结构

以下目录结构是基于 v1.1.0 版本整理。

├── .github                   # GitHub 配置
├── .theia                    # Theia 配置
├── .vscode                   # VS Code 配置
├── configs                   # 工程 eslint、tsconfig 等配置
├── dev-packages
|   ├── application-manager   # 应用工程管理类，提供 Frontend、Backend、Webpack 代码生成
|   ├── application-package   # 应用 package.json 配置解析，管理 Application、Extensions
|   ├── cli                   # CLI 工具，提供 start、build 等命令
|   ├── electron              # Electron Target 运行环境依赖
|   └── ext-scripts           # Theia package 之间共享 npm scripts
├── doc                                             # 文档
├── examples                  # 示例
├── logo                      # Logo 物料
├── packages                  # 框架模块
|   ├── callhierarchy
|   ├── console
|   ├── core                  
|   ├── ...
|   └── workspace
├── scripts                   # 工程运行相关的脚本
├── .editorconfig
├── .eslintrc.js
├── .gitignore
├── .gitpod.dockerfile
├── .gitpod.yml
├── .npmignore
├── .travis.yml
├── .yarnrc
├── devfile.yaml
├── lerna.json
├── package.json
├── tsconfig.json
└── tsfmt.json

packages 目录下的子模块，包含如下子目录层级，按不同的平台进行区分：

• common：仅使用基本的 JavaScript API，可以在所有的目标环境中运行的源代码；
• browser：需要使用例如 DOM 等 Browser APIs 等源代码，可能会使用 common 中的代码；
• node：需要使用 Node.js APIs 的源代码，可能会使用 common 中的代码；
• electron-node：需要使用 Node.js APIs 的 Electron 相关的源代码，可能会使用 common 中的代码；
• electron-browser：需要使用 Electron renderer-process APIs 的源代码，可能会使用 common、browser、node 中的代码；
• electron-main：需要使用 Electron main-process APIs 的源代码，可能会使用 common、node 中的代码。

Inversify 框架

IoC (Inversion of Control) 容器有依赖注入(Dependency Injection)和依赖查询(Dependency Lookup)两种实现模式。InversifyJS 是一个强大的轻量级 IoC 容器框架，Inversify 中通过依赖注入的模式实现 IoC 容器。

@injectable & @inject

通过 @injectable() 装饰器标记可注入的服务；如果目标对象中的构造函数里有 @inject() 装饰器，则将相应的实例当作构造函数的参数注入，@inject 装饰器在运行时可用。

/**
 * The main entry point for Theia applications.
 */
@injectable()
export class BackendApplication {
    protected readonly app: express.Application = express();

    @inject(ApplicationPackage)
    protected readonly applicationPackage: ApplicationPackage;

    private readonly _performanceObserver: PerformanceObserver;

    constructor(
        @inject(ContributionProvider) @named(BackendApplicationContribution)
        protected readonly contributionsProvider: ContributionProvider,
        @inject(BackendApplicationCliContribution) protected readonly cliParams: BackendApplicationCliContribution
    ) {
        ...
    }
    ...
}

对于外部库我们无法通过装饰器标识可注入的类，我们可以通过 API 的方法注入：

import { decorate, injectable } from 'inversify';
decorate(injectable(), CLASS_NAME); // CLASS_NAME 是类名

Service

通过 Container 的 bind 方法手动将依赖与容器实现绑定：

bind(serviceIdentifier: ServiceIdentifier): BindingToSyntax;

通过服务标志 serviceIdentifier 生成绑定对象 BindingToSyntax ，该对象定义了丰富的绑定函数，诸如 to()、toSelf()、toConstantValue()、toFactory() 等。可以将多个服务使用相同到 serviceIdentifier 进行绑定，具体可以参考：Multi-injection。

 

可以通过 Container 的 get 方法解析依赖：

get(serviceIdentifier: interfaces.ServiceIdentifier): T;

完整实例如下：

let container = new Container({ autoBindInjectable: true });
container.bind(Ninja).to(Samurai);
container.get(Ninja);              // returns a Samurai

可以使用 autoBindInjectable 激活 @injectable() 装饰类的自动绑定：

let container = new Container({ autoBindInjectable: true });
container.isBound(Ninja);          // returns false
container.get(Ninja);              // returns a Ninja
container.isBound(Ninja);          // returns true

ContainerModule

Container modules 可以用来组织复杂应用的模块依赖关系，通过 ContainerModule 初始化容器模块，通过 load 加载模块。

load(...modules: interfaces.ContainerModule[]): void;

同步容器模块：

let warriors = new ContainerModule((bind: interfaces.Bind, unbind: interfaces.Unbind) => {
    bind("Ninja").to(Ninja);
});

let weapons = new ContainerModule(
    (
        bind: interfaces.Bind,
        unbind: interfaces.Unbind,
        isBound: interfaces.IsBound,
        rebind: interfaces.Rebind
    ) => {
        bind("Katana").to(Katana);
        bind("Shuriken").to(Shuriken);
    }
);

let container = new Container();
// 加载模块
container.load(warriors, weapons);
// 卸载模块
container.unload(warriors);

异步容器模块：

let warriors = new AsyncContainerModule(async (bind: interfaces.Bind, unbind: interfaces.Unbind) => {
    const ninja = await getNinja();
    bind("Ninja").toConstantValue(ninja);
});

let weapons = new AsyncContainerModule(
    (
        bind: interfaces.Bind,
        unbind: interfaces.Unbind,
        isBound: interfaces.IsBound,
        rebind: interfaces.Rebind
    ) => {
        bind("Katana").to(Katana);
        bind("Shuriken").to(Shuriken);
    }
);

let container = new Container();
// 加载模块
await container.loadAsync(warriors, weapons);
// 卸载模块
container.unload(warriors);

PhosphorJS 框架

Theia 框架前端 UI 布局和 Services 一样，具备灵活可拓展的特点。VS Code 是内置了一套基本的组件系统，而 Theia 框架的 UI 布局基于 PhosphorJS 框架。 PhosphorJS 提供了一组丰富的小部件，布局，事件和数据结构。

@phosphor/widgets

PhosphorJS Widge 提供了一套组件机制，通过 JS 代码的方式构建 UI 组件，同时可以和其他组件配合使用。

import { Widget } from '@phosphor/widgets';
let widget = new Widget();
let div = document.createElement('div');
widget.node.appendChild(div);

操作 CSS 类名：

let widget = new Widget();
widget.id = 'main';
widget.addClass('foo');
widget.addClass('bar');
widget.removeClass('foo');
widget.toggleClass('bar', false);

将 Widget 附加到 DOM 元素上：

let widget = new Widget();
widget.attach(document.body);

将 Widget 从 DOM 上分离：

let widget = new Widget();
widget.attach(document.body);

// 方法1
widget.detach();
// 方法2
widget.dispose();

@phosphor/messaging

MessageLoop 提供了 sendMessage 发送同步消息 和 postMessage 发送异步消息。

import { IMessageHandler, Message, MessageLoop } from '@phosphor/messaging';

class Handler implements IMessageHandler {
  processMessage(msg: Message): void {
    console.log(msg.type);
  }
}

let handler = new Handler();
MessageLoop.sendMessage(handler, new Message('one'));    // logs 'one'
MessageLoop.postMessage(handler, new Message('two'));    // sometime later: logs 'two'

可以通过 MessageLoop.installMessageHook 设置一个 message hook，在消息被发送到 handler 处理之前执行 hook，对 message 进行处理，如果 hook 返回 false，则不会调用其他 hooks，并且消息不会被发送到 handler 进行处理。

import { IMessageHandler, Message, MessageLoop } from '@phosphor/messaging';

class LogHook implements IMessageHook {
  messages: string[] = [];
  messageHook(target: IMessageHandler, msg: Message): boolean {
    this.messages.push(msg.type);
    return true;
  }
}

let panel = new Widget();
let layout = new LogPanelLayout();
let widget = new Widget();
let hook = new LogHook();
panel.layout = layout;
MessageLoop.installMessageHook(widget, hook);
Widget.attach(panel, document.body);
layout.insertWidget(0, widget);

应用启动流程

执行 npm run start 实际上是执行 theia start 命令。

@theia/cli

theia 命令注册

Theia Cli 是一个基于 Node.js 的 Cli 工具，package.json 中通过 bin 字段注册 theia 命令。

"bin": {
    "theia": "./bin/theia"
 },

./bin/theia 文件如下：

#!/usr/bin/env node
require('../lib/theia')

#!/usr/bin/env node 语句是指定脚本的解释器，通过全局的环境变量找到 node，从而执行脚本里面的代码。

theia 命令实现

CLI 工具的具体实现在 src/theia.ts 中：

const projectPath = process.cwd();
const appTarget: ApplicationProps.Target = yargs.argv['app-target'];
const manager = new ApplicationPackageManager({ projectPath, appTarget });
const target = manager.pck.target;

function commandArgs(arg: string): string[] {
    const restIndex = process.argv.indexOf(arg);
    return restIndex !== -1 ? process.argv.slice(restIndex + 1) : [];
}

yargs
  .command({
  command: 'start',
  describe: 'start the ' + manager.pck.target + ' backend',
  handler: async () => {
    try {
      manager.start(commandArgs('start'));
    } catch (err) {
      console.error(err);
      process.exit(1);
    }
  }
})
// 省略...

// see https://github.com/yargs/yargs/issues/287#issuecomment-314463783
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const commands = (yargs as any).getCommandInstance().getCommands();
const argv = yargs.demandCommand(1).argv;
const command = argv._[0];
if (!command || commands.indexOf(command) === -1) {
  console.log('non-existing or no command specified');
  yargs.showHelp();
  process.exit(1);
} else {
  yargs.help(false);
}

可以看到 cli 中主要是利用 yargs 处理命令行的参数，然后传到 ApplicationPackageManager 类中的方法中进行处理。

@theia/application-manager

ApplicationPackageManager 类是在 @theia/application-manager npm 包中定义的。

ApplicationPackageManager 实现

export class ApplicationPackageManager {

    readonly pck: ApplicationPackage;
    /** application process */
    readonly process: ApplicationProcess;
    /** manager process */
    protected readonly __process: ApplicationProcess;
    protected readonly webpack: WebpackGenerator;
    protected readonly backend: BackendGenerator;
    protected readonly frontend: FrontendGenerator;

    constructor(options: ApplicationPackageOptions) {
        this.pck = new ApplicationPackage(options);
        this.process = new ApplicationProcess(this.pck, options.projectPath);
        this.__process = new ApplicationProcess(this.pck, path.join(__dirname, '..'));
        this.webpack = new WebpackGenerator(this.pck);
        this.backend = new BackendGenerator(this.pck);
        this.frontend = new FrontendGenerator(this.pck);
    }

    protected async remove(fsPath: string): Promise {
        if (await fs.pathExists(fsPath)) {
            await fs.remove(fsPath);
        }
    }

    async clean(): Promise {
        await this.remove(this.pck.lib());
        await this.remove(this.pck.srcGen());
        await this.remove(this.webpack.genConfigPath);
    }

    async generate(): Promise {
        await this.webpack.generate();
        await this.backend.generate();
        await this.frontend.generate();
    }

    async copy(): Promise {
        await fs.ensureDir(this.pck.lib());
        await fs.copy(this.pck.frontend('index.html'), this.pck.lib('index.html'));
    }

    async build(args: string[] = []): Promise {
        await this.generate();
        await this.copy();
        return this.__process.run('webpack', args);
    }

    start(args: string[] = []): cp.ChildProcess {
        if (this.pck.isElectron()) {
            return this.startElectron(args);
        }
        return this.startBrowser(args);
    }

    startElectron(args: string[]): cp.ChildProcess {
        // If possible, pass the project root directory to electron rather than the script file so that Electron
        // can determine the app name. This requires that the package.json has a main field.
        let appPath = this.pck.projectPath;

        if (!this.pck.pck.main) {
            appPath = this.pck.frontend('electron-main.js');

            console.warn(
                `WARNING: ${this.pck.packagePath} does not have a "main" entry.\n` +
                'Please add the following line:\n' +
                '    "main": "src-gen/frontend/electron-main.js"'
            );
        }

        const { mainArgs, options } = this.adjustArgs([ appPath, ...args ]);
        const electronCli = require.resolve('electron/cli.js', { paths: [this.pck.projectPath] });
        return this.__process.fork(electronCli, mainArgs, options);
    }

    startBrowser(args: string[]): cp.ChildProcess {
        const { mainArgs, options } = this.adjustArgs(args);
        return this.__process.fork(this.pck.backend('main.js'), mainArgs, options);
    }

    private adjustArgs(args: string[], forkOptions: cp.ForkOptions = {}): Readonly<{ mainArgs: string[]; options: cp.ForkOptions }> {
        const options = {
            ...this.forkOptions,
            forkOptions
        };
        const mainArgs = [...args];
        const inspectIndex = mainArgs.findIndex(v => v.startsWith('--inspect'));
        if (inspectIndex !== -1) {
            const inspectArg = mainArgs.splice(inspectIndex, 1)[0];
            options.execArgv = ['--nolazy', inspectArg];
        }
        return {
            mainArgs,
            options
        };
    }

    private get forkOptions(): cp.ForkOptions {
        return {
            stdio: [0, 1, 2, 'ipc'],
            env: {
                ...process.env,
                THEIA_PARENT_PID: String(process.pid)
            }
        };
    }

}

ApplicationPackage 负责解析 package.json 配置生成应用包相关的信息；ApplicationProcess 将 Node.js child_process 模块的方法包装了一层，ApplicationPackageManager 构造函数中初始化了两个子进程： process 进程用于应用运行， __process 进程用于应用构建。WebpackGenerator、BackendGenerator、FrontendGenerator 负责管理代码生成。

当我们执行 theia start 命令的时候实际上会调用 ApplicationPackageManager 的 start 方法，根据 target 从而调用 startElectron 或者 startBrowser 方法，我们可以发现最终都会调用  this.__process.fork   方法。

如果要理解这句代码的作用我们需要了解 child_process.fork 。

child_process fork 函数

在 Node 中，child_process 模块提供了衍生子进程的能力，提供了 4 种方式创建子进程：child_process.spawn()，child_process.fork()，child_process.exec()，child_process.execFile()。spawn() 方法在一个新的进程里启动一个命令，可以给这个命令传递任何的参数；fork() 方法是 spawn() 的一个特例，专门用于衍生新的 Node.js 进程。

child_process.fork(modulePath[, args][, options])

• modulePath  在子进程中运行的模块；
• args  字符串参数的列表；
• options