本项目从属于笔者的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 {//用于抓取公共资源数据的APIggzyAPIClient: FluentFetcher = null;//EDATA，用于抓取E路数据的APIedataAPIClient: 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=1it('获取博文', 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=1it('创建博文@表单编码格式', 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=1it('创建博文@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:超时