通用配置

通用配置是指 node-ral 框架提供的基础配置属性，用于描述服务，阅读此章节前请先了解 node-ral 的 配置系统

protocol

设置 node-ral 与后端服务器的请求协议，目前内置有 http 与 soap 协议

https 协议可通过设置请求协议为 http 并且添加 https: true 配置

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

pack

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

form
formdata
json
querystring
string
raw
stream

更详细的说明可以阅读数据格式

 module.exports.DEMO = {
	 pack: 'querystring'
 }

unpack

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

form
formdata
json
querystring
string
raw

更详细的说明可以阅读数据格式

 module.exports.DEMO = {
	 unpack: 'json'
 }

encoding

编码配置。由于Node.js中字符串只支持 utf-8 编码格式，因此如果服务端的编码格式不是 utf-8 时，在 Node.js 中作为字符串使用前均需要进行编码转换工作。node-ral 使用 iconv-lite 扩展了 Node.js 的编码格式，使其支持GBK。

具体的支持格式可以参考 https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings

 module.exports.DEMO = {
	 encoding: 'utf-8'
 }

balance

负载均衡配置，当存在多个后端 server 配置时，会通过负载均衡策略选择其中一台后端服务器发起请求。目前支持的负载均衡策略有

random

随机调度，将外部请求按顺序发送到后端 server 中随机选取的一台服务器上
roundrobin

轮叫调度，将外部请求按顺序轮流分配到 server 中的服务器上
hashring

一致性哈希策略，适用于后端缓存敏感的业务，要求请求参数中添加 balanceKey 参数

 module.exports.DEMO = {
	 balance: 'roundrobin'
 }

timeout

设置请求的超时时间，单位为毫秒。目前还未支持细化超时策略，如独立的连接超时、请求读超时等等。

 module.exports.DEMO = {
	 timeout: 500
 }

retry

设置请求失败后的重试次数。除了数据打包异常外，连接建立阶段、写数据阶段、读数据阶段、数据解包阶段的异常都会触发重试。

 module.exports.DEMO = {
	 retry: 1
 }

server

后端服务器资源配置，用于配置后端服务真实的请求服务器

每一个后端服务器配置均需包含 host 与 port

host 不可以添加 schema 如 http:// 或 https://

module.exports.DEMO = {
	server: [
		{
			host: '1.api.example.com',
			port: 80
		},
		{
			host: '2.api.example.com',
			port: 80
		}
	]
}

degrade

请求执行失败后，可以不返回异常，而是根据 degrade 配置，返回服务降级后的数据。

module.exports.DEMO = {
    degrade: {
        name: 'node-ral'
    }
}

这样在请求失败后，就会将 {name: 'node-ral'} 返回至数据使用方。

为了应对降级数据的动态需求，degrade 可以配置为一个函数，conf 参数会提供 node-ral 发起请求时的所有信息用于用户编写动态的降级策略。

module.exports.DEMO = {
    degrade: function (conf) {
        if (conf.path = '/test') {
            return {
                path: 'test'
            }
        } else {
            ...
        }
    }
}

includeExtras

extras 数据会包含一些返回数据以外的额外数据，如 HTTP 协议中的 headers 与 statusCode。extras 数据默认会以 function (data, extras) 的形式返回，通过 includeExtras 配置，可以将 extras 数据放在 data 中返回，默认会设置到 data._extras。

自定义处理时，建议 unpack 设置为 raw 或 json，如果设置为 string 会导致 extrasKey 无法注入。

module.exports.DEMO = {
    includeExtras: true,
    ...
}

extrasKey

为了避免 includeExtras 与原始数据造成冲突，通过 extrasKey 可以自定义在 data 中的键值。

module.exports.DEMO = {
    includeExtras: true,
    extrasKey: 'customExtrasKey'
    ...
}

这样设置后，extras 数据就会在 data.customExtrasKey 中返回。

customLog

为了进一步丰富 RAL 提供的日志信息，RAL 提供 customLog 配置自定义更丰富的日志信息，用户可以从请求参数、返回值、返回头信息中记录自己希望记录的信息

module.exports.DEMO = {
    customLog: {
        'tracecode': 'responseContext.extras.headers.tracecode',
        'logid': 'requestContext.headers.x_bd_logid'
    },
    ...
}

requestContext 为用户调用 RAL 时的请求参数，responseContext为响应信息，请求成功时， responseContext.body 为响应数据，responseContext.extras 为各个请求协议的额外请求信息，如 HTTP 协议中的响应头 headers 等。