# 在客户端使用安全网关

本文档内容已过时，请查看目录中现行文档

# 环境准备

需要在「接入层-接入节点」访问方式中选择勾选「小程序访问」并填写允许访问的AppID

需要在微信开发者工具中选择 2.31.1 版本以上的基础库，才能使用模拟器进行调试。

# 获取接入节点ID

「安全网关控制台-接入层」页面，将接入节点的默认域名取出，截取ID部分，如下图所示：

# 配置请求域名

当前网关的请求需要在mp后台配置request域名，直接将节点域名的完整地址填入就可以，协议为https，如下：

# 在小程序中使用

# 项目配置

强烈建议：在项目配置文件 app.json 中添加如下字段：

{
    "cloud": true,
    "cloudVersion": "alpha"
}

配置后，网关能力支持所有基础库版本，配置完成后，需要在真机上测试确认功能是否正常（微信开发者工具-预览）。

# 合法域名配置

小程序中访问时，需要将网关的接入域名填入到微信公众平台的小程序合法域名中。

# 初始化网关

在真实使用时，需要更改自己的网关 ID 信息。

// app.js
App({
  async onLaunch() {
    const gateway = wx.cloud.services.Gateway({
        // 接入域名，可以在网关控制台中获取
        domain: 'a224faf18-wx1111111111111.preview.wxcloudrun.com',
    })
    // 赋值到 cloud 对象上，方便后续调用
    wx.cloud.gateway = gateway
  }
})

# 调用网关

网关调用形式除 path 参数外，与 wx.request 基本相同：

wx.cloud.gateway.call({
    // 去除域名后的接口路径，中文需要转译
    path: `/?word=${encodeURIComponent('微信网关访问')}`,
    // 请求方法
    method: 'GET',
    // 请求 header
    header: {
        // 小程序场景可选 header，支持自动携带可信的 openid、unionid（小程序需绑定微信开放平台账号）
        // 后台服务收到请求时，可以从请求头中获取到如下 header
        // x-wx-openid: xxxxxx
        // x-wx-unionid: xxxxxx
        'x-wx-include-credentials': 'openid,unionid',
    }
    // 其余参数与 wx.request 相同
}).then(result => {
  console.log('微信网关访问结果：', result)
})

# 接入常见问题

# 开发者工具 Network 面板

开发者工具已支持对网关请求的调试能力，更新到 1.06.2303020 以上即可查看。

# 降级重试

建议对链路可用度敏感的业务使用降级重试策略，即：

先使用 wx.cloud.gateway 进行请求
在请求失败时，回退到 wx.request 进行请求。gateway.call 返回的数据结构如下：

{
  "data": { "x": 1 },
  // http状态码
  "statusCode": 404, 
  // 请求正常则始终为 gateway.call:ok
  "errMsg": "gateway.call:ok",
    // "errCode": -651000, 正常时无此属性。异常时会返回值，代表安全网关侧异常
  "header": {
    "date": "Wed, 19 May 2021 02:37:59 GMT",
    "server": "envoy",
    "content-length": "0"
  },
  "callID": "1665645158626-tsmg9Dpy"
}

# TypeScript 支持

目前 TypeScript 支持仍在进行中，需要手动声明如下类型信息

interface GatewayInstance {
    call: (param: ICloud.CallContainerParam) => Promise<ICloud.CallContainerResult>
}
declare interface WxCloud {
    services: {
        Gateway: (opts: { id: string }) => GatewayInstance
    }
    gateway: GatewayInstance
}