Skip to content

aliplay-team/maga-client-nodejs-open

Repository files navigation

@aligames/maga-open

阿里游戏 API 网关 - Node.js SDK

NPM version build status Test coverage David deps Known Vulnerabilities NPM download

提供了 API 的请求封装、摘要签名、响应解释、消息监听等功能,使用 SDK 可以轻松完成 API 的调用,API 结果的获取。

安装依赖

仅支持 Node.js 6.x 以上版本。

npm i @aligames/maga-open --save

我们的类库严格遵循 Semver 版本规则,故强烈建议开发者通过 ^ 的方式引入,即:

{
  "dependencies": {
    "@aligames/maga-open": "^1.0.0"
  }
}

使用方法

作为消费者,发起请求

  • 通过 new Sdk.Client({ key, secret }) 进行初始化,需要提供 keysecret 配置。
  • 使用 yield client.request({ service, data, options }) 来封包,发送请求给服务端,以及解析服务端返回数据。
const Sdk = require('@aligames/maga-open');
const client = new Sdk.Client({
  key: '<your_app_key>',
  secret: '<your_app_secret>',
  // host: 'http://',
  // level: 'INFO',
  // timeout: 5000, // 超时时间,默认为 5000ms
  // required: true, // 遇到错误时,直接抛错还是返回错误对象,便于组合请求,默认为 true - 抛错
  // prefix: 'MAGA',
  // logfile: 'path/to/log/file',
  // logger: my_custom_logger,
});

const result = yield client.request({
  // API 名称,必须用 / 开头
  service: '/api/xxx',
  // 请求的数据体
  data: {
    uid: 'tz',
  },
});

// 返回的对象中,包含 { id, data, state, headers }
console.log(result.data);

并发组合请求:

const result = yield {
  api1: client.request({ service: '/api/xxx', data: { uid: 'tz' } }),
  api2: client.request({ service: '/api/yyy' }),
};

const data = {};
Object.keys(result).forEach(key => data[key] = result[key].data);

// 返回的对象中,包含 { api1: {}, api2: {} }
console.log(result.api1.data);

// 提取出所有 data
console.log(data);

错误处理:

try {
  const result = yield client.request({
    service: '/api/xxx',
    data: {
      uid: 'tz',
    },
  });
} catch (err) {
  // { message, code, data }
  console.error(err);
}

对特定请求配置:

const config = {
  // API 名称,必须用 / 开头
  service: '/api/xxx',
  // 请求的数据体
  data: {
    uid: 'tz',
  },
};

const result = yield client.request(config, {
  timeout: 100000,
  required: false,
});

// api1 是关键请求,失败了则整个失败,而 api2 请失败时,不会报错,此时 result.api2 是 error 对象
const combo = yield {
  api1: client.request({ service: '/api/xxx', data: { uid: 'tz' } }),
  api2: client.request({ service: '/api/yyy' }, { required: false }),
};

作为服务提供方,提供接口服务

  • 通过 new Sdk.Server({ keystore }) 进行初始化,需要提供 keystore 配置。
  • 使用 server.decode({ meta, payload }) 解析客户端传递过来的请求体,解析出错会抛错,请注意 try catch 处理。
  • 使用 server.response({ result, id, code, msg }) 对响应数据进行封包,返回 { meta, payload } 供开发者使用,前者用于配置 headers,后者是 buffer 直接返回给对端。
    • code 是 API 层的状态码,如 API 找不到,返回 404没有权限,keystore 校验失败,返回 403,等等。
    • result 节点为业务结果,数据一般为 { data: {}, state: { code, message }}
    • 注意: result.state.code 和上面提到的 state 不一样,是业务的状态码
const Sdk = require('@aligames/maga-open');
const server = new Sdk.Server({
  // 允许访问的 app key 和 secret 值对
  keystore: {
    '<your_app_key>': '<your_app_secret>',
  },
  // level: 'INFO',
  // prefix: 'MAGA SERVER',
  // logfile: 'path/to/log/file',
  // logger: my_custom_logger,
});


try {
  // 获取客户端发送的请求对象,需传递 headers 和 req body buffer,进行解码,解析出错会抛错,请注意 `try catch` 处理。
  const body = server.decode({ meta: ctx.headers, payload: rawBody });

  // 进行业务逻辑处理,如查询数据库
  const result = yield ctx.service.user.find({ uid: body.uid, from: 'server' });

  // 对返回结果进行封包
  const { meta, payload } = server.response({ id: id || Date.now(), code, msg, result });

  // 返回 headers
  ctx.set(meta);

  // 返回请求体,buffer
  ctx.body = payload;

} catch (err) {
  // 需要自己处理报错后的返回
  ctx.status = err.code;
  ctx.body = err;
}

调试

我们给开发者提供了 cli 命令,用于本地发起请求。

$ maga-cli request --key=<key> --secret=<secret> <payload json string>
$ maga-cli encode --key=<key> --secret=<secret>  <payload json string>
$ maga-cli decode --key=<key> --secret=<secret>  <payload base64 string>

示例:

$ node ./node_modules/.bin/maga-cli --key=ngclient#2dcd --secret=wqjx0iXcRw2uEXdmjlruzw003 --host="http://localhost:7001" request '{"service":"/api/csbiz.account.findUserById?ver=1.0.0","data":{"uid":"tz"}}'

$ node bin/maga-cli.js --key=ngclient#2dcd --secret=wqjx0iXcRw2uEXdmjlruzw003 --host="http://100.84.254.233:7001" decode 'Rn+Cek0ATDXYJvkDxgiJ20+wRP4XdvFKcp4XXePyj+R83W9H+yct6LEIzrlP9cw6tohaF1a1AhcXnayIv+TfY18Kr7uJ8v9mdDBx1Efc3BUtDS3LJzW3BBhXBYeQ5C0B'

质量

我们的类库严格遵循 Semver 版本规则,故强烈建议开发者通过 ^ 的方式引入,即:

{
  "dependencies": {
    "@aligames/maga-open": "^1.0.0"
  }
}

单元测试覆盖率:

=============================== Coverage summary ===============================
Statements   : 100% ( 190/190 )
Branches     : 100% ( 80/80 )
Functions    : 100% ( 19/19 )
Lines        : 100% ( 188/188 )
================================================================================

服务端开发

参见示例: https://github.com/aliplay-team/maga-client-nodejs-open-example

推荐使用我们开源的『企业级的 Node.js Web 基础框架』 - eggjs

反馈

  • 联系接口同学
  • 或提交 Issue

About

阿里游戏 API 网关 - Node.js SDK

Resources

Stars

Watchers

Forks

Packages

No packages published