Arrow Api

请注意

• 本模块发布在npm，但是并不是公用模块。
• 您可以下载并使用，如果对您有帮助的话。
• 本模块的所有开发者不对可用性和安全性等负责。

模块简介

本模块是对api请求的执行层和处理层的封装。由于历史问题，目前Quiver(直接写在react_app中的功能)的Api模块与Arsenal的Api模块规范不统一。 在Kun中，api模块又以另一种方式存在。本模块旨在同构各系统Api层。ArrowApi模块将提供请求发送、默认事件处理路由参数匹配等功能。并提供处理函数定制、请求引擎替换等个性化需求。

请求方式

目前本模块的默认请求方式为formData。formData优点是传送blob方便。在本团队开发的各个系统中大量使用了头像上传、文档上传等功能，所以选用了formData。但是目前formData存在许多问题。比如不能传送空数组、数组参数名与Ruby不统一（在目前的请求引擎reqwest中的格式是 data[0]name:1 data[1]name:2 。而Ruby期待的是 data[]name:1 data[]name:2 。）这是一个需要处理的问题。如果使用Json格式则不会出现这个问题。 但是json传送blob又不是很方便。

约定格式

请求

{
   meta:{ // 无需在使用的时候手动书写，api内部已经封装
       version:'123322113344', // 不适用缓存时，此字段将为空
       versionName:'getOrganization'
   },
   name:'1',
   age:'2',
   someKey:'foo',// 真正要传送的数据散落在meta外部 array or object or binary or string ....
}

响应

{
   meta:{
       useCache:false, // 后台指明是否使用了缓存
       version:'1122334411',
       versionName:'getOrganization',
       code:'',
       msg:'',
       page:'',
       pageSize:''
   },
   data:[] // 相应的数据
}

使用本模块的流程

引入包

import {registerApi} from 'arrowApi'

提供参数并注册Api

const registeredApi = registerApi(options) // options 见后文

使用注册好的api

registeredApi.getOrganization({
   match:{id:3}, // 路由匹配参数
   data:{ // 请求数据
     lite:true
   },
   doNotHandle:false, // 是否禁用默认处理，默认false
   method:'get', // 方法 默认 get
   useCache: false , // 是否使用缓存，默认为true。建议不修改
   type:'',// 数据类型，默认json。
   processData: false // 是否使用reqwest提供的处理数据方法 默认true 会把json转成formData 如果传入false 则会发送json。
}).then(success => {
   // 成功
   // 一般会在这里进行请求的处理
   // 比如更新state等
   // 如果前面的doNotHandle 为true 。则会单独执行成功和失败函数
   // 如果前面的doNotHandle 为false 。则会在默认的处理函数结束后调用此处代码。
} , error => {
   // 失败
   // 同成功一致的行为
})

注册 api 时 可传入的参数

const options = {
  fetcher: reqwest,  // 请求引擎
  messageHandler: message // 供默认处理行为使用的处理函数或处理组件,
  apiNamePathObject: {}, // api方法名与路径的mapper
  apiLayout: "/api/v1", // api Layout
  apiHost: "http://test9.huaing.com" // host
}

注： 关于 messageHandler ， 在一般情况下，您可以传入 antDesign 的 message 组件。当然，根据鸭子法则，你可以传入任何一个同时具有error,success,warn方法的对象。 请区别于接口调用时书写在 then 中的回调函数。他们虽然也是请求处理函数 但是他们是针对每一个接口的个性化处理。此处的 messageHandler 是 所有doNotHandle = false接口的默认处理行为。

关于引擎的可替换性

目前仅做了一种适配，即，传入了引擎并且引擎为reqwest时，本模块才能生效。原因是内部各种api名称都是用的reqwest的api名称。并没有真正做到引擎可替换。 如果后期涉及到多系统使用不同api引擎的情况。个人建议对各个引擎的行为进行抽象后制作mapper，实现个引擎不同名称和语法至统一名称、语法、行为的转换。

缓存机制

缓存存储于localStorage。 每个API可传入布尔类型的useCache参数决定是否使用缓存。 当useCache为true时。发送请求将会携带版本号与版本名称。否则发送的meta中的数据将会是空。

后台若接收到版本号，就会进行对比，若缓存未失效则会返回meta.useCache为true并且在data中不返回任何数据。 此时应该去localStorage获取数据。若后台对比结果为缓存失效，会返回新的数据、版本号并返回meta.useCache为false