# @banzaicloud/service-tools 中文文档

规范地址：https://npmcn.com/package/%40banzaicloud/service-tools/

版本：4\.0\.6
npm 元数据更新时间：2026-03-31T10:42:51.569Z
中文译文更新时间：2026-11-07T19:06:49.583Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40banzaicloud/service-tools
原文对照：https://npmcn.com/package/%40banzaicloud/service-tools/?lang=original
项目主页：https://github.com/banzaicloud/service-tools#readme
源码仓库：https://github.com/banzaicloud/service-tools

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：144 kB，155 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：koa \>=2\.5\.2 \< 3\.0\.0，express \>=4\.16\.3 \< 5\.0\.0，@hapi/hapi \>=19\.0\.0 \< 20\.0\.0
- 首次发布：2018-08-03T09:44:20.606Z
- 最新版本发布：2021-07-07T08:29:53.212Z
- 近 30 天下载量：3081（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 0 个）

## 中文简介

常见案例的节点服务工具

## 安装

```sh
npm install @banzaicloud/service-tools
```

也可以使用：`pnpm add @banzaicloud/service-tools`、`yarn add @banzaicloud/service-tools`、`bun add @banzaicloud/service-tools`

## README

# 节点服务工具

**准备你的Node.js生产申请!**

 [![CircleCI](https://circleci.com/gh/banzaicloud/service-tools.svg?style=svg&circle-token=002bb942365281c0834e18a1cb83e1930c3ce0fa "CircleCI")](https://circleci.com/gh/banzaicloud/service-tools)[![npm version](https://badge.fury.io/js/%40banzaicloud%2Fservice-tools.svg "npm version")](https://npmjs.com/package/@banzaicloud/service-tools)

此库提供常见的功能, 如优雅的错误处理和关闭, 结构化的 JSON 记录和几个 HTTP 中间软件, 使您的应用程序真正为现代的容器化环境做好准备, 如 [库伯涅斯](http://kubernetes.io/)。 。 。 .

-   [安装](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-installation)
-   [使用量](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-usage)
    -   [主要出口](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-main-exports)
        -   [`catchErrors(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-catcherrorsoptions)
        -   [`gracefulShutdown(handlers, options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-gracefulshutdownhandlers-options)
        -   [`logger`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-logger)
            -   [使用已提供的日志而不是 `console`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-use-provided-logger-instead-of-console)
    -   [配置](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-config)
        -   [`config.environment`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-configenvironment)
        -   [`config.pino`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-configpino)
    -   [中间软件( Koa)](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-middleware-koa)
        -   [`errorHandler(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-errorhandleroptions)
        -   [`healthCheck(checks, options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-healthcheckchecks-options)
        -   [`prometheusMetrics(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-prometheusmetricsoptions)
        -   [`requestValidator(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-requestvalidatoroptions)
        -   [`requestLogger(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-requestloggeroptions)
    -   [中间软件( Express)](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-middleware-express)
        -   [`errorHandler(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-errorhandleroptions-1)
        -   [`healthCheck(checks, options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-healthcheckchecks-options-1)
        -   [`prometheusMetrics(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-prometheusmetricsoptions-1)
        -   [`requestValidator(options)`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-requestvalidatoroptions-1)

## 安装

```sh
npm i @banzaicloud/service-tools
# or
yarn add @banzaicloud/service-tools
```

## 用法实例( E)

此库以TypeScript来写出,指被公布的类型或源代码用于参数和返回类型.

有实例可供查阅 [快递](https://expressjs.com/) 财务报告和审定财务报表 [科亚](https://koajs.com/) 框架。 看看这个 _[实例](https://npmcn.com/examples)_ 文件夹!

### 主要出口

#### `catchErrors(options)`

抓住未被发现的例外 和未处理的承诺拒绝。 之后恢复正常运行不安全 [无法排除](https://nodejs.org/api/process.html#process_event_uncaughtexception)。 。 。 .

```js
const { catchErrors } = require('@banzaicloud/service-tools')

// ...

// the handlers return a Promise
// the handlers are called in order
catchErrors([closeServer, closeDB])

// the error will be caught and the handlers will be called before exiting
throw new Error()
```

#### `gracefulShutdown(handlers, options)`

优雅关闭: 退出前释放资源( 数据库, HTTP 连接,...) 。 申请收到时 `SIGTERM` 或者说 `SIGINT` 信号,将调用近接器。 处理者应返回 a `Promise`。 。 。 .

```js
const { gracefulShutdown } = require('@banzaicloud/service-tools')

// ...

// the handlers return a Promise
// the handlers are called in order
gracefulShutdown([closeServer, closeDB])
```

#### `logger`

A 类 [皮诺](https://github.com/pinojs/pino) 结构化 JSON 日志实例配置 [`config.pino`](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-config)。 。 。 .

```js
const { logger } = require('@banzaicloud/service-tools')

logger.info({ metadata: true }, 'log message')
// > {"level":30,"time":<ts>,"msg":"log message","pid":0,"hostname":"local","metadata":true,"v":1}
```

##### 使用已提供的日志而不是 `console`

全球覆盖 `console` 并使用库提供的日志打印信件.

```js
const { logger } = require('@banzaicloud/service-tools')

console.log('log message')
// > log message

logger.interceptConsole()

console.log('log message')
// > {"level":30,"time":<ts>,"msg":"log message","pid":0,"hostname":"local","v":1}
```

### 配置

动态装入配置 .

#### `config.environment`

使用 `NODE_ENV` 环境变量,具有以下公认的价值:生产、开发、测试.

```js
const { config } = require('@banzaicloud/service-tools')
// validates the NODE_ENV environment variable
console.log(config.environment)
// > { nodeEnv: 'production' }
```

#### `config.pino`

被提供方使用 [日志](https://npmcn.com/package/%40banzaicloud/service-tools/#readme-logger)使用 `LOGGER_LEVEL` 财务报告和审定财务报表 `LOGGER_REDACT_FIELDS` 环境变量。 这个 `LOGGER_LEVEL` 可以是以下之一:致命,错误,警告,信息,调试,追踪. `LOGGER_REDACT_FIELDS` 是一个逗号分隔的字段名称列表,以遮盖输出(默认为: `'password, pass, authorization, auth, cookie, _object'`) (中文(简体) ).

```js
const pino = require('pino')
const { config } = require('@banzaicloud/service-tools')

const logger = pino(config.pino)

logger.info({ metadata: true, password: 'secret' }, 'log message')
// > {"level":30,"time":<ts>,"msg":"log message","pid":0,"hostname":"local","metadata":true,"password":"[REDACTED]","v":1}
```

### 中间软件( Koa)

数个中间软件 [科亚](https://koajs.com/) 网络框架.

#### `errorHandler(options)`

Koa 错误处理器中间软件 .

```js
const Koa = require('koa')
const { koa: middleware } = require('@banzaicloud/service-tools').middleware

const app = new Koa()

// this should be the first middleware
app.use(middleware.errorHandler())
```

#### `healthCheck(checks, options)`

科阿健康检查端点操作员.

```js
const Koa = require('koa')
const Router = require('koa-router')
const { koa: middleware } = require('@banzaicloud/service-tools').middleware

// ...

const app = new Koa()
const router = new Router()

// the checks return a Promise
router.get('/health', middleware.healthCheck([checkDB]))

app.use(router.routes())
app.use(router.allowedMethods())
```

#### `prometheusMetrics(options)`

科亚 [普罗米修斯](https://prometheus.io/) 测量端点处理器。 默认它收集一些 [默认参数](https://github.com/siimon/prom-client#default-metrics)。 。 。 .

```js
const Koa = require('koa')
const Router = require('koa-router')
const { koa: middleware } = require('@banzaicloud/service-tools').middleware

// ...

const app = new Koa()
const router = new Router()

router.get('/metrics', middleware.prometheusMetrics())

app.use(router.routes())
app.use(router.allowedMethods())
```

#### `requestValidator(options)`

Koa 请求验证器中间软件 。 接受 [乔](https://github.com/hapijs/joi) 计划 `body` (身体解析器要求), `params` 财务报告和审定财务报表 `query` (需要排队). 以 `400` 如果请求无效。 指定验证值为 `ctx.state.validated`。 。 。 .

```js
const joi = require('joi')
const qs = require('qs')
const Koa = require('koa')
const Router = require('koa-router')
const bodyParser = require('koa-bodyparser')
const { koa: middleware } = require('@banzaicloud/service-tools').middleware

// ...

const app = new Koa()
const router = new Router()

const paramsSchema = joi
  .object({
    id: joi
      .string()
      .hex()
      .length(64)
      .required(),
  })
  .required()

const bodySchema = joi.object({ name: joi.string().required() }).required()

const querySchema = joi.object({ include: joi.array().default([]) }).required()

router.get(
  '/',
  middleware.requestValidator({ params: paramsSchema, body: bodySchema, query: querySchema }),
  async function routeHandler(ctx) {
    const { params, body, query } = ctx.state.validated
    // ...
  }
)

app.use(bodyParser())
// query parser
app.use(async function parseQuery(ctx, next) {
  ctx.query = qs.parse(ctx.querystring, options)
  ctx.request.query = ctx.query
  await next()
})
app.use(router.routes())
app.use(router.allowedMethods())
```

#### `requestLogger(options)`

Koa 请求日志中间软件 。 用于本地开发与调试.

```js
const Koa = require('koa')
const { koa: middleware } = require('@banzaicloud/service-tools').middleware

// ...

const app = new Koa()

// this should be the second middleware after the error handler
// ...
app.use(middleware.requestLogger())
```

### 中间软件( Express)

数个中间软件 [快递](https://expressjs.com/) 网络框架.

#### `errorHandler(options)`

快捷错误处理器中间软件 .

```js
const express = require('express')
const { express: middleware } = require('@banzaicloud/service-tools').middleware

const app = express()

// this should be the last middleware
app.use(middleware.errorHandler())
```

#### `healthCheck(checks, options)`

快递健康检查端点处理器.

```js
const express = require('express')
const { express: middleware } = require('@banzaicloud/service-tools').middleware

// ...

const app = express()

// the checks return a Promise
app.get('/health', middleware.healthCheck([checkDB]))
```

#### `prometheusMetrics(options)`

快递 [普罗米修斯](https://prometheus.io/) 测量端点处理器。 默认它收集一些 [默认参数](https://github.com/siimon/prom-client#default-metrics)。 。 。 .

```js
const express = require('express')
const { express: middleware } = require('@banzaicloud/service-tools').middleware

// ...

const app = express()

app.get('/metrics', middleware.prometheusMetrics())
```

#### `requestValidator(options)`

Express 请求验证器中间软件. 接受 [乔](https://github.com/hapijs/joi) 计划 `body` (身体解析器要求), `params` 财务报告和审定财务报表 `query`返回时使用 `400` 如果请求无效。 指定验证值为 `req`。 。 。 .

```js
const joi = require('joi')
const express = require('express')
const { express: middleware } = require('@banzaicloud/service-tools').middleware

// ...

const app = express()

const paramsSchema = joi
  .object({
    id: joi
      .string()
      .hex()
      .length(64)
      .required(),
  })
  .required()

const bodySchema = joi.object({ name: joi.string().required() }).required()

const querySchema = joi.object({ include: joi.array().default([]) }).required()

app.use(express.json())
app.get(
  '/',
  middleware.requestValidator({ params: paramsSchema, body: bodySchema, query: querySchema }),
  function routeHandler(req, res) {
    const { params, body, query } = req
    // ...
  }
)
```

## 常见问题

### @banzaicloud/service-tools 是什么？

常见案例的节点服务工具

### 如何安装 @banzaicloud/service-tools？

在项目目录运行 npm install @banzaicloud/service-tools，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：koa（\>=2\.5\.2 \< 3\.0\.0）、express（\>=4\.16\.3 \< 5\.0\.0）、@hapi/hapi（\>=19\.0\.0 \< 20\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @banzaicloud/service-tools 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @banzaicloud/service-tools 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @banzaicloud/service-tools 可以商用吗？

@banzaicloud/service-tools 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @banzaicloud/service-tools 的下载量有多少？

根据 npm 官方下载统计，@banzaicloud/service-tools 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,081 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @banzaicloud/service-tools 还在维护吗？

最新版本 4\.0\.6 发布于 2021/07/07（5 年前）；至今共发布 49 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/08/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。