QML Book 第十一章网络 2

11.5 REST API

要使用网络服务，我们首先需要创建一个。我们将使用 Flask（http://flask.pocoo.org）一个基于 python 的简单的 HTTP 应用服务器来创建一个简单的彩色 Web 服务。我们还可以使用接受并返回 JSON 数据的其他所有 Web 服务器。具体的想法是具有可以通过 Web 服务进行管理的命名颜色列表。在这种情况下管理是指 CRUD（create-read-update-delete）。

Flask 中的一个简单的 Web 服务可以写在一个文件中。我们从空的 server.py 文件开始。在这个文件中，我们创建了一些 boiler-code，并从外部 JSON 文件加载了我们的初始颜色。另请参阅 Flask 快速入门文档。

from flask import Flask, jsonify, request
import json

colors = json.load(file('colors.json', 'r'))

app = Flask(__name__)

# ... service calls go here

if __name__ == '__main__':
    app.run(debug = True)

当我们运行此脚本时，它将提供一个 http://localhost:5000 的 Web 服务器，但是目前它不提供任何有用的东西。

我们现在将开始将我们的 CRUD（创建，读取，更新，删除）端点添加到我们的小型 Web 服务中。

11.5.1 读取请求

要从我们的 Web 服务器读取数据，我们将为所有颜色提供 GET 方法。

@app.route('/colors', methods = ['GET'])
def get_colors():
    return jsonify( { "colors" :  colors })

这将返回 “/colors” 端点下的颜色。为了测试这个功能，我们可以使用 curl 创建 http 请求。

curl -i -GET http://localhost:5000/colors

这将把我们的颜色列表作为 JSON 数据返回给我们。

11.5.2 读取条目

要按名称读取单个颜色，我们提供位于 “/colors/” 下方的详细信息终点。该名称是端点的参数，用于标识单个颜色。

@app.route('/colors/', methods = ['GET'])
def get_color(name):
    for color in colors:
        if color["name"] == name:
            return jsonify( color )

我们可以再次使用curl来测试它。例如获取红色条目：

curl -i -GET http://localhost:5000/colors/red

它将返回一个颜色条目作为 JSON 数据。

11.5.3 创建条目

到目前为止，我们刚刚使用 HTTP GET 方法。要在服务器端创建一个条目，我们将使用 POST 方法，并使用 POST 数据传递新的颜色信息。端点位置与获取所有颜色相同。但是这次我们期待一个 POST 请求。

@app.route('/colors', methods= ['POST'])
def create_color():
    color = {
        'name': request.json['name'],
        'value': request.json['value']
    }
    colors.append(color)
    return jsonify( color ), 201

Curl 具有足够的灵活性，允许我们提供 JSON 数据作为 POST 请求中的新条目。

curl -i -H "Content-Type: application/json" -X POST -d '{"name":"gray1","value":"#333"}' http://localhost:5000/colors

11.5.4 更新条目

要更新信息条目，我们使用 PUT HTTP 方法。端点与检索单个颜色条目相同。当颜色更新成功时，我们将更新的颜色作为 JSON 数据返回。

@app.route('/colors/', methods= ['PUT'])
def update_color(name):
    for color in colors:
        if color["name"] == name:
            color['value'] = request.json.get('value', color['value'])
            return jsonify( color )

在 curl 请求中，我们仅提供要作为 JSON 数据更新的值和命名的端点，以标识要更新的颜色。

curl -i -H "Content-Type: application/json" -X PUT -d '{"value":"#666"}' http://localhost:5000/colors/red

11.5.5 删除条目

使用 DELETE HTTP 动词删除条目。它也为单个颜色使用相同的端点，但这次是 DELETE HTTP 动词。

@app.route('/colors/', methods=['DELETE'])
def delete_color(name):
    success = False
    for color in colors:
        if color["name"] == name:
            colors.remove(color)
            success = True
    return jsonify( { 'result' : success } )

该请求看起来类似于单个颜色的 GET 请求。

curl -i -X DELETE http://localhost:5000/colors/red

现在我们可以读取所有颜色，读取指定颜色，创建新的指定颜色，更新指定颜色和删除指定颜色。我们也知道我们的 API 的 HTTP 端点。

活动	HTTP	端点
读取全部	GET	http://localhost:5000/colors
创建条目	POST	http://localhost:5000/colors
读取条目	GET	http://localhost:5000/colors/
更新条目	PUT	http://localhost:5000/colors/
删除条目	DELETE	http://localhost:5000/colors/

我们的小 REST 服务器现已完成，我们可以专注于 QML 和客户端。要创建易于使用的 API，我们需要将每个操作映射到单个 HTTP 请求，并为用户提供简单的 API。

11.5.6 客户端 REST

为了演示一个 REST 客户端，我们编写一个小的颜色网格。颜色网格通过 HTTP 请求显示从 Web 服务检索的颜色。我们的用户界面提供以下命令：

Get color list
Create color
Read last color
Update last color
Delete last color

我们将 API 绑定到一个名为 colorservice.js 的 JS 文件中，并将其导入到我们的 UI 中作为服务。在服务模块中，我们创建了一个帮助函数来为我们提供 HTTP 请求：

// colorservice.js
function request(verb, endpoint, obj, cb) {
    print('request: ' + verb + ' ' + BASE + (endpoint?'/' + endpoint:''))
    var xhr = new XMLHttpRequest();
    xhr.onreadystatechange = function() {
        print('xhr: on ready state change: ' + xhr.readyState)
        if(xhr.readyState === XMLHttpRequest.DONE) {
            if(cb) {
                var res = JSON.parse(xhr.responseText.toString())
                cb(res);
            }
        }
    }
    xhr.open(verb, BASE + (endpoint?'/' + endpoint:''));
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.setRequestHeader('Accept', 'application/json');
    var data = obj?JSON.stringify(obj):''
    xhr.send(data)
}

它需要四个参数。verb 定义要使用的 HTTP 动词（GET，POST，PUT，DELETE）。第二个参数是用作 BASE 地址的后缀的端点（例如 “http://localhost:5000/colors”）。第三个参数是可选的 obj，将作为 JSON 数据发送到服务器。当响应返回时，最后一个参数定义要调用的回调。回调接收到具有响应数据的响应对象。在我们发送请求之前，我们指出我们通过修改请求头来发送和接受 JSON 数据。

使用这个请求帮助函数，我们可以实现我们之前定义的简单命令（create，read，update，delete）：

// colorservice.js
function get_colors(cb) {
    // GET http://localhost:5000/colors
    request('GET', null, null, cb)
}

function create_color(entry, cb) {
    // POST http://localhost:5000/colors
    request('POST', null, entry, cb)
}

function get_color(name, cb) {
    // GET http://localhost:5000/colors/
    request('GET', name, null, cb)
}

function update_color(name, entry, cb) {
    // PUT http://localhost:5000/colors/
    request('PUT', name, entry, cb)
}

function delete_color(name, cb) {
    // DELETE http://localhost:5000/colors/
    request('DELETE', name, null, cb)
}

该代码驻留在服务实现中。在 UI 中，我们使用该服务来实现我们的命令。我们有一个 ListModel，它的 id 为 gridModel，作为 GridView 的数据提供者。使用 Button ui 元素指示命令。

从服务器读取颜色列表。

// rest.qml
import "colorservice.js" as Service
...
// read colors command
Button {
    text: 'Read Colors';
    onClicked: {
        Service.get_colors( function(resp) {
            print('handle get colors resp: ' + JSON.stringify(resp));
            gridModel.clear();
            var entries = resp.data;
            for(var i=0; i

 
 在服务器上创建一个新的颜色条目。 
 // rest.qml
import "colorservice.js" as Service
...
// create new color command
Button {
    text: 'Create New';
    onClicked: {
        var index = gridModel.count-1
        var entry = {
            name: 'color-' + index,
            value: Qt.hsla(Math.random(), 0.5, 0.5, 1.0).toString()
        }
        Service.create_color(entry, function(resp) {
            print('handle create color resp: ' + JSON.stringify(resp))
            gridModel.append(resp)
        });
    }
}
 
 根据其名称读取颜色。 
 // rest.qml
import "colorservice.js" as Service
...
// read last color command
Button {
    text: 'Read Last Color';
    onClicked: {
        var index = gridModel.count-1
        var name = gridModel.get(index).name
        Service.get_color(name, function(resp) {
            print('handle get color resp:' + JSON.stringify(resp))
            message.text = resp.value
        });
    }
}
 
 根据颜色名称更新服务器上的颜色条目。 
 // rest.qml
import "colorservice.js" as Service
...
// update color command
Button {
    text: 'Update Last Color'
    onClicked: {
        var index = gridModel.count-1
        var name = gridModel.get(index).name
        var entry = {
            value: Qt.hsla(Math.random(), 0.5, 0.5, 1.0).toString()
        }
        Service.update_color(name, entry, function(resp) {
            print('handle update color resp: ' + JSON.stringify(resp))
            var index = gridModel.count-1
            gridModel.setProperty(index, 'value', resp.value)
        });
    }
}
 
 按颜色名称删除颜色。 
 // rest.qml
import "colorservice.js" as Service
...
// delete color command
Button {
    text: 'Delete Last Color'
    onClicked: {
        var index = gridModel.count-1
        var name = gridModel.get(index).name
        Service.delete_color(name)
        gridModel.remove(index, 1)
    }
}
 
 使用 REST API 来完成 CRUD（创建，读取，更新，删除）操作。还有其他可能性来生成 Web-Service API。可以是一个基于模块的，每个模块都有一个端点。 并且可以使用 JSON RPC（http://www.jsonrpc.org/）定义 API。当然，基于 XML 的 API 也是可行的，但是 JSON 方法具有很大的优势，因为解析是作为 JavaScript 的一部分直接构建到 QML/JS 中。

QML Book 第十一章 网络 2