Yiding: Created page with "（以下内容，译自:Category:Tutorials中的Web Services。更多内容可以参看:Category:Chinese。）本教程描述如何创建Web应用程序，它的前端..."

2015-08-23T09:23:43Z

Created page with "（以下内容，译自Category:Tutorials中的Web Services。更多内容可以参看Category:Chinese。）本教程描述如何创建Web应用程序，它的前端..."

New page

（以下内容，译自[[:Category:Tutorials]]中的Web Services。更多内容可以参看[[:Category:Chinese]]。）

本教程描述如何创建Web应用程序，它的前端是运行在用户浏览器中的HTML/JavaScript，而后端是用Visual Prolog编写的。

介绍的重点是Visual Prolog的后端，它实现JSON-RPC Web服务。所包含的HTML/JavaScript代码主要是为了使例子自身完整，说明前端代码如何与Visual Prolog服务互动。

教程描述了同样的服务如何才能：

* 作为独立的HTTP/HTTPS服务器运行
* 作为IIS（Microsoft Information Services微软信息服务）的ISAPI扩展嵌入式地运行

注意，web服务需要使用Visual Prolog的 '''商业版'''。
还要注意，本教程中完全没有考虑SOAP。

使用的例子是商业版中的 '''webRPC'''。 (IDE: '''Help ->Install Examples...''')。

=== 概述 ===

本节描述应用程序的整体概貌及工作方式。实际发生的事情是相当复杂的，不过好在很多复杂的东西是自动处理的。了解过程的概貌及其复杂性，就比较容易理解要做些什么及为什么这样做。

总的来说，作为例子的应用程序其工作流程是这样的：用户（在web浏览器中）浏览网页 '''http:<nowiki />//<server>/file/test.htm''' （或 '''http:<nowiki />//<server>/file/calendar.htm'''），服务器返回相应的文件给浏览器。浏览器对文件的上下文进行评估后，可能进一步请求级联的css、js文件和图片等。此外，HTML文件包含的嵌入式JavaScript代码也会对服务器产生远端过程调用 ('''RPC''')，服务器执行相应的过程并将结果返回给浏览器。最后，嵌入式的JavaScript用返回的数据更新浏览器的HTML内容。

客户机与服务器之间的通信由HTTP (或 HTTPS)协议完成。因此在服务器一侧需要一个HTTP服务器，它可以返回文件并实现远端过程调用。在 '''jsonRpcService_httpApi''' 中的程序运行该服务作为一个独立的HTT服务器，它可以处理文件请求，实现远端过程调用。'''jsonRpcService_isApi'''中的程序是用ISAPI插件来实现远端过程调用的，通过对IIS的配置来处理文件请求并对远端过程调用使用ISAPI。

独立的HTTP服务器通过微软的[http://msdn.microsoft.com/en-us/library/windows/desktop/aa364510(v=vs.85).aspx HTTP Server API]来实现，它可以共享带有IIS的端口及URL，这样一来，'''http:<nowiki />//<server>/file'''等可以进入到我们的独立服务器而'''http:<nowiki />//<server>/<something>'''也可以由IIS得到处理。

=== JSON 和 JSON-RPC ===

远端过程调用是按照[http://www.jsonrpc.org/specification JSON-RPC 2.0 Specification]规程实现的，这实际上要求数据按[http://www.json.org/ JSON] ('''J'''ava'''S'''cript '''O'''bject '''N'''otation) 格式编码。

JSON语法是JavaScript的一个子集：在对有效JSON文本进行求值时它会成为一个相应的JavaScript对象。然而，还是应该总是使用JSON解析程序而不是对该文本求值：因为文本更可能是“代码”而不是“数据”，所以对文本求值有安全上的风险。

不需要对JSON格式有详细的了解，因为在客户端一侧使用的是JavaScript而在服务器一侧使用的是JSON的对象/域表示方式，（对JSON格式的）解析和编写都可以交给标准软件去做。

执行JSON-RPC调用时，客户端发送一个JSON请求对象，服务器用一个JSON响应对象做响应，除非请求是一个'''notification（通知）'''，此时不需要响应。

请求对象有四个成员：
* <vp>jsonrpc</vp>: 一个说明JSON-RPC协议版本的串，必须就是 "2.0"。
* <vp>method</vp>: 一个包含被调用方法名称的串。
* <vp>params</vp>: 该方法的参数（如果方法不带参数就省略）。
**by-position: 一个JSON数组，包含有按服务器要求顺序排列的值。
**by-name: 一个带有成员名称的JSON对象，成员名称要严格与方法所期望的参数相匹配，包括大小写都要一致。
* <vp>id</vp>: 一个由客户端创建的标识该请求的串或数。如果是通知则这个域就省掉了。

响应对象有三个成员：
* <vp>jsonrpc</vp> 一个说明JSON-RPC协议版本的串，必须就是 "2.0"。
* <vp>id</vp> 由客户端发布的值。
第三个成员是下列之一：
* <vp>result</vp> （意味着该调用成功了）程序调用的结果
* <vp>error</vp> （意味着该调用失败了）一个描述所发生错误的对象

=== 客户端一侧 ===

{{例|这段代码演示了在客户端一侧进行一次过程调用的方法：
<source lang="JavaScript">
function httpPOST(URL, method, params) {
var ReqObj = { jsonrpc: "2.0", id: getId(), method: method, params: params };
var Req = JSON.stringify(ReqObj);
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("POST", URL, false);
xmlHttp.setRequestHeader('Content-Type', 'application/json-rpc; charset=UTF-8');
xmlHttp.send(Req);
var resp = xmlHttp.responseText;
var respObj = JSON.parse(resp);
var error = respObj.error;
if (error) {
if (Data = error.data) {
log("<pre>" + Data +"</pre>\n");
}
log("<p>error : "+ error.code +": " + error.message + "</p>\n");
} else {
// respObj.result contains the result
}
}</source>
小结一下：
* 创建一个请求对象Create a request object
* 由JSON将其 "串化（stringify）"
* 用一个XMLHttpRequest对象发布它
* JSON解析响应文本
* 对 "error" 成员进行检查
}}

有很多其它的方法来写客户端一侧的代码，通常会使用一些标准的JavaScript库程序包，这些包可以异步处理错误及执行调用。 '''calendar.htm''' 使用了这样的库代码，不过这些内容超出了本教材的范围。

=== 服务代码 ===

在Visual Prolog中JSON是由域<vp>json::jsonValue</vp>来表示的：

<vip>domains
jsonValue =
n; % null
f; % false
t; % true
r(real Number);
s(string String);
a(jsonValue* Array);
o(jsonObject Object).</vip>

JSON值只有7类：null、false、true、数、串、数组、对象。

数组是一个JSON值的序列，用Visual Prolog的表来表示。

JSON对象由Visual Prolog的 <vp>jsonObject</vp> 接口表示：

<vip>interface jsonObject supports mapM{string Key, jsonValue Value}
...
end interface jsonObject</vip>

该接口含有一些便利的谓词/属性（这些上面都没有说到），不过从本质上来说<vp>jsonObject</vp>不过就是从Key（名称）到JSON值之间的映射。

{{例|以下代码：
<vip>J = jsonObject::new(),
J:set_boolean("bbb", true),
J:set_string("sss", "The String"),
J:writeTo(stdio::outputStream),
stdio::nl,
jsonPrettyPrint::ppObject(stdio::outputStream, J)</vip>
会生成如下输出：
<source lang="text">{"bbb":true,"sss":"The String"}
{
"bbb" : true,
"sss" : "The String"
}</source>
<vp>writeTo</vp> 压缩生成一种适用于进程间通信等的 JSON 表示。 <vp>jsonPrettyPrint</vp> 可用良好的格式（比如调试时用）打印该值。
}}

创建 RPC 服务时，必须实现一个支持<vp>rpcService</vp>接口的对象：

<vip>interface testService supports rpcService
end interface testService

class testService : testService
end class testService</vip>

在该实现中，需要继承处理JSON解析、编写等的<vp>jsonRpcServiceSupport</vp>：

<vip>implement testService
inherits jsonRpcServiceSupport
open core, json
...

end implement testService</vip>

还需要在构造器中注册你的过程：

<vip>clauses
new() :-
setProc_name("hello", hello),
setProc_name("calendar", calendar).</vip>

过程有四类，相应于不同的注册谓词：There are four kinds of procedures, with corresponding registration predicates:

* <vp>setProc_array</vp> 用于注册将参数放在数组中的过程
* <vp>setProc_name</vp> 用于注册在对象中使用命名参数的过程
* <vp>setListener_array</vp> 用于注册将参数放在数组中的通知监听器
* <vp>setListener_name </vp> 用于注册在对象中使用命名参数的通知监听器

在上面的例子中，有两个过程“hello”和“calendar”，都是使用命名参数。 hello 的代码可以是这样的：

<vip>constants
testService_error : jsonRpcError::serverErrorCode = jsonRpcError::serverError_last+1.
% 从last开始增加，last是用于未指明的服务器错误

predicates
hello : jsonProc_name.
clauses
hello(_Context, ArgMap) = o(Result) :-
Result = jsonObject::new(),
Username = ArgMap:get_string("username"),
if "error" = Username then
raise_serviceError(testService_error, "'error' is an invalid user name")
elseif "userError" = Username then
exception::raise_user("'%Name%' is an invalid user name", [namedValue("Name", string(Username))])
elseif "definiteUserError" = Username then
exception::raise_definiteUser("'%Name%' is an invalid user name", [namedValue("Name", string(Username))])
else
Result:set_string("token", string::concat("Hello ", Username))
end if.</vip>

<vp>hello</vp>过程首先创建一个<vp>jsonObject</vp>用于<vp>Result</vp>。任意 JSON 值都可以当成结果，不过 <vp>hello</vp> 设计为返回带一个<vp>"token"</vp>成员的JSON对象。

接下来它由<vp>ArgMap</vp>获取参数，要的是一个名为<vp>"username"</vp>的串参数。

<vp>hello</vp> 使用 <vp>Username</vp> 的值来说明异常处理与成功。

<vp>"error"</vp>一段演示如何引发“服务器错误”，它是用于RPC服务的特别设计的错误消息。“userError”和“definiteUserError”情况说明的是该过程调用时除其它异常外可能发生的异常。

要注意，客户端代码要编程处理相应的错误。当然服务器一侧也可以在任意其它程序中处理指定的异常，也可以在适当地方记录这些错误。

错误不是 <vp>Username</vp> 的情况，映射 "token" 串给 <vp>Result</vp>。

{{例|建议 <vp>jsonProc</vp> 只做参数提取与结果构造，而使实际功能在分开的事务层中，如下面这段代码演示的：
<vip>predicates
hello : jsonProc_name.
clauses
hello(_Context, ArgMap) = o(Result) :-
Result = jsonObject::new(),
Username = ArgMap:get_string("username"),
Token = businessLayer::hello(Username), % 实际功能在分开的事务层中
Result:set_string("token", Token).</vip>}}

=== 独立的 HTTP 服务器 ===

如同上面 <vp>jsonRpcService_httpApi</vp> 程序演示的，<vp>testService</vp>（支持 <vp>rpcService</vp>）可以用于独立的 HTTP 服务器，不需要多少代码，而且为适合特殊需要而做的代码调整也很简单。但不管怎么样，也还是相当复杂的。

该服务器基于微软能与IIS很好配合的[http://msdn.microsoft.com/en-us/library/windows/desktop/aa364510(v=vs.85).aspx HTTP Server API]。其实，IIS好像是构建在该 HTTP Server API 的顶层（或起码它们两者都是构建在共同基础之上的）。

HTTP Server api 与以下实体打交道：
* 创建器/构造器的进程
* Server会话
* URL组
* Request队列
* Worker进程

创建器/构造器进程创建服务器会话，由其定义URL组及请求队列。worker进程与请求队列相关联，处理队列接收到的请求。

在示例程序中创建器/构造器是仅有的worker进程，更复杂的情形超出了本教材的范围。

服务器会话是URL组及请求队列的所有者/持有者，它们才是我们需要实际考虑的。

URL组是由URL模型集定义的，其形式为：
:'''http:<nowiki />//<host>:<port>/<relativeURI>'''
:'''https:<nowiki />//<host>:<port>/<relativeURI>'''

一个请求到达计算机时，一种匹配机制会按照活动的URL组中URL模型集对其进行匹配，结果要不是匹配不上就是覆盖该URL。

每个URL组分配一个请求队列，与某个URL组匹配的请求就放入其相应的队列。那些没有分配请求队列的URL组是非活动的，不参加匹配。

Worker进程从请求队列中取出请求并进行处理。一个请求队列可以与若干个URL组相联系，而每个URL组又可以有若干URL模型。因此，worker进程由某个请求队列摘出的请求可以会匹配与该队列联系的某个URL组的某个URL模型。

在示例服务器中，我们创建了两个请求队列，每个都只有一个URL组与之联系，并且每个URL组也只有一个URL模型。事实上：
* <vp>reqQueue_rpc</vp> 接收来自 '''http:<nowiki/>//localhost:5555/jsonrpc/<something>'''的请求，而
* <vp>reqQueue_file</vp> 接收来自'''http:<nowiki/>//localhost:5555/file/<something>''''的请求。

<vp>reqQueue_rpc</vp> is a <vp>requestQueue_rpc</vp> handles RPC requests by feeding them to our <vp>testService</vp>.

<vp>reqQueue_file</vp>是一个<vp>requestQueue_file</vp>，它用 <vp>fileMapper</vp>映射该请求到一个文件名及相应的<vp>ContentType</vp>，<vp>requestQueue_file</vp>接下来就会处理该文件的传输。

==== 服务器配置：netsh ====

上面的示例运行很平稳，因为它使用的是宿主机5555端口。然而一般情况下运行应用程序会要求http的使用80端口、https的使用443端口，这时就会出现一些安全性问题。

如果仅只是更换端口号并使用公共宿主机名，在给URL组添加URL模型时服务器程序将会得到一个 'Access is denied'（拒绝访问）的异常。

如果"as Administrator"来运行服务器则不会产生访问违例。但这绝对是不值得提倡的，因为这样一来它也有了做某些有害事情的权力。

要使程序运行于普通模式，必须要对运行服务器程序的用户保留上面讨论的URL模型。

使用netsh.exe (net shell)程序可以完成这个工作。 program.这将会需要处理http URL acl。详细内容参见 [http://msdn.microsoft.com/en-us/library/windows/desktop/cc307236(v=vs.85).aspx Netsh commands for HTTP].

{{例|演示在命令行提示符下的工作：
<source lang="text">>netsh http add urlacl http://www.something.com:80/file/ user=SMT\serviceuser
>netsh http add urlacl http://www.something.com:80/jsonrpc/ user=SMT\serviceuser</source>
'''注意''' 要做修改需使命令行提示符运行于"as Administrator"。
如果仅写 "netsh" 就会进入http模式的提示符模式，只是写http命令。
<source lang="text">>netsh
netsh>http
netsh http>add urlacl http://www.something.com:80/file/ user=SMT\serviceuser
netsh http>add urlacl http://www.something.com:80/jsonrpc/ user=SMT\serviceuser
netsh http>exit</source>}}

通过Visual Prolog来进行URL保留也是可以的，但为了防止冲突及其它一些问题，最好还是使用标准netsh程序。

注意示例是个控制台程序。在大规模应用情况下设计一个通用窗口服务会更好些。Visual Prolog有工程模板用于创建服务，但这超出了本教材的范围。

=== IISAPI插件 ===

如同 <vp>jsonRpcService_isApi</vp> 程序所演示的那样，<vp>testService</vp>（支持<vp>rpcService</vp>)也可以ISAPI dll的形式来应用。该DLL可以由IIS使用来运行RPC请求。

<vp>jsonRpcService_isApi</vp> 不处理文件请求，更自然的办法是把它留给IIS本身。该DLL代码其实不复杂，关键是IIS的配置。

IIS配置有专门教材，参见[[IIS configuration]]。

=== GUI程序 ===

在'''webRPC'''示例目录中还有一个<vp>jsonRpcService_httpGUI</vp>程序，它演示了图形用户界面程序如何用作独立Web RPC服务。要注意，并不提倡实际的服务程序具有GUI。这只是说明，当需要其它程序与GUI程序交互时GUI很有用，比如当用户登录时。它也可以用作一种快速借用已有GUI代码用于Web服务的方法（比如在创建实际服务前的试验）。

=== 多线程 ===

不管web服务如何运行（独立的带或不带GUI、或是ISAPI），需要注意的是HTTP请求运行于并发的若干线程。所以，保证请求处理的线程安全是很重要的。<vp>requestQueue_rpc::synchronizer</vp>属性可用于同步RPC的执行，这个属性可以由一个谓词进行设置接收<vp>runnable</vp>，而<vp>runnable</vp>时才实际执行RPC调用。可运行的程序可以是，比如在一个监控程序（monitor）下运行，以此来保证这个时间只有一个程序在运行；或者是放入一个队列并从中顺序执行；再或者是如 <vp>jsonRpcService_httpGUI</vp> 那样发布给GUI队列交由GUI线程执行。

=== Visual Prolog 客户端 ===

本教材及所提及的示例主要讨论Visual Prolog服务器一侧内容，而使用web浏览器作为客户端。不过，有时Visual Prolog程序也需要作为客户端访问WEB服务。示例 <vp>jsonRpcClient</vp> 演示了如何做这样的事情。其方法与使用JavaScript时很相似：

* 创建一个带有方法名及参数的 <vp>jsonRpcRequest</vp> 对象
* 用 <vp>asString</vp> 对其进行JSON串化
* 用 XMLHttpRequest 对象（<vp>xmlHTTP</vp> 或 <vp>xmlHTTP60</vp>的一个实例）进行投递
* JSON 解析响应文本（用<vp>jsonObject::fromString</vp>）
* 检查 "error" 成员

在示例程序中，有一个 <vp>delayCall</vp>，,它是为了使GUI得到更新。如果没有它，GUI的更新就要一直等到RPC完成。不过这个调用与RPC本身是无关的。

=== Skype HTTP/HTTPS 冲突 ===
{{:Include/SkypeHTTPConflict}}

=== HTTPS ===

HTTPS是使用安全套接的HTTP协议。IIS和独立HTTP服务器都可以使用HTTPS。要使用HTTPS，服务器计算机必须要有一个证书。可以自己创制证书，但自制的证书是不可信的，因而会引发安全提示。自制证书用于试验与开发是够用了，但在实际使用时需要获取一个可信的证书。

简单说，可信证书必须从可信提供者那里获取。这种信任基于以下三件事：
* 提供者是自身可信的
* 提供者（通过正常购买链）对证书持有者真实身份具有认知
* 提供者可以在证书被滥用时撤消证书

注意，HTTPS缺省时使用443端口（而HTTP使用80端口），需要时必须在使用"http"的地方写明 "https"（例如'''https:<nowiki />//+:443/mypath'''）

对证书的进一步讨论超出了本教材的范围。

=== 参考 ===

* [http://www.json.org/ JSON]
* [http://www.jsonrpc.org/specification JSON-RPC 2.0 Specification]
* Microsoft's [http://msdn.microsoft.com/en-us/library/windows/desktop/aa364510(v=vs.85).aspx HTTP Server API]

[[Category:Tutorials部分中文译文]]

Web Services (Web服务) - Revision history

Yiding: Created page with "（以下内容，译自:Category:Tutorials中的Web Services。更多内容可以参看:Category:Chinese。） 本教程描述如何创建Web应用程序，它的前端..."

Yiding: Created page with "（以下内容，译自:Category:Tutorials中的Web Services。更多内容可以参看:Category:Chinese。）本教程描述如何创建Web应用程序，它的前端..."