JDL-GateWay物流网络SDK的设计与使用

本文主要介绍京东物流网关前端插件的设计及使用方法，通过该插件的引入，可以轻松实现不同环境下服务域的接入，插件以axios为基础，前端开发零成本接入。

背景

在实际的业务开发中，我们往往需要对接不同的业务线， 然而从安全规范来说，需要接入网关层进行统一处理。接入服务网关层可以实现接口数据的统一管理， 接口格式的规范化、权限的控制、安全认证、路由负载均衡等。

作为前端开发来说， 不同的环境、不同用户账户需要进行不同网关的处理工作，为此我们开发了一套基于axios的插件来适应不同的场景。

axiosGW

在进行插件开发时，放弃的之前基于内部封装的fetch库的实现，而且采用基于axios的方式进行实现。主要优势axios的适用度更广，对于前端来说更容易上手，另外它的插件自身比较利于扩展。

axiosGW是基于axios实现的网关前端SDK插件， 目前支持passport、erp 、inner_erp（内网ERP调用网关）、 tls_inner_erp（tls内网ERP调用网关）。它内置了配置方案，具有扩展性，可进行第三方模块的接入。

设计模型

如下图所示， 针对不同账户不同环境我们分别进行划分。账户类型包括passport、erp、内网erp等。环境的话按照实际项目的开发可以分为development (开发)、prepare(预发)、production(生产）环境。另外针对不同账户不同环境分别设置里401的登录跳转。

其实现原理的流程图如下所示，其中主要的实现为：

1.在请求拦截器中对url进行处理，根据不同环境对URL拼接对应的服务域， 设置header字段包括lop-dn的设置。

2.在响应拦截器中，进行401的跳转判断处理。

3.考虑的插件的灵活性允许第三方配置服务域或者跳转地址。

安装

npm install @jdl/axios-gateway --registry=http://registry.m.jd.com

使用方法

网关插件的引入方式如下代码所示， 考虑到实际业务中仍存在一些没有接入网关的接口， 建议采用axios.create创建一个新的axios对象，然后在该对象的基础上进行插件的封装。通过axiosGW方法的调用生成的是一个单例模式的插件，项目场景是一种用户类型的话采用该方案。在插件使用过程中，有用户反馈他们的项目同时存在erp inner_erp希望可以提供多实例模式， 此时可以采用axiosGW.create的方式。axiosGW.create允许配置多个实例。

import axios from 'axios'
import axiosGW from '@jdl/axios-gateway';


const instance = axios.create({
  timeout: 5000
})


const config: any = {
  env: process.env.NODE_ENV,
  domain: process.env.VUE_APP_GW_DOMAIN,
  appid: process.env.VUE_APP_GW_APPID,
  appType: 'pc',
  clientInfo: {
    appName: process.env.VUE_APP_GW_APPNAME,
    client: 'pc'
  },
  loginDomain: process.env.VUE_APP_LOGIN_DOMAIN,
  loginType: process.env.VUE_APP_LOGINTYPE,
  stopLogin: true
}



axiosGW(instance, config)
export default instance

config属性

config字段的配置如下， 每个字段的作用及是否必选都有相应说明

网关的配置

通过设置loginType字段， 实现不同账户不同配置。目前支持passport、erp 、inner_erp（内网ERP调用网关）、 tls_inner_erp（tls内网ERP调用网关）。

第三方网关环境域名内置方式

企业咚咚联系星云技术支持总群 进行配置文件扩展 配置文件格式如下：

'erptest': {
    domains: {
      development: 'https://test-XXX.jd.com',
      prepare: 'https://uat-XXX.jd.com',
      production: 'https://lop-XXX.jd.com'
    },
    loginUrl: function (options: any) {
      // 你的跳转地址
      return '//passport.jd.com/uc/login?ReturnUrl=XXXXXX'
    }
  }

目前支持登录方式

passport、erp 、inner_erp（内网ERP调用网关）、 tls_inner_erp（tls内网ERP调用网关）。

自定义登录跳转

默认status返回401时， 检查为用户未登录， 会触发登录跳转。如果你想自定义登录跳转的地址时， 有两种方案可选。

第一种 在配置文件中，设置changeLoginHref回调函数，如下示例：

{
  changeLoginHref: function (response, options) {
    return '//www.jd.com'
  }
}

通过该回调可进行灵活配置。

第二种 您需要企业咚咚联系星云技术支持总群 （songali 或者 luobinbin5），进行配置设置。

LOP-DN设置

第一种 ，通过domain 进行全局的domain设置。

第二种 ，在axios请求中进行单条设置， 示例如下：

export function getQueryCod(data: any) {
  return axios({
    method: 'POST',
    url: '/logistics/getQueryCod',
    data,
    headers: {
      'LOP-DN': 'xxx.jd.com'
    }
  })
}

另一种方案，您可以对axios添加拦截器采用路由匹配规则，对LOP-DN进行批量分类设置。

自定义响应处理

如果您的response的返回结果并非 401表示未登录这样的模板结果， 您可以通过responseHandle回调方法进行自定义响应处理。 规范返回的结果中需包含status字段。

网关服务域外部配置方式

如果你的账户是非passport、erp 、inner_erp（内网ERP调用网关）、 tls_inner_erp（tls内网ERP调用网关）；允许你采用外部配置的方式进行接入。当然我们更推荐内部配置的方案。其接入方式如下，确保你的gwEnvInfos字段中的key值与LoginType一致。

gwEnvInfos: {
    'yourPassport': {
      domains: {
        development: 'https://test-XXX.jd.com',
        prepare: 'https://uat-XXX.jd.com',
        production: 'https://lop-XXX.jd.com'
      },
      loginUrl: function (options: any) {
        // 你的跳转地址
        return '//passport.jd.com/uc/login?ReturnUrl=XXXXXX'
      }
    }
  }

关闭网关层

closeGw字段设置为true。

总结

设计公用插件库用来接入不同开发环境的数据， 这是前端框架中的一个基本点， 然而不同公司根据实际业务场景，会有一套自己的实现方案。针对我们这边业务的特点，JDL-GateWay采用axios拦截器的方案进行实现，开发者无需在axios的基础上进行额外学习，插件也比较方面扩展和维护。

文章或存在一些浅显不足之处， 欢迎大家评论指点。