honey-net 接口请求库

目前接口请求响应格式分为两版：

1. 旧版：海纳原有所有系统都采用这种格式
2. 新版：遵循腾讯云apiv3规范

本接口请求库，通过封装，隐藏了不同接口格式的底层细节，提供统一的请求方式，响应结果，只需在初始化时选择对应的接口格式即可

安装方法

npm install --save "honey-net"

接口库初始化

NetV3是新版接口 NetV1是旧版接口

新版接口初始化方法

import { NetV3 as Net } from '@tencent/honey-net';
const api = new Net();
api.init({
  baseUrl: '/',
});

旧版接口初始化方法

import { NetV1 as Net } from '@tencent/honey-net';
const api = new Net();
api.init({
  baseUrl: '/',
});

init传入的参数

| 参数名 | 传入值 | 说明 | | ------------------- | ------ | -------------------------------------------------------------------- | | errorHandler | 函数 | 异常拦截器，除ApiError以外的异常，如网络异常等，返回true则不继续抛出 | | apiErrorHandler | 函数 | 异常拦截器，只有ApiError异常会传入，返回true则不继续抛出 | | customHeaderHandler | 函数 | 自定义header，函数应这么定义 headers => { /* 加上自定义header */} | | baseUrl | url | 请求接口根路径 | | timeout | 毫秒 | 请求超时时间 | | requestHandlers | 数组 | 请求处理器，可以传入多个处理函数 | | responseHandlers | 数组 | 响应处理器，可以传入多个处理函数 | | suspendSyncTime | 布尔值 | 默认为false |

Net对象方法

NetV3.post

原始的post方法

不会对返回信息进行解析

import { NetV3 as Net } from '@tencent/honey-net';
const api = new Net();

const res = await api.post('/v1/getRole', {
  RoleID: 123
})

if (res.data) {
  // res.data 是接口返回的数据，需要自行解析，自行处理正常数据返回或者错误数据返回
}

NetV3.get

原始的get方法

不会对返回信息进行解析

import { NetV3 as Net } from '@tencent/honey-net';
const api = new Net();

const res = await api.get('/v1/getRole', {
  RoleID: 123
},{
  headers: {
    xxxx: 'xxx'
  },// 添加请求头等其他自定义参数
})

if (res.data) {
  // res.data 是接口返回的数据，需要自行解析，自行处理正常数据返回或者错误数据返回
}

NetV3.setToken

设置 jwt token 值

api.setToken('blah blah');

NetV3.easyPost

post方法

会对返回信息进行解析，如果接口返回正常数据，post函数返回值就是接口Response里的数据，如果接口返回错误，则会抛出ApiError 可通过ApiError的getCode和getMessage分别获得错误码和错误信息

import { NetV3 as Net, ApiError } from '@tencent/honey-net';
const api = new Net();

try {
  const res = await api.easyPost('/v1/getRole', {
    RoleID: 123
  })
  // 这里res就是接口返回的正常数据
} catch (err) {
  if (err instanceof ApiError) {
    // 错误码
    const code = err.getCode()
    // 错误信息
    const message = err.getMessage()
  }
}

NetV3.easyGet

get方法

会对返回信息进行解析，如果接口返回正常数据，get函数返回值就是接口Response里的数据，如果接口返回错误，则会抛出ApiError 可通过ApiError的getCode和getMessage分别获得错误码和错误信息

import { NetV3 as Net, ApiError } from '@tencent/honey-net';
const api = new Net();

try {
  const res = await api.easyGet('/v1/getRole', {
    RoleID: 123
  })
  // 这里res就是接口返回的正常数据
} catch (err) {
  if (err instanceof ApiError) {
    // 错误码
    const code = err.getCode()
    // 错误信息
    const message = err.getMessage()
  }
}

错误对象

ApiError

如果是接口返回的错误信息，easyPost和easyGet会抛出ApiError

ApiError有如下函数可以使用：

| 函数名 | 函数功能 | | ---------------------------------- | ----------------------------------------------------------- | | getCode | 获取错误码 | | getMessage | 获取错误描述文案 | | isAuthFailureInvalidSecretId | 密钥非法（不是云 API 密钥类型）。 | | isAuthFailureMFAFailure | MFA 错误。 | | isAuthFailureSecretIdNotFound | 密钥不存在。 | | isAuthFailureSignatureExpire | 签名过期。 | | isAuthFailureSignatureFailure | 签名错误。 | | isAuthFailureTokenFailure | token 错误。 | | isAuthFailureUnauthorizedOperation | 请求未 CAM 授权。 | | isDryRunOperation | DryRun 操作，代表请求将会是成功的，只是多传了 DryRun 参数。 | | isFailedOperation | 操作失败。 | | isInternalError | 内部错误。 | | isInvalidAction | 接口不存在。 | | isInvalidParameter | 参数错误。 | | isInvalidParameterValue | 参数取值错误。 | | isLimitExceeded | 超过配额限制。 | | isMissingParameter | 缺少参数错误。 | | isNoSuchVersion | 接口版本不存在。 | | isRequestLimitExceeded | 请求的次数超过了频率限制。 | | isResourceInUse | 资源被占用。 | | isResourceInsufficient | 资源不足。 | | isResourceNotFound | 资源不存在。 | | isResourceUnavailable | 资源不可用。 | | isUnauthorizedOperation | 未授权操作。 | | isUnknownParameter | 未知参数错误。 | | isUnsupportedOperation | 操作不支持。 | | isUnsupportedProtocol | HTTPS 请求方法错误，只支持 GET 和 POST 请求。 | | isUnsupportedRegion | 接口不支持所传地域。 |

使用Demo

下面以post请求（新版）

假设接口定义如下：

请求路径：

method: POST

path: /v1/GridPCSvr/DescribeRoleList

请求参数：

{
  "RequestId": "xxx",
  "RoleID": "1001",
  "Offset": 0,
  "Limit": 10
}

接口返回：

{
  "Response": {
    "TotalNum":143,
    "RoleMemberList":[{
      "UserName":"张三",
      "UserID":"XXX",                    
      "CreateTime":"2020-12-02 19:03:21",
      "Phone":"13923882323",
    }]
  }
}

可以如下请求

import { NetV3 as Net } from '@tencent/honey-net';
const api = new Net();
api.init({
  baseUrl: '/',
});

async function getRoleList(params) {
  try {
    const roleListData = await api.easyPost('/v1/GridPCSvr/DescribeRoleList', params);

    return roleListData;
  } catch (error) {
    // ApiError 是接口返回错误信息，需要继续抛出去给业务逻辑
    if (error instanceof ApiError) {
      if (error.isAuthFailureTokenFailure()) {
        // token 失效了
        // 处理token失效的逻辑
      } else {
        // 其他错误
        // 如果无法处理则继续抛出错误
        throw error
      }
    }
    console.error(error.message);
  }
  return null;
}

// 这里无需存入RequestId，接口库会自动带上
const resData = await getRoleList({
  "RoleID": "1001",
  "Offset": 0,
  "Limit": 10
})