兼容微信小程序的流式网络请求库

本项目从属于笔者的Web开发入门与最佳实践之前端开源项目系列。如果对于HTTP协议与规范尚不掌握的建议阅读HTTP 基础与变迁一文。如果对于REST尚不掌握的推荐阅读来自微软的接口设计指南以及来自于PayPal的RESTful API标准

Fluent Fetcher:兼容Weapp的流式网络请求库

笔者一直比较喜欢使用标准的Fetch API来进行浏览器端的网络请求，同时使用的是isomorphic-fetch保证接口类的可测试性。而本项目则是笔者借鉴了SuperAgent API的风格基于Fetch进行的二次封装，主要是提供了流式风格的构造与使用方法，同时对常见功能进行了扩展。另外，fluent-fetcher还原生支持Weapp，基于fluent-fetcher构造的接口类可以直接在Weapp环境下使用。

Basic Usage

Installation

可以使用npm install fluent-fetcher --save安装本项目，或者使用yarn add fluent-fetcher安装使用。

Instantiate:实例化

直接在需要使用的地方以import导入即可:

//@flow
import FluentFetcher from 'fluent-fetcher';

我们可以直接以实例化方式创建请求实例:

const host = "jsonplaceholder.typicode.com";
let fluentFetcher = new FluentFetcher({scheme: "http", host});

其中可选的构造参数有:

constructor(
    {
        scheme = "http", //请求协议
        host = "api.com",  //域名
        encoding = "utf8",  //编码
        acceptType = "json" //接收的返回数据类型
    } = {}
)
{...}

而如果在项目中我们存在多个数据源，建议是在接口公共父类中创建多个数据源实例，这样具体的接口实现类皆可以使用使用this.xxxClient方式进行请求。

// @flow
//E路数据的服务端地址
const edataHost = 'api.edata.com';

//公共资源的服务端地址
const ggzyHost = 'api.ggzy.com';

export default class API {

  //用于抓取公共资源数据的API
  ggzyAPIClient: FluentFetcher = null;

  //EDATA，用于抓取E路数据的API
  edataAPIClient: FluentFetcher = null;

  /**
   * @function 默认构造函数
   */
  constructor() {

    //构造请求体
    this.ggzyAPIClient = new FluentFetcher({
      scheme: 'http',
      host: ggzyHost,
      responseContentType: "json"
    }).header({
      key: 'UserAgent',
      value: 'wap'
    }).header({
      key: 'Content-Type',
      value: 'application/json'
    });

    this.edataAPIClient = new FluentFetcher({
      scheme: 'http',
      host: edataHost,
      responseContentType: "json"
    }).header({
      key: 'UserAgent',
      value: 'wap'
    }).header({
      key: 'Content-Type',
      value: 'application/json'
    });

  }

}

注意，如果你是在Weapp环境下，那么FluentFetcher会自动使用wx.request作为请求载体。

GET

//测试GET类型请求
describe('GET请求测试', function () {

  //https://jsonplaceholder.typicode.com/posts?userId=1
  it('获取博文', function (done) {
    fluentFetcher
      .parameter({"userId": "1"})
      .get("/posts")
      .build()
      .then((data) => {
        expect(data).to.be.a('array');
        expect(data.length).to.be.above(0);
        done();
      }).catch((error) => {
      done(error);
    });
  });


});

POST

//测试POST类型请求
describe('POST请求测试', function () {

  //https://jsonplaceholder.typicode.com/posts?userId=1
  it('创建博文@表单编码格式', function (done) {
    fluentFetcher
      .parameter({
        title: 'foo',
        body: 'bar',
        userId: 1
      })
      .post("/posts", 'x-www-form-urlencoded')
      .build()
      .then((data) => {
        expect(data).to.be.a('object');
        expect(data.id).to.equal(101);
        expect(data.title).to.equal('foo');
        expect(data.body).to.equal('bar');
        expect(data.userId).to.equal(1);

        done();
      }).catch((error) => {
      done(error);
    });
  });

  //https://jsonplaceholder.typicode.com/posts?userId=1
  it('创建博文@JSON格式', function (done) {
    fluentFetcher
      .parameter({
        title: 'foo',
        body: 'bar',
        userId: 1
      })
      .post("/posts")
      .build()
      .then((data) => {
        expect(data).to.be.a('object');
        expect(data.id).to.equal(101);
        expect(data.title).to.equal('foo');
        expect(data.body).to.equal('bar');
        expect(data.userId).to.equal(1);

        done();
      }).catch((error) => {
      done(error);
    });
  });


});

PUT/DELETE

类似于POST请求方法。

Advanced Usage

Encode:编码

项目使用了isomorphic-urlencode作为通用的编解码工具，正常的会支持UTF8与GBK两种编码方案。当我们以x-www-form-urlencoded格式发起POST/PUT/DELETE请求时，会自动会请求体进行编码工作。另外，如果我们使用pathSegment添加请求路径时候，也会自动进行编码操作。

Mock

在实际的项目中，譬如微信小程序里，可能我们的服务端尚未准备好或者域名没有审核通过，我们需要在前端进行Mock操作以模拟正常业务流程的返回。笔者在这里选定的Mock方案个人感觉还是比较轻量级的，即直接在构造实例时将你需要的Mock地址对应的数据传入即可。

//测试MOCK
describe('MOCK请求测试', function () {

  it('对于MOCK数据应该正常返回本地值', function (done) {


    fluentFetcher.get('/mock').mock({'/mock': {test: 'data'}}).build().then((data) => {

      expect(data).to.be.a('object');

      expect(data.test).to.equal('data');

      done();

    });

  });

});

CORS:跨域请求

• 浏览器跨域方法与基于Fetch的Web请求最佳实践

直接使用cors()函数添加CORS支持即可。

Error:异常处理

异常处理是我们项目中常见的操作，在Fluent Fetch中对于所有非200或者300系列的请求皆会抛出异常:

    if (response.status >= 200 && response.status < 300) {
      return response
    } else {
      var error = new Error(response.statusText);
      error.response = response;
      throw error
    }

笔者是推荐使用async/await加上try-catch语法进行异常处理:

    try {
      //发起数据请求
      let result = await this.post(`/quotation/bom/${bom.id}`, data);

      return successResponse;

    } catch (err) {

      return internalServerErrorResponse;

    }

RoadMap

• Cache:缓存

• Retry:失败重试

• Timeout:超时