Theia APIs——通過JSON-RPC進行通信

上一篇：Theia APIs——事件

通過JSON-PRC進行通信

　　在本節中，我將講解如何創建後端服務並通過JSON-PRC來連接它。

　　我將使用debug logging system作爲例子來進行講解。

概述

　　本示例將用express框架創建一個服務，然後通過websocket連接該服務。

註冊服務

　　首先要做的是將服務公開，這樣前端就能連接它。

　　你需要創建一個後端服務模塊（類似logger-server-module.ts）：

import { ContainerModule } from 'inversify';
import { ConnectionHandler, JsonRpcConnectionHandler } from "../../messaging/common";
import { ILoggerServer, ILoggerClient } from '../../application/common/logger-protocol';

export const loggerServerModule = new ContainerModule(bind => {
    bind(ConnectionHandler).toDynamicValue(ctx =>
        new JsonRpcConnectionHandler<ILoggerClient>("/services/logger", client => {
            const loggerServer = ctx.container.get<ILoggerServer>(ILoggerServer);
            loggerServer.setClient(client);
            return loggerServer;
        })
    ).inSingletonScope()
});

　　我們來詳細看一下：

import { ConnectionHandler, JsonRpcConnectionHandler } from "../../messaging/common";

　　這一行導入了JsonRpcConnectionHandler，這是一個工廠類，我們用它創建了一個onConnection連接處理程序，它爲後端通過JSON-RPC調用的對象創建一個代理，並將一個本地對象公開給JSON-RPC。

接下來我們來看看具體的實現過程。

　　ConnectionHandler是一個簡單的接口，它指定了連接的路徑以及在連接創建時的行爲。

　　它是這樣的：

import { MessageConnection } from "vscode-jsonrpc";

export const ConnectionHandler = Symbol('ConnectionHandler');

export interface ConnectionHandler {
    readonly path: string;
    onConnection(connection: MessageConnection): void;
}

import { ILoggerServer, ILoggerClient } from '../../application/common/logger-protocol';

　　文件logger-protocol.ts包含了服務器和客戶端需要實現的接口。

　　這裏的服務器指的是將通過JSON-RPC調用的後端對象，而客戶端指的是可以接收來自後端對象的通知的對象。

　　稍後我們會詳細介紹。

bind<ConnectionHandler>(ConnectionHandler).toDynamicValue(ctx => {

　　這裏有個地方很神奇，乍一看，它是一個ConnectionHandler的實現。

　　神奇之處在於，這個ConnectionHandler類型是綁定到messaging-module.ts文件中的ContributionProvider的。

　　所以，當MessageingContribution啓動時（調用onStart），它爲所有綁定ConnectionHandlers創建一個websocket連接。

　　像這樣（來自messageing-mocule.ts）：

constructor( @inject(ContributionProvider) @named(ConnectionHandler) protected readonly handlers: ContributionProvider<ConnectionHandler>) {
    }

    onStart(server: http.Server): void {
        for (const handler of this.handlers.getContributions()) {
            const path = handler.path;
            try {
                createServerWebSocketConnection({
                    server,
                    path
                }, connection => handler.onConnection(connection));
            } catch (error) {
                console.error(error)
            }
        }
    }

　　要深入瞭解ContributionProvider，可以參考這裏。

　　然後：

new JsonRpcConnectionHandler<ILoggerClient>("/services/logger", client => {

　　我們來看看這個類的實現做了哪些事情：

export class JsonRpcConnectionHandler<T extends object> implements ConnectionHandler {
    constructor(
        readonly path: string,
        readonly targetFactory: (proxy: JsonRpcProxy<T>) => any
    ) { }

    onConnection(connection: MessageConnection): void {
        const factory = new JsonRpcProxyFactory<T>(this.path);
        const proxy = factory.createProxy();
        factory.target = this.targetFactory(proxy);
        factory.listen(connection);
    }
}

　　我們看到，這裏通過ConnectionHandler類的擴展創建了一個websocker連接，路徑是"/services/logger"。

　　讓我們來看看這個onConnection具體做了什麼：

onConnection(connection: MessageConnection): void {
        const factory = new JsonRpcProxyFactory<T>(this.path);
        const proxy = factory.createProxy();
        factory.target = this.targetFactory(proxy);
        factory.listen(connection);

　　我們一行一行來看：

const factory = new JsonRpcProxyFactory<T>(this.path);

　　上面這一行在路徑"/services/logger"上創建了一個JsonRpcProxy。

const proxy = factory.createProxy();

　　然後，我們從工廠創建了一個代理對象，它將使用ILoggerClient接口來調用JSON-RPC連接的另一端。

factory.target = this.targetFactory(proxy);

　　上面這一行將調用我們在參數中傳遞的函數，所以：

client => {
            const loggerServer = ctx.container.get<ILoggerServer>(ILoggerServer);
            loggerServer.setClient(client);
            return loggerServer;
        }

　　這裏在loggerServer上設置客戶端，本例中它用於向前端發送有關日誌更改的通知。

　　同時它返回loggerServer，用作在JSON-RPC上公開的對象。

factory.listen(connection);

　　上面這一行將工廠連接到Connection。

　　帶有services/*路徑的endpoints由webpack開發服務器提供，參見webpack.config.js：

'/services/*': {
        target: 'ws://localhost:3000',
        ws: true
    },

連接到服務

　　現在我們已經有了一個後端服務，讓我們來看看如何從前端連接它。

　　要做到這一點，你需要像下面這樣：

（來自logger-frontend-module.ts）

import { ContainerModule, Container } from 'inversify';
import { WebSocketConnectionProvider } from '../../messaging/browser/connection';
import { ILogger, LoggerFactory, LoggerOptions, Logger } from '../common/logger';
import { ILoggerServer } from '../common/logger-protocol';
import { LoggerWatcher } from '../common/logger-watcher';

export const loggerFrontendModule = new ContainerModule(bind => {
    bind(ILogger).to(Logger).inSingletonScope();
    bind(LoggerWatcher).toSelf().inSingletonScope();
    bind(ILoggerServer).toDynamicValue(ctx => {
        const loggerWatcher = ctx.container.get(LoggerWatcher);
        const connection = ctx.container.get(WebSocketConnectionProvider);
        return connection.createProxy<ILoggerServer>("/services/logger", loggerWatcher.getLoggerClient());
    }).inSingletonScope();
});

　　其中最重要的幾行：

bind(ILoggerServer).toDynamicValue(ctx => {
        const loggerWatcher = ctx.container.get(LoggerWatcher);
        const connection = ctx.container.get(WebSocketConnectionProvider);
        return connection.createProxy<ILoggerServer>("/services/logger", loggerWatcher.getLoggerClient());
    }).inSingletonScope();

　　我們一行一行來看：

const loggerWatcher = ctx.container.get(LoggerWatcher);

　　這一行創建了一個監聽器，它通過loggerWatcher客戶端從後端獲取有關事件的通知（loggerWatcher.getLoggerClient()）。

　　想要了解更多有關事件如何在theia中工作的信息，可以查看這裏。

const connection = ctx.container.get(WebSocketConnectionProvider);

　　上面這一行獲得了一個websocket連接，它將被用來創建一個代理。

return connection.createProxy<ILoggerServer>("/services/logger", loggerWatcher.getLoggerClient());

　　我們將一個本地對象作爲第二個參數傳入，用來處理來自遠程對象的JSON-RPC消息。有時，本地對象依賴於代理，在代理實例化之前無法實例化。這種情況下，代理接口應該實現JsonRpcServer，而本地對象應該作爲客戶端來提供。

export type JsonRpcServer<Client> = Disposable & {
    setClient(client: Client | undefined): void;
};

export interface ILoggerServer extends JsonRpcServery<ILoggerClient> {
    // ...
}

const serverProxy = connection.createProxy<ILoggerServer>("/services/logger");
const client = loggerWatcher.getLoggerClient();
serverProxy.setClient(client);

　　所以，在最後一行，我們將ILoggerServer接口綁定到JsonRpc代理。

　　注意底層的調用：

createProxy<T extends object>(path: string, target?: object, options?: WebSocketOptions): T {
        const factory = new JsonRpcProxyFactory<T>(path, target);
        this.listen(factory, options);
        return factory.createProxy();
    }

　　這個和後端的例子很像。

　　也許你也注意到了，就連接而言，這裏前端是服務器而後端是客戶端，但對我們的邏輯來說這並不重要。

　　這裏還有幾點：

• 在路徑"logger"上創建JsonRpc代理。
• 公開loggerWatcher.getLoggerClient()對象。
• 返回ILoggerServer類型的代理。

　　現在，ILoggerServer的實例通過JSON-RPC被代理到後端的LoggerServer對象。

在示例的前端和後端加載模塊

　　現在我們已經有了這些模塊，我們需要將它們引入到我們的示例中。我們將使用瀏覽器作爲示例，在electron中代碼是相同的。

後端

　　在examples/browser/src/backend/main.ts中，你需要像這樣來引用：

import { loggerServerModule } from 'theia-core/lib/application/node/logger-server-module';

　　然後將其載入到主容器。

container.load(loggerServerModule);

前端

　　在examples/browser/src/frontend/main.ts中，你需要像這樣來引用：

import { loggerFrontendModule } from 'theia-core/lib/application/browser/logger-frontend-module';

container.load(frontendLanguagesModule);

完成示例

 　　如果你想查看本文中提到的完整示例，可以查看這裏的commit。

 

原文地址：https://theia-ide.org/docs/json_rpc