内置支持

node-ral 内置了一些通用的请求协议与数据格式方便即装即用

请求协议

HTTP协议

用于向后端发起http请求

module.exports.DEMO = {
    protocol: 'http'
}

此外http请求协议支持额外配置 https 属性来实现 https 请求

module.exports.DEMO = {
    protocol: 'http',
    https: true // 设置为https请求,
    rejectUnauthorized: false // 设置不进行SSL验证,
    key: fs.createReadFileStream('./key.pem'), // 添加key, 目前尚不支持
    cert: fs.createReadFileStream('./cert.pem') // 添加cert, 目前尚不支持
}

http请求协议还实现了一部分私有配置用于处理http请求

HTTP配置

method

配置http请求的 method，如 GET , POST 等

path

配置http请求的 path，要求以 / 开头，path 设置会用于后端 url 生成

module.exports.DEMO = {
    protocol: 'http',
    path: '/demo',
    server: [
        {
            host: 'api.example.com',
            port: 80
        }
    ] 
}

// url: http://api.example.com/demo

query

配置http请求的 query，值可以是一个 Object 也可以是一个字符串，更加推荐使用 Object 来定义 query，query 设置会用于后端 url 生成

module.exports.DEMO = {
    protocol: 'http',
    path: '/demo',
    query: {
        foo: 'bar'
    }
    server: [
        {
            host: 'api.example.com',
            port: 80
        }
    ] 
}

// url: http://api.example.com/demo?foo=bar

headers

配置http请求的 request headers，属性要求为一个对象

module.exports.DEMO = {
    protocol: 'http',
    headers: {
        'Cookie': 'foo=bar',
        'x-client-name': 'ral'
    }
}

url

直接要求 RAL 无视 server 配置访问指定的 URL (不处理302)

module.exports.DEMO = {
    url: 'http://www.baidu.com/search/error.html',
    rejectUnauthorized: false
}

更多示例可以参考https://github.com/fex-team/node-ral/tree/master/example/http-demo

SOAP协议

用于向后端发起soap请求

module.exports.DEMO = {
    protocol: 'soap',
    pack: 'raw',
    unpack: 'raw'
}

soap请求协议的 pack 与 unpack 类型均需设置为 raw，这是因为在soap协议实现中，其数据打包解包是与请求协议紧耦合的。

soap请求协议还实现了一部分私有配置用于处理soap请求

SOAP配置

method

配置soap请求 SOAP method ，即 soap 服务调用方法

ral('soap', {
    data: {},
    method: 'getDemo'
});

path

配置soap服务的 wsdl 地址

module.exports.DEMO = {
    protocol: 'http',
    path: '/services/demo?wsdl',
    server: [
        {
            host: 'api.example.com',
            port: 80
        }
    ] 
}

// wsdl url: http://api.example.com/services/demo?wsdl

headers

配置soap请求的headers

module.exports.DEMO = {
    protocol: 'http',
    path: '/services/demo?wsdl',
    headers: [{
        soapXmlns: 'http://example.com',
        data: {
            AuthenticationToken: {
                username: 'hello',
                password: 'world'
            }
        }
    }]
}

更多示例可以参考https://github.com/fex-team/node-ral/tree/master/example/soap-demo

Redis协议

node-ral 封装了 Redis 协议，需要与 Redis 数据格式结合使用

示例：

module.exports.redis = {
    protocol: 'redis',
    pack: 'redis',
    unpack: 'redis',
    balance: 'random',
    protocol: 'redis',
    servers: [{host: '127.0.0.1', port: 6379}]
};

请求 Redis

ral('redis', {
    data: {
        'key': 'a',
        'value': 'b'
    },
    method: 'set'
});

对于无法用 key, value 表达的复杂命令，也可以使用数组来传递参数

// 等价于 ZADD myzset 1 "one"
ral('redis', {
    data: ['myzset', '1', 'one'], 
    method: 'zadd'
});

数据格式

node-ral 支持多种数据格式，大部分数据格式都实现了打包与解包功能，主要用于通用配置中 pack 与 unpack 的设置

示例:

module.exports.DEMO = {
    protocol: 'http',
    method: 'POST',
    pack: 'form',
    unpack: 'json'
}

pack

设置请求数据的打包格式，目前内置的打包格式有

form

将数据按照 application/x-www-form-urlencoded 编码打包，一般用于HTTP POST。

form会设置headers属性，添加 Content-Type 为 application/x-www-form-urlencoded

ral('DEMO', {
    data: {a: 1}
});

// request body: a=1

formdata

将数据按照 multipart/form-data 编码打包，一般用于HTTP POST上传文件。对象可以是文件Stream或Buffer。

formdata会设置headers属性，添加 Content-Type 为 multipart/form-data

ral('DEMO', {
    data: {
        a: 1,
        b: new Buffer('form data')
    }
});

// request body

----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="a"

1
----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="b"
Content-Type: 


----WebKitFormBoundaryE19zNvXGzXaLvS5C

更多示例可以参考 https://github.com/fex-team/node-ral/tree/master/example/formdata-demo

json

将数据按照 json 格式打包

ral('DEMO', {
    data: {a: 1}
});

// request body: {"a": 1}

querystring

querystring 数据格式比较特殊，在这个数据格式下，并不会为请求body添加任何数据，而是会将 data 合并至 query，在HTTP请求协议下，querystring 格式的数据就会以 query 的形式拼接至请求URL中

ral('DEMO', {
    data: {a: 1},
    query: {foo: 'bar'}
});

// url: www.example.com/api/demo?foo=bar&a=1 

更多示例可以参考 https://github.com/fex-team/node-ral/tree/master/example/baidumap

string

将数据作为字符串处理

ral('DEMO', {
    data: 'whatever'
});

// request body: whatever

raw

声明数据无需任何处理，直接将传入的 data 直接作为 request body 传递至请求协议

ral('DEMO', {
    data: new Buffer('raw buffer')
});

// request body: [Buffer]

stream

声明数据格式为 Stream，只要请求协议支持流式数据，node-ral 就会将数据 pipe 至请求协议，可以用于 API Proxy 等场景

function (req, res, next) {
    ral('DEMO', {
        data: req
    });
}

// request body: req stream

更多示例可以参考 https://github.com/fex-team/node-ral/tree/master/example/stream-demo

unpack

设置服务端返回数据的解包格式，目前内置的解包格式有

form

将数据按照 application/x-www-form-urlencoded 格式解包，一般服务端不会访问这种类型的数据

// response: a=1

data = {a: 1}

formdata

不支持

json

将数据按照 json 格式解包

// response: {"a": 1}

data = {a: 1}

更多示例可以参考 https://github.com/fex-team/node-ral/tree/master/example/baidumap

querystring

与 form 表现一致

string

将数据按照 string 格式解包，与 raw 的区别在于能够处理字符编码问题，并且一般协议返回的均是二进制 Buffer 而非字符串，需要手动进行 toString() 处理

// response: {"a": 1}

data = '{"a": 1}'

raw

直接返回服务端返回的二进制数据

// response: [Buffer]

data = [Buffer]

stream

将服务端返回的数据封装为 Stream 进行返回

// response: [Buffer]

data = [Stream]

目前 node-ral 会在接收完服务器所有数据后才会将数据整体推送至解包协议，这样的影响是虽然服务端数据可以用 Stream 读取，但是处理过程并不是流式的。有待后续改进。

更多示例可以参考 https://github.com/fex-team/node-ral/tree/master/example/stream-demo