Restler 项目技术文档

1. 安装指南

安装方式

Restler 是一个用于 Node.js 的 HTTP 客户端库，简化了创建和使用 http.Client 的复杂性。要安装 Restler，请在终端中运行以下命令：

npm install restler

运行测试

安装完成后，您可以通过以下命令运行测试，以确保 Restler 正常工作：

npm test

2. 项目使用说明

Restler 提供了简单易用的接口，用于执行常见的 HTTP 请求操作。以下是一些基本的使用示例：

基本请求

var rest = require('restler');

rest.get('http://google.com').on('complete', function(result) {
  if (result instanceof Error) {
    console.log('Error:', result.message);
    this.retry(5000); // 5秒后重试
  } else {
    console.log(result);
  }
});

发送 JSON 数据

var jsonData = { id: 334 };
rest.postJson('http://example.com/action', jsonData).on('complete', function(data, response) {
  // 处理响应
});

文件上传

rest.post('https://twaud.io/api/v1/upload.json', {
  multipart: true,
  username: 'danwrong',
  password: 'wouldntyouliketoknow',
  data: {
    'sound[message]': 'hello from restler!',
    'sound[file]': rest.file('doug-e-fresh_the-show.mp3', null, 321567, null, 'audio/mpeg')
  }
}).on('complete', function(data) {
  console.log(data.audio_url);
});

3. 项目 API 使用文档

request(url, options)

基本方法，用于发起任何类型的请求。返回一个 RestRequest 对象，该对象会触发以下事件：

事件

• complete: function(result, response) - 请求完成时触发，无论成功与否。传递响应结果和响应对象作为参数。如果发生错误，result 始终是 Error 的实例。
• success: function(data, response) - 请求成功时触发。传递响应数据和响应对象作为参数。
• fail: function(data, response) - 请求成功但返回 4XX 或 5XX 状态码时触发。传递响应数据和响应对象作为参数。
• error: function(err, response) - 发生错误时触发（如连接中断、解析失败等）。传递 Error 对象和响应对象（如果可用）作为参数。
• abort: function() - 当调用 request.abort() 时触发。
• timeout: function(ms) - 当请求超时时触发。传递超时时间（毫秒）作为参数。
• 2XX, 3XX, 4XX, 5XX: function(data, response) - 根据响应状态码范围触发。
• <actual response code>: function(data, response) - 根据具体响应状态码触发。

成员

• abort([error]) - 取消请求。触发 abort 事件。request.aborted 设置为 true。如果传递了非空 error，则还会触发 error 事件。
• retry([timeout]) - 在指定时间后重新发送请求。当前请求会被取消。
• aborted - 判断请求是否被取消。

其他请求方法

• get(url, options) - 发起 GET 请求。
• post(url, options) - 发起 POST 请求。
• put(url, options) - 发起 PUT 请求。
• del(url, options) - 发起 DELETE 请求。
• head(url, options) - 发起 HEAD 请求。
• patch(url, options) - 发起 PATCH 请求。
• json(url, data, options) - 通过 GET 方法发送 JSON 数据。
• postJson(url, data, options) - 通过 POST 方法发送 JSON 数据。
• putJson(url, data, options) - 通过 PUT 方法发送 JSON 数据。
• patchJson(url, data, options) - 通过 PATCH 方法发送 JSON 数据。

解析器

您可以为 parsers 选项指定如何反序列化响应数据。Restler 提供了以下解析器：

• parsers.auto - 根据内容类型自动选择解析器（XML、JSON 或 YAML）。如果内容类型无法识别，则返回原始数据。
• parsers.json, parsers.xml, parsers.yaml - 将响应转换为 JavaScript 对象。使用 YAML 和 XML 解析器需要安装 yaml 和 xml2js。

选项

• method - 请求方法，默认为 "get"。
• query - 查询字符串变量，覆盖 URL 中的查询字符串。默认为空。
• data - 请求体中添加的数据。可以是字符串或对象。
• parser - 用于处理返回数据的函数。默认使用 restler.parsers.auto。
• encoding - 请求体的编码。默认为 "utf8"。
• decoding - 响应体的编码。默认为 "utf8"。
• headers - HTTP 头信息。默认为 { 'Accept': '*/*', 'User-Agent': 'Restler for node.js' }。
• username, password - 基本认证的用户名和密码。
• accessToken - OAuth Bearer Token。
• multipart - 如果设置为 true，则数据将以 multipart/form-encoded 格式发送。
• client - 用于复用或实现连接池的 http.Client 实例。
• followRedirects - 是否跟随重定向。默认为 true。
• timeout - 超时时间（毫秒）。
• rejectUnauthorized - 是否验证服务器证书。默认为 true。
• agent - HTTP Agent 实例。如果未定义，则使用 globalAgent。

4. 项目安装方式

Restler 的安装非常简单，只需在终端中运行以下命令即可：

npm install restler

安装完成后，您可以在项目中通过 require('restler') 引入并使用 Restler。