Ext Direct 规范

概述

Ext Direct 是一种平台和语言无关的远程过程调用 (RPC) 协议。Ext Direct 允许 Ext JS 应用程序的客户端与任何符合规范的服务器平台之间进行无缝通信。Ext Direct 是无状态且轻量级的，支持 API 发现、调用批处理和服务器到客户端事件等功能。

约定

本文档中使用的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”应按照 RFC 2119 中的描述进行解释。

Ext Direct 部分基于 JSON（参见 http://www.json.org 或 RFC 4627 ），并利用基于 HTML 表单的文件上传（ RFC 1867, RFC 2388 ）。

API 发现

服务器 MAY 支持通过 API 发现机制向客户端发布其 API。如果支持 API 发现，则服务器 MUST 响应预配置 URI 的 HTTP GET 请求，返回一个文档，该文档具有正确的内容类型，以便浏览器将此文档解释为 JavaScript 代码。

API 声明

服务器 API 声明 MUST 是有效的 JavaScript 代码，该代码导致创建一组嵌套的 Object，这些 Object 被分配给一个变量，该变量稍后可以传递给客户端应用程序中的 Ext Direct 初始化代码。建议该代码也符合 JSON 对象语法的更严格规则，以便非 JavaScript 实现可以尝试将 API 声明解析为 JSON。

API 声明代码示例

var Ext = Ext || {};
Ext.REMOTING_API = {
    "id": "provider1",
    "url": "ext/direct/router",
    "type": "remoting",
    "actions": {
        "Album": [{
            "name": "getAll",
            "len": 0
        }, {
            "name": "add",
            "params": ["name", "artist"],
            "strict": false
        }, {
            "name": "delete",
            "len": 1
        }]
    }
};

API 声明属性

API 声明的 JavaScript Object 必须包含以下强制属性

• url - 此 API 的服务 URI。
• type - 对于远程 API，MUST 为 remoting，对于轮询 API，MUST 为 polling。
• actions - 列出给定远程 API 的所有 Action 和 Method 的 JavaScript Object。在轮询 API 声明中 MUST 省略。

API 声明 MAY 还包含以下可选属性

• id - 远程 API 提供程序的标识符。当使用多个 API 时，这很有用。
• namespace - 给定远程 API 的命名空间。
• timeout - 在此远程 API 中用作每个 Method 调用超时时间的毫秒数。

任何其他属性都是可选的。

Action 和 Method 声明

API 声明的 actions 属性中的每个 Action 都是一个 Object 数组，这些 Object 表示 Method。Action 本身没有属性。Action 名称可以嵌套，即 Action 可以包含其他 Action 以及 Method。

Method 声明必须具有以下属性

• name - 此 Method 的名称。在其 Action 中 MUST 是唯一的。

每个 Method 都通过 Action 和 Method 名称（以点字符 (.) 连接）完全限定，并以可选的命名空间为前缀

[Namespace.]Foo.Bar.baz

其中 Foo 是外部 Action 名称，Bar 是内部 Action 名称，baz 是 Method 名称。

Method 调用约定

Method 声明必须具有以下互斥属性之一，这些属性描述 Method 的调用约定

• len - 有序 Method 所需的参数数量。对于不接受参数的 Method，此数字 MAY 为 0。
• params - 命名 Method 支持的参数数组。此数组 MAY 为空。
• formHandler - JavaScript 布尔值 true 表示此 Method 接受表单提交。

有序 Method 必须始终符合其调用约定。当为有序 Method 调用远程 Method 代理函数时，必须以完全相同的顺序提供所需的确切参数数量。如果传递的参数数量少于所需数量，则路由器 MAY 选择返回异常而不调用实际的 Method。

命名 Method MAY 使用 strict 属性来控制在调用 Method 时如何检查参数并将参数传递给服务器

• 当 strict 设置为 true 时，只有 params 数组中列出的名称的参数才会发送到服务器；任何其他参数都将被丢弃。这是默认行为。
• 当 strict 设置为 false 时，所有参数都将传递到服务器。路由器 SHOULD 将所有参数传递给实际的 Method。

如果缺少某些列出的参数，路由器 MAY 选择返回异常并省略调用实际的 Method。如果 params 数组为空且 strict 属性设置为 false，则路由器 MUST 不执行任何参数检查，并且 MUST 将所有参数传递给调用的 Method。

具有所有可选参数的命名 Method 示例

"actions": {
    "TestAction": [{
        "name": "named_no_strict",
        "params": [],
        "strict": false
    }]
}

调用元数据

Method 声明 MAY 包含可选的 metadata 属性，该属性定义 Method 接受的调用元数据的类型。如果 Method 声明中不存在 metadata 属性，则客户端 MUST 不会为该 Method 的任何调用向服务器发送调用元数据。

metadata 属性（如果存在）MUST 是一个 JavaScript 对象，具有以下属性

• len - 按位置调用元数据所需的参数数量。此数字 MUST 大于 0。
• params - 按名称调用元数据支持的名称数组。此数组 MAY 为空。
• strict - JavaScript 布尔值，用于控制如何检查调用元数据参数。

如果存在，则调用元数据参数必须符合其调用约定。调用元数据调用约定 MAY 与主 Method 参数调用约定不同，例如，有序 Method MAY 接受按名称调用元数据，或者命名 Method MAY 接受按位置调用元数据。

参数检查的执行方式与主 Method 参数相同。

一些接受调用元数据的 Method 声明示例

"actions": {
    "TestAction": [{
        "name": "meta1",
        "len": 0,
        "metadata": {
            "len": 1
        }
    }, {
        "name": "meta2",
        "len": 1,
        "metadata": {
            "params": ["foo", "bar"],
            "strict": false
        }
    }, {
        "name": "meta3",
        "params": [],
        "strict": false,
        "metadata": {
            "len": 3
        }
    }, {
        "name": "meta4",
        "params": ["foo", "bar"],
        "metadata": {
            "params": ["baz", "qux"]
        }
    }]
}

轮询 API 声明

声明轮询 API 是可选的。如果服务器实现了一个以上的事件提供程序，建议在同一 JavaScript 文档中包含轮询 API 声明以及远程 API 声明。

具有一个远程 API 和一个轮询 API 的 API 声明示例

var Ext = Ext || {};
Ext.REMOTING_API = {
    "id": "provider1",
    "type": "remoting",
    "url": "ext/direct/router",
    "actions": {
        "User": [{
            "name": "read",
            "len": 1
        }, {
            "name": "create",
            "params": ["id", "username"]
        }]
    }
};
Ext.POLLING_API = {
    "id": "provider2",
    "type": "polling",
    "url": "ext/direct/events"
};

远程函数调用

远程调用通过向服务器发送 Request 对象或多个 Request 对象来表示。Request 对象以 JSON 编码，并作为原始负载在 HTTP POST 请求中发送到 API 声明中声明为 url 的服务 URI。HTTP POST 中 MUST 不存在任何其他数据，除非包含一个或多个 Request 的有效 JSON 文档。在 POST 请求的 HTTP 标头中，MUST 包含 Content-Type 标头，其值为“application/json”。客户端 MUST 对 Request 文档使用 UTF-8 字符编码。

远程函数调用请求

Request 是一个 Object，具有以下成员

• type – MUST 是字符串“rpc”。
• tid – 此 Request 的事务 ID。在批处理中的 Request 中 MUST 是唯一的整数。
• action – 调用的 Method 所属的 Action。MUST 指定。
• method – 要调用的远程 Method。MUST 指定。
• data – 要传递给调用的远程 Method 的一组参数。对于接受 0（零）个参数的 Method，MUST 为 null；对于有序方法，MUST 为 Array；对于命名方法，MUST 为 Object。
• metadata - 可选的元参数集，如果客户端提供，则可供调用的远程 Method 使用。如果调用没有关联的元数据，则此成员 MUST 不存在于 Request 中。

有序 Method 的典型 JSON 编码 Request Object 可能如下所示

{"type":"rpc","tid":1,"action":"Foo","method":"bar","data":[42,"baz"]}

命名 Method 的典型 JSON 编码 Request 对象可能如下所示

{"type":"rpc","tid":2,"action":"Foo","method":"qux","data":{"foo":"bar"}}

具有按名称调用元数据的有序 Method 的典型 JSON 编码 Request 对象可能如下所示

{"type":"rpc","tid":3,"action":"Foo","method":"fred","data":[0],
 "metadata":{"borgle":"throbbe"}}

远程 Request MAY 可以批处理，在这种情况下，Request MUST 作为具有唯一 tid 成员的 Request 对象数组发送

[
    {"type":"rpc","tid":3,"action":"Foo","method":"frob","data":["foo"]},
    {"type":"rpc","tid":4,"action":"Foo","method":"blerg","data":["qux"]}
]

服务器 MUST 支持 Request 批处理，并且 SHOULD 尝试按相同顺序返回调用调用结果或异常。

远程响应

对远程调用的响应 MUST 包含每个 Request 的结果或异常。响应以 JSON 编码，并作为原始 HTTP 响应负载返回给客户端，Content-Type 标头为“application/json”，字符编码为 UTF-8。

如果 Request 以批处理形式发送，则服务器 MUST 仅在路由器处理完所有 Request 后才返回相应的响应，并且响应 SHOULD 遵循与原始 Request 相同的顺序。对于每个响应，原始 Request 的相应 tid 成员 MUST 由服务器不变地传递回去。

远程调用结果

结果是一个 Object，具有以下成员

• type — MUST 是字符串“rpc”。
• tid — 此响应的事务 ID。MUST 与原始 Request 中的相同。
• action — 调用的 Method 所属的 Action。MUST 与原始 Request 中的相同。
• method — 调用的远程 Method 的名称。MUST 与原始 Request 中的相同。
• result — Method 返回的数据。MUST 存在于 Response 对象中，但对于不返回任何数据的方法，MAY 为 null。

典型的 JSON 编码 Response 对象数组可能如下所示

[
    {"type":"rpc","tid":1,"action":"Foo","method":"bar","result":0},
    {"type":"rpc","tid":2,"action":"Foo","method":"baz","result":null}
]

远程调用异常

异常是一个 Object，具有以下成员

• type — MUST 是字符串“exception”。
• tid — 此响应的事务 ID。MUST 与原始 Request 中的相同。
• action — 调用的 Method 所属的 Action。MUST 与原始 Request 中的相同。
• method — 调用的远程 Method 的名称。MUST 与原始 Request 中的相同。
• message — 错误消息。MUST 存在。
• where — 可选的异常引发位置描述。MAY 包含堆栈跟踪或其他信息。

典型的 JSON 编码异常可能如下所示

{
    "type": "exception",
    "tid": 3,
    "action": "Foo",
    "method": "frob",
    "message": "Division by zero",
    "where": "... stack trace here ..."
}

远程表单提交

远程表单调用通过提交具有 HTTP POST 请求的 HTML 表单来表示。表单内容必须符合（HTML 4.01 规范）[5]。服务器 MUST 支持“application/x-www-form-urlencoded”和“multipart/form-data”内容类型以实现向后兼容性。客户端 MAY 选择仅实现“multipart/form-data”编码。

每个提交的表单 MUST 只有一个 Method 调用。对于在远程 API 中声明了表单处理程序调用约定的每个 Method，客户端 MUST 使用表单提交。

远程表单请求

表单 SHALL 包含以下字段

• extType - MUST 是字符串“rpc”。
• extTID - 此 Request 的事务 ID。在批处理中的 Request 中 MUST 是唯一的整数。
• extAction - 调用的 Method 所属的 Action。MUST 指定。
• extMethod - 要调用的远程 Method。MUST 指定。
• extUpload - 字符串化的布尔值（"true" 或 "false"），指示文件上传已附加到此表单提交。

如果给定的表单提交有关联的调用元数据，则表单 MAY 包含 metadata 字段。

除了上面列出的强制字段外，表单 MAY 包含其他字段。这些附加字段 MUST 作为命名参数传递给调用的 Method。

当表单用于上传文件时，编码类型 MUST 为“multipart/form-data”。

远程表单响应

服务器 MUST 使用 JSON 文档响应表单提交，该文档包含如 4.2.1 和 4.2.2 节中所述的有效 Response 或 Exception 对象。该文档的内容类型 MUST 为“application/json”，字符编码为 UTF-8。

远程文件上传响应

当表单请求包含一个或多个文件上传时，服务器 MUST 返回有效的 HTML 文档，该文档具有正确的内容类型，以便浏览器将此文档解释为 HTML。该文档的字符编码 MUST 为 UTF-8。

HTML 文档 MUST 包含如 4.2.1 和 4.2.2 节中所述的有效 JSON 编码 Response 或 Exception，并用 HTML <textarea> 标签括起来。

文件上传响应的示例可能如下所示

<!DOCTYPE html>
<html>
    <head>
        <title>File upload response</title>
    </head>
    <body>
        <textarea>{JSON RESPONSE HERE}</textarea>
    </body>
</html>

事件轮询

服务器可以实现可选的事件轮询机制。事件轮询是通过定期向服务器发送 HTTP GET 请求来执行的。每个服务器可以有多个事件提供者；在这种情况下，每个事件提供者必须有一个单独的服务 URI。

事件轮询请求

事件轮询请求的基本形式是向被轮询的事件提供者的服务 URI 发送 HTTP GET 请求。服务器必须为每个事件提供者维护一个活动的轮询处理方法列表，并在每次发出轮询请求时调用每个轮询处理方法。服务器可以支持通过 HTTP GET 请求 URI 向轮询处理方法传递参数，但这不是必需的。

事件轮询响应

事件轮询响应必须是一个有效的 JSON 文档，并具有正确的内容类型，以便浏览器将此文档解析为 JSON。该文档必须使用 UTF-8 字符编码。

事件轮询响应应该包含一个事件对象数组。如果没有给定请求的待处理事件，则此数组可以为空。服务器必须不得在响应数组中包含异常对象。

事件对象

事件对象必须包含以下属性

• type - 必须是字符串 "event"。
• name - 事件名称，必须是字符串。
• data - 事件数据，应该是任何有效的 JSON 数据。

一个典型的事件对象示例

{
    "type": "event",
    "name": "progressupdate",
    "data": {
        "processId": 42,
        "progress": 100
    }
}

术语

Ext Direct 使用以下术语

• 服务器 — 一种计算系统，它提供可由客户端远程执行的功能。
• 客户端 — 一种计算系统，它远程调用服务器功能并接收结果和/或异常。
• 服务器 API — 服务器 API 的描述，该 API 向客户端公开。
• API 声明 — 编码服务器 API 的 JavaScript 代码块。API 声明通常由服务器动态生成，并在启动时由客户端检索；API 声明也可以嵌入在客户端应用程序代码中。
• 远程调用 API — API 声明的主要部分，它枚举了客户端可用的服务器操作和方法，以及它们的调用约定和其他参数。
• 轮询 API — API 声明的可选的部分，可以用于声明服务器事件提供者及其凭据的存在。
• API 发现 URI — 服务器上的一个预配置 URI，客户端应向其发送 HTTP GET 请求以检索 API 声明。如果特定应用程序中未使用动态 API 发现，则此 URI 是可选的，可以省略。
• 服务 URI — 服务器上的一个预配置 URI，客户端将使用它来向路由器发送远程调用请求，或向事件提供者发送轮询请求。每个路由器或事件提供者必须发布一个对该路由器或事件提供者唯一的服务 URI。
• 命名空间 — 将在其中创建嵌套的操作对象以及相应的远程方法存根的全局对象。可选的；如果未在 API 声明中定义，则将使用默认的 window 对象。
• 操作 — 命名空间单元；方法的集合。操作可以嵌套，并且可以放置在全局命名空间中。操作可以被视为公开方法的类。
• 远程方法 — 可以由客户端远程调用的服务器功能。方法始终属于操作，并通过组合命名空间、操作和方法名称来完全限定：[Namespace.]Action.Method。
• 远程方法代理 — Ext Direct 客户端堆栈创建的代替实际方法的存根 JavaScript 函数，该实际方法仅存在于服务器上。将为每个方法创建一个单独的代理函数，其参数签名符合方法的 API 声明。
• 有序方法 — 以有序方式或按位置（如在列表中）接受零个或多个参数的远程方法。
• 命名方法 — 按名称（如在关联数组（哈希表、对象、映射）中）接受参数的远程方法。
• 表单处理方法 — 接受表单提交的远程方法。这是一种遗留机制，可用于在不符合 XMLHttpRequest Level 2 规范的浏览器中上传文件。
  对于服务器来说，实现对表单处理程序的支持是可选的；如果未提供此类支持，则服务器不得将方法声明为使用表单处理程序调用约定。
• 轮询处理程序 — 由事件提供者调用的服务器函数，用于返回事件列表，作为定期事件轮询的结果传递给客户端。
• 调用元数据 - 可选的一组额外的参数，可以传递给方法。元数据与主要参数相关，但不同，并且单独处理。一个常见的用例是传递数据库信息，例如 CRUD 操作的表名。
• 路由器 — 服务器组件，它在其服务 URI 接收远程调用函数请求，运行实际函数，并收集要返回给客户端的结果或异常。
• 事件提供者 — 服务器组件，它在其服务 URI 接收定期轮询请求，运行在此事件提供者处注册的轮询处理程序函数，收集轮询处理程序返回的事件，并将事件列表返回给客户端。
• 请求 — 客户端请求的远程方法调用，传递符合方法调用约定的参数。
• 响应 — 关于请求完成的信息。必须是结果或异常。
• 结果 — 远程方法在成功或不成功调用完成时返回的任何数据。结果是可选的，如果方法不应返回任何数据，则可以省略。
• 异常 — 应用程序代码中的致命错误、应用程序逻辑错误或其他不可恢复的事件。
• 事件 — 可以由轮询处理程序生成并传递给客户端的通知。事件对于应用程序状态更新、进度指示器以及其他可预测的条件和事件非常有用。
• 批处理 - 将多个请求组合成一个数据包发送到服务器，而不是单独发送每个请求。

参考文献

• RFC 2119
• RFC 4627
• RFC 1867
• RFC 2388