egg-apigw-tracer

适配 API 网关的 HTTP 请求示踪器，用于 Egg.js 框架。

目录

• egg-apigw-tracer
  • 目录
  • 介绍
  • 安装
  • 使用
    • 启用插件
    • 配置方式
    • 使用说明
  • 示例
  • 相关
  • 作者
  • 参与
  • 许可证

介绍

在对外提供 Web 服务时，可能在线上环境出现偶发性的错误，为了方便排查问题，给所有的请求都提供一个 唯一请求 ID 是一个不错的实践，开发者可以根据这个请求 ID 去相关日志中找寻对应的错误内容。

这个「唯一请求 ID」（Unique Request ID）有的时候也叫「示踪 ID」（trace ID），一个通俗的做法是使用 UUID 生成一个字符串，并在响应中附带该字符串。另外一些 Web 服务，会使用云厂商的 API 网关作为接入层，然后将请求转发到开发者自己的服务器上。此时我们往往希望使用 API 网关自带的请求 ID 作为示踪 ID，本插件就是为了解决这个问题诞生的。

本插件完美适配 Egg.js 框架，只需要按照框架要求启用插件，可以零配置使用。

安装

按照通用的方式使用 npm 下载安装到你的项目下即可，无需全局安装。

安装命令：

npm i egg-apigw-tracer

使用

在使用前，请确保你已经阅读 Egg.js 框架关于插件的 文档 。

下面说明如何配置以及使用插件。

启用插件

在 config/plugin.js 文件中中声明启用插件：

exports.tracer = {
  /** 是否启用插件，true 为启用，false 为禁用 */
  enable: true,

  /** 指定插件使用的包，为 'egg-apigw-tracer' */
  package: 'egg-apigw-tracer',
}

配置方式

本插件无需任何配置即可使用。但考虑到以下使用场景：

线上生产环境使用 API 网关做接入层，使用 API 网关自带的请求 ID 做示踪 ID，但本地开发环境无该接入层，同时为了保持功能逻辑一致，也需要一个类似的示踪 ID，因此使用 UUID 做示踪 ID。

在 config/config.${env}.js 文件配置插件的使用方式（以下为默认配置）：

exports.tracer = {
  mode: 'apigw',
  idHeader: 'x-ca-request-id',
}

各配置项的含义是：

| 属性 | 类型 | 默认值 | 是否必填 | 说明 | | :------: | :----: | :---------------: | :------: | :--------------------------------------------------------------------------------: | | mode | string | 'apigw' | 否 | 模式，使用 apigw 表示存在 API 网关接入层，使用 uuid 表示使用 uuid 生成示踪 ID | | idHeader | string | 'x-ca-request-id' | 否 | 仅在使用apigw 模式下该设置项有效，表明从指定的请求头中获取requestId用作示踪 ID |

使用说明

主要有 2 处使用场景，一是你可以直接通过 ctx.traceId 获取示踪 ID，二是你使用 ctx.logger 打印日志时，框架会自动在日志前附上示踪 ID，前缀格式为：[$userId/$ip/$traceId/${cost}ms $method $url] ，详情见 文档 。

示例

我们模拟以下这个使用场景，来演示如何配置和使用本插件：

线上生产环境使用 阿里云 API 网关做接入层，本地开发测试未使用特定接入层。

在 config/plugin.js 文件中中声明启用插件：

exports.tracer = {
  enable: true,
  package: 'egg-apigw-tracer',
}

在 config.local.js 文件中配置内容为：

exports.tracer = {
  mode: 'uuid',
}

在 config.prod.js 文件中配置内容为：

exports.tracer = {
  mode: 'apigw',
}

相关

以下是作者开发的 Egg.js 框架的插件系列，已用于作者的生产项目中，推荐使用。

• egg-apigw-tracer - ⚡ 适配 API 网关的 HTTP 请求示踪器，用于 Egg.js 框架
• egg-aliyun-tablestore - 🚚 阿里云表格存储（Tablestore）插件，用于 Egg.js 框架
• egg-load - 🚀 自动挂载第三方模块至 Egg.js 框架上

作者

我是 inlym ，一个产品经理和全栈开发者。

如果你有任何问题或者建议，欢迎联系我，以下是我的联系方式：

• 邮箱：[email protected]
• 主页：www.inlym.com

参与

非常欢迎你能够参与这个项目的开发和维护。

你可以通过以下几种方式参与到项目中：

1. 提建议和需求。对于几句话就能说清楚的建议和需求，你可以直接 提一个 New Issue 。
2. Fork 项目，修改代码，然后提交 Pull requests 。（提交前请检查务必通过 ESLint 检查）

许可证

本插件使用 MIT 许可证。