❤
npm
Sign UpSign In

tammy

1.1.4 • Public • Published

Tammy

npm package

Note: 基于promise用于浏览器和node.js的http客户端

NPM version NPM Downloads

目录

安装

使用传统的 <script> 标签加载 tammy

<script src="//cdn.jsdelivr.net/npm/tammy/umd.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/tammy-adapter-xhr/umd.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/tammy-plugin-xsrf/umd.min.js"></script>

使用 CommonJS 方式导入

npm install tammy --save
 
# 浏览器环境 
npm install tammy-adapter-xhr --save
 
# nodejs环境 
npm install tammy-adapter-request --save
 
# 可选 
npm install tammy-plugin-xsrf --save

用法

执行一个 GET 请求

import { http } from 'tammy';
import xhr from 'tammy-adapter-xhr';
http.defaults.adapter = xhr;
 
// Make a request for a user with a given ID
http.get('/user?ID=12345')
  .then(function (response) {
    // 处理成功情况
  })
  .catch(function (error) {
    // 处理异常情况
  });
 
// Optionally the request above could also be done as
http.get('/user', {
  qs: {
    ID: 12345
  }
})
.then(function (response) {
    // 处理成功情况
})
.catch(function (error) {
  // 处理异常情况
});
 
// 使用 async/await
async function getUser() {
  try {
    const response = await http.get('/user?ID=12345');
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

NOTE: async/await 是 ECMAScript 2017 的一部分, 浏览器不一定都支持

执行一个 POST 请求

import { http } from 'tammy';
 
request.post('/user', {
  firstName: 'Fred',
  lastName: 'Flintstone'
})
.then(function (response) {
  console.log(response);
})
.catch(function (error) {
  console.log(error);
});

执行多个并发请求

import { http } from 'tammy';
 
request.all([{
  url: '/user/12345',
  qs: {
    num: 1
  }
}, '/user/12345/permissions'])
  .then(function (arr) {
    // Both requests are now complete
  });

Tammy API

  • Constants
    • CT_FORM
    • CT_JSON
    • CT_FORM_DATA
    • CONTENT_TYPES
    • ECONNABORTED
    • ECONNRESET
    • ENETWORK
    • EREQCANCELLED
  • Request
    • cancel
    • cancelAll
    • create
    • http
  • Utils
    • createError
    • forOwn
    • formify
    • isAbsoluteURL
    • isCancelled
    • isFunction
    • isNil
    • isNumber
    • isObject
    • isString
    • joinPath
    • joinQuery
    • forSlice
    • merge
    • noop
    • remove
    • removeAt
    • stringifyQuery
    • uuid
import {
  CT_FORM
  CT_JSON
  CT_FORM_DATA
  CONTENT_TYPES,
  ECONNABORTED,
  ECONNRESET,
  ENETWORK,
  EREQCANCELLED,
  cancel,
  cancelAll,
  create,
  http,
  createError,
  forOwn,
  formify,
  isAbsoluteURL,
  isCancelled,
  isFunction,
  isNil,
  isNumber,
  isObject,
  isString,
  joinPath,
  joinQuery,
  forSlice,
  merge,
  noop,
  remove,
  removeAt,
  stringifyQuery,
  uuid
} from 'tammy';
 

通过相关配置发起请求

http(options)

// Send a POST request
 
import { http } from 'tammy';
 
http({
  method: 'post',
  url: '/user/12345',
  data: {
    firstName: 'Fred',
    lastName: 'Flintstone'
  }
});

http(url[, options])

// Send a GET request (default method)
 
import { http } from 'tammy';
 
http('/user/12345');

请求方法别名

http(options)

http.get(url[, data[, options]])

http.delete(url[, data[, options]])

http.del(url[, data[, options]])

http.head(url[, data[, options]])

http.options(url[, data[, options]])

http.post(url[, data[, options]])

http.put(url[, data[, options]])

http.patch(url[, data[, options]])

NOTE: 当使用以上别名方法时，url，method和data等属性不用在config重复声明。

执行多个并发请求

http.all([ ...options ])

创建一个实例

创建一个拥有通用配置的 tammy 实例

create([options])

import { create } from 'tammy';
import xhr from 'tammy-adapter-xhr';
 
const instance = create({
  baseUrl: 'https://some-domain.com/api/',
  timeout: 1000,
  headers: {'X-Custom-Header': 'foobar'},
  adapter: xhr
});

实例方法别名

instance(options)

instance.get(url[, data[, options]])

instance.delete(url[, data[, options]])

instance.del(url[, data[, options]])

instance.head(url[, data[, options]])

instance.options(url[, data[, options]])

instance.post(url[, data[, options]])

instance.put(url[, data[, options]])

instance.patch(url[, data[, options]])

配置参数

下面是可用配置项, 只有 url 必填, 如果没有指定方法, 就默认 GET 方法

  • url - 请求地址.
  • baseUrl - 跟路径，将会跟 url 拼接.
  • method - 请求方法 (默认值: "GET").
  • headers - 自定义请求头 (默认值: {'Accept': 'application/json, text/plain, */*'}).
  • qs - url 拼接参数, 必须是一个对象或者一个 query string 字符串.
  • data - 如果是 GET 请求, 将转成 query string; 如果是 POST 请求, 将根据 content-type 转成 query string 或者 json string.
  • cache - 如果设置为 false, 将在 url 后增加时间戳, 当 method 是 HEAD、DELETE 或 GET.
  • timeout - 请求超时毫秒数 (默认值: 0 无超时).
  • adapter - 自定义适配不同环境 (参考 https://github.com/fengxinming/tammy/blob/dev/packages/tammy-adapter-xhr/src/index.js).
{
  adapter: function (options) {
    /* ... */
  }
}
  • validateStatus - 校验 HTTP 响应状态码 (默认值: (status >= 200 && status < 300) || status === 304.
{
  validateStatus: function (status) {
    // 校验状态码并返回 bool 值
  }
}
  • cancelToken - 保存 token 用于中断请求.
let cancelToken;
// ...
 
{
  cancelToken: function(token) {
    cancelToken = token;
  }
}
  • requestType - 简化设置 content-type, 可选值包括: ‘form’、'json'或'form-data'
  • responseType - 设置响应数据类型, 可选值包括 'arraybuffer', 'blob', 'document', 'json', 'text', 'stream' (默认值: "json").
  • withCredentials - 是否携带cookie信息 (默认值: false).
  • auth - HTTP Basic auth
{
  auth: {
    username: 'janedoe',
    password: 's00pers3cret'
  }
}
  • xsrfCookieName xsrf token 名称 (默认值: "XSRF-TOKEN").
  • xsrfHeaderName xsrf token 值 (默认值: "X-XSRF-TOKEN").
  • onUploadProgress - 处理上传进度事件.
{
  onUploadProgress: function (progressEvent) {
    // Do whatever you want with the native progress event
  }
}
  • onDownloadProgress - 处理下载进度事件.
{
  onDownloadProgress: function (progressEvent) {
    // Do whatever you want with the native progress event
  }
}

Response 结构

Response 包含以下信息.

{
  // `data` 服务端返回的数据
  data: {},
 
  // `status` 服务端返回的状态码
  status: 200,
 
  // `statusText` 服务端返回的状态信息
  statusText: 'OK',
 
  // `headers` 响应头
  headers: {},
 
  // `config` 请求配置
  config: {},
 
  // `request` 请求对象
  request: {}
}

使用 then 接受 response 相关信息

import { http } from 'tammy';
 
http.get('/user/12345')
  .then(function (response) {
    console.log(response.data);
    console.log(response.status);
    console.log(response.statusText);
    console.log(response.headers);
    console.log(response.config);
  });

使用 catch 接受异常信息 rejection callback, 可见 异常处理 区域.

默认参数

全局 http 默认配置

import { http, CT_FORM } from 'tammy';
 
http.defaults.baseUrl = 'https://api.example.com';
http.headers.common.Authorization = 'authtoken';
http.headers.post['Content-Type'] = CT_FORM;

定制 http 实例

import { create } from 'tammy';
 
const instance = create({
  baseUrl: 'https://api.example.com',
  Authorization: 'authtoken'
});

配置优先级

配置项通过一定的规则合并, request配置将覆盖instance.defaults配置.

import { create } from 'tammy';
 
const instance = create();
 
instance.defaults.timeout = 2500;
 
// timeout 将覆盖 instance.defaults.timeout
instance.get('/longRequest', {
  timeout: 5000
});

拦截器

增加全局 http 拦截器

// Add a request interceptor
import { http } from 'tammy';
 
const interceptorId = http.interceptors.request.use(function(config) {
  // Do something before request is sent
  return config;
}, function (error) {
  // Do something with request error
  return Promise.reject(error);
});
 
// Add a response interceptor
http.interceptors.response.use(function (response) {
  // Do something with response data
  return response;
}, function (error) {
  // Do something with response error
  return Promise.reject(error);
});

通过 id 或下标移除拦截器

http.interceptors.request.eject(interceptorId);
// 或者
http.interceptors.request.eject(0);

增加定制 http 拦截器

import { create } from 'tammy';
 
const instance = create();
// Add a request interceptor
instance.interceptors.request.use(function({ interceptors }) {
  // Do something before request is sent
  return config;
}, function (error) {
  // Do something with request error
  return Promise.reject(error);
});
 
// Add a response interceptor
instance.interceptors.request.use(function (response) {
  // Do something with response data
  return response;
}, function (error) {
  // Do something with response error
  return Promise.reject(error);
});

异常处理

http.get('/user/12345')
  .catch(function (error) {
    if (error.response) {
      // The request was made and the server responded with a status code
      // that falls out of the range of 2xx
      console.log(error.response.data);
      console.log(error.response.status);
      console.log(error.response.headers);
    } else if (error.request) {
      // The request was made but no response was received
      // `error.request` is an instance of XMLHttpRequest in the browser and an instance of
      // http.ClientRequest in node.js
      console.log(error.request);
    } else {
      // Something happened in setting up the request that triggered an Error
      console.log('Error', error.message);
    }
    console.log(error.config);
  });

校验 HTTP 状态码

http.get('/user/12345', {
  validateStatus: function (status) {
    return status < 500; // Reject only if the status code is greater than or equal to 500
  }
})

CancelToken

使用 cancel 方法中断请求

let cancelToken;
 
http.get('/user/12345', {
  cancelToken(token) {
    cancelToken = token;
  }
}).catch(function (thrown) {
  if (isCancelled(thrown)) {
    console.log('Request cancelled', thrown.message);
  } else {
    // handle error
  }
});
 
http.post('/user/12345', {
  name: 'new name'
})
 
// cancel the request (the message parameter is optional)
http.cancel(cancelToken, 'Operation aborted by the user.');
 
// cancel all requests
http.cancelAll();

插件

适配器

License

MIT

Readme

Keywords

Package Sidebar

Install

npm i tammy

Repository

github.com/fengxinming/tammy

Homepage

github.com/fengxinming/tammy#readme

Weekly Downloads

1

Version

1.1.4

License

MIT

Unpacked Size

63.4 kB

Total Files

6

Last publish

Collaborators

  • fengxinming
Try on RunKit
Report malware