# @6thbridge/utils 中文文档

规范地址：https://npmcn.com/package/%406thbridge/utils/

版本：1\.10\.5
npm 元数据更新时间：2026-11-05T22:45:12.177Z
中文译文更新时间：2026-11-06T17:03:29.766Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%406thbridge/utils
原文对照：https://npmcn.com/package/%406thbridge/utils/?lang=original
源码仓库：https://github.com/DexlerNG/bridge-utils-package

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

- 包体积（解压后）：800 kB，267 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：24 个
- 首次发布：2024-05-01T16:38:07.114Z
- 最新版本发布：2026-11-05T22:45:12.004Z
- 近 30 天下载量：2653（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：153（近 12 个月 71 个）

## 中文简介

我们常用函数的简单接口

## 安装

```sh
npm install @6thbridge/utils
```

也可以使用：`pnpm add @6thbridge/utils`、`yarn add @6thbridge/utils`、`bun add @6thbridge/utils`

## README

# @ 6thbridge/ 使用文档

[](https://badge.fury.io/js/%406thbridge%2Futils)[](https://opensource.org/licenses/ISC)一个用于Node.js应用程序的综合性TypeScript通用库,为包括数据库操作,缓存,消息,日志等共同开发任务提供可再使用的组件.

## 目录

-   [安装](https://npmcn.com/package/%406thbridge/utils/#readme-installation)
-   [快速启动](https://npmcn.com/package/%406thbridge/utils/#readme-quick-start)
-   [伙伴 API 密钥和路径](https://npmcn.com/package/%406thbridge/utils/#readme-partner-api-keys-and-routes)
-   [核心单元](https://npmcn.com/package/%406thbridge/utils/#readme-core-modules)
-   [API 参考](https://npmcn.com/package/%406thbridge/utils/#readme-api-reference)
-   [实例](https://npmcn.com/package/%406thbridge/utils/#readme-examples)
-   [测试](https://npmcn.com/package/%406thbridge/utils/#readme-testing)
-   [捐款](https://npmcn.com/package/%406thbridge/utils/#readme-contributing)
-   [许可证](https://npmcn.com/package/%406thbridge/utils/#readme-license)

## 安装

```bash
# Using npm
npm install @6thbridge/utils

# Using yarn
yarn add @6thbridge/utils
```

### 依赖关系

此套件包括以下关键依赖性:

-   **数据库**数字 : `mongoose`, , , , , `ioredis` `mongoose-paginate-v2`
-   **通讯**数字 : `amqplib`, , , , , `kafkajs` `amqp-connection-manager`
-   **公用事业**数字 : `lodash`, (中文(简体) ), `dayjs`, (中文(简体) ), `joi`, (中文(简体) ), `axios`
-   **监测**:,, `rollbar` `@opentelemetry/auto-instrumentations-node`

## 快速启动

```typescript
import { 
  HelperUtil, 
  ReferenceUtil, 
  RedisClient, 
  RabbitMQClient,
  MongoDBRepository,
  logger 
} from '@6thbridge/utils';

// Generate a reference
const reference = ReferenceUtil.generateReference('production');

// Use Redis
const redis = RedisClient.getInstance();
await redis.connect({ url: 'redis://localhost:6379' });

// Clean data
const cleanData = HelperUtil.removeFieldsWithEmptyValue(data);

// Log information
logger.info('Application started', { reference });
```

## 伙伴 API 密钥和路径

见 [伙伴 API 密钥和路径](https://npmcn.com/package/%406thbridge/utils/docs/partner-keys-and-routes.md) 页:1 `can(['partner'], [])`,用户服务关键验证合同, `PartnerContextEntity`, (中文(简体) ), 和快递线路注册实例.

## 核心单元

### 🔧 [公用事业](https://npmcn.com/package/%406thbridge/utils/src/utils/README.md)

用于数据操作、参考生成和共同操作的基本功能.

-   **辅助工具**: 数据清理、活动记录、同步设施
-   **参考UTI**: 参考和UUID生成
-   **电话号码格式化**: 国际电话号码格式化

### 🗄️ [数据库](https://npmcn.com/package/%406thbridge/utils/src/database/README.md)

数据库抽象层和寄存器模式.

-   **MongoDB 仓库**: 蒙戈DB与Mongoose的业务
-   **Redis 整合**: 缓存和会话管理

### 📨 [经纪人](https://npmcn.com/package/%406thbridge/utils/src/brokers/README.md)

事件驱动架构的信息代理执行 .

-   **兔子的密度**: AMQP 与兔子MQ的通讯
-   **KafkaJS 一体化**: Apache Kafka 消息流

### 💾 [缓存](https://npmcn.com/package/%406thbridge/utils/src/cache/README.md)

改进业绩的缓存解决方案.

-   **冗余客户**: 基于 Redis 的缓存, 有集群支持
-   **节点缓存**: 用于轻量级应用的内装箱

### 📝 [锁定器](https://npmcn.com/package/%406thbridge/utils/src/logger/README.md)

综合采伐制度分多层和集成.

-   **结构化日志**: JSON 格式日志
-   **多重运输**: 控制台、文件和外部服务记录
-   **跟踪错误**:与监测服务相结合

### 🛡️ [中间软件](https://npmcn.com/package/%406thbridge/utils/src/middlewares/README.md)

Express.js 用于通用功能的中间软件.

-   **认证**: JWT 和 API 密钥验证
-   **验证**: 请求/答复确认
-   **处理错误**: 集中错误处理
-   **限制费率**: 以服务为主的 ioredis 连接重置请求限制

#### 共享费率限制符

```typescript
import Redis from 'ioredis';
import { Ratelimiter } from '@6thbridge/utils';

const redisClient = new Redis(process.env.REDIS_URL);
Ratelimiter.configure({
  redisClient,
  serviceName: 'my-service',
});

const loginLimiter = Ratelimiter.limit({
  keyPrefix: 'login',
  numberOfTries: 5,
  skipSuccessfulRequests: true,
});

// Use loginLimiter as Express middleware on your login route.
```

默认的限制是30分钟窗口内每个IP五次尝试. 越狱了 返回 HTTP 429 与 `errorCode: 'RateLimitExceeded'`设置 `skipSuccessfulRequests` 从计数中排除成功的响应; 它默认为 `false`。 。 。 .

打电话 `Ratelimiter.configure({ redisClient, serviceName })` 启动前 创建限制器。 它接受一个现有的标准 ioredis `Redis` 连接; 呼叫服务拥有连接设置和关闭。 通话 `limit` 在此之前 配置会丢出一个错误。 个人 `limit` 电话不再带客户.

`serviceName` 是可选的,默认为 `process.env.APP_NAME`这样 `Ratelimiter.configure({ redisClient })` 足够当 `APP_NAME` 已经设定. 明确 `serviceName` 以优先为准。 配置抛出( N) 提供服务名称.

每个 Redis 键开头 `rl:<serviceName>:`设置特定路径 `keyPrefix` 在服务中隔离计数器;其默认值为 `rate-limit-key`。例如, 上方的登录限制 `rl:my-service:login:<normalized-ip>`服务 不同名称可以安全共享 Redis. 现有限制保留配置 它们被创造,如果 `configure` 又被调用.

可选同步 `keyGenerator(req, res)` 替换默认密钥, 包括 `keyPrefix`,同时保留服务前缀。 没有它 限制用途 `res.locals.ip`,则 `cf-connecting-ip`, (中文(简体) ), `x-forwarded-for`,则 `ip` 页眉,或 `req.ip`按照顺序, 并规范IPv6地址。 配置可信任的代理来提供这些值 .

该类也作为 `middlewares.Ratelimiter` 从包根.

### 📊 [监测](https://npmcn.com/package/%406thbridge/utils/src/monitoring/README.md)

应用监测和可观察性工具.

-   **打开几何**: 分布式跟踪
-   **Rollbar 整合**: 错误监测和提醒

## API 参考

### 辅助工具

```typescript
class HelperUtil {
  // Async utility
  static async sleep(durationInMs: number = 1000): Promise<void>
  
  // Data cleaning
  static removeFieldsWithEmptyValue(value: any): any
  
  // Activity logging
  static async saveActivityLog(activityLog: SaveActivityLogDTO, options?: any): Promise<void>
}
```

### 参考UTI

```typescript
class ReferenceUtil {
  // Generate environment-specific reference
  static generateReference(env: string): string
  
  // Generate reference with custom prefix
  static generateReferenceWithPrefix(env: string, prefix: string): string
  
  // Generate UUID
  static generateUUID(options?: any): string
}
```

### 冗余客户

```typescript
class RedisClient {
  // Singleton pattern
  static getInstance(): RedisClient
  static resetInstance(): void
  
  // Connection management
  connect(config?: RedisConnect): Commander
  
  // Redis operations
  static getRedis(): Commander
}
```

### 兔子的密度

```typescript
class RabbitMQClient {
  // Singleton pattern
  static getInstance(): RabbitMQClient
  static resetInstance(): void
  
  // Connection and messaging
  connect(config: RabbitMQConnectConfig): AmqpConnectionManager
  static async sendToQueue(queueName: string, payload: any, options?: PublishOptions): Promise<any>
  static async publishToExchange(exchangeName: string, routeKey: string, payload: any, options?: PublishOptions): Promise<any>
  
  // Message consumption
  static listen(queueName: string, options: any, callback: Function): Promise<void>
}
```

### MongoDB 仓库

```typescript
class MongoDBRepository {
  constructor(Model: TypedModel<any>)
  
  // CRUD operations
  create(payload: Record<string, any>, options?: CreateOptions): Promise<any>
  findById(id: string, projection?: ProjectionType<any>, options?: QueryOptions): Promise<any>
  findOne(condition: Record<string, any>, sort?: Record<string, number>, options?: FindOptions): Promise<any>
  find(condition: Record<string, any>, sort?: Record<string, any>, options?: FindOptions): Promise<any>
  
  // Advanced operations
  paginate(condition: Record<string, any>, sort?: Record<string, any>, options?: FindOptions): Promise<PaginateResult<any>>
  updateOne(query: Record<string, any>, update: Record<string, any>, options?: MongooseOptions): Promise<any>
  bulkWrite(bulkWritePayload: any): Promise<any>
}
```

## 实例

### 基本用途实例

#### 数据清理

```typescript
import { HelperUtil } from '@6thbridge/utils';

const dirtyData = {
  name: 'John Doe',
  email: '',
  phone: null,
  address: undefined,
  age: 30
};

const cleanData = HelperUtil.removeFieldsWithEmptyValue(dirtyData);
// Result: { name: 'John Doe', age: 30 }
```

#### 参考生成

```typescript
import { ReferenceUtil } from '@6thbridge/utils';

// Production reference
const prodRef = ReferenceUtil.generateReference('production');
// Example: L20240101120000ABCDE

// Development reference with prefix
const devRef = ReferenceUtil.generateReferenceWithPrefix('development', 'ORDER');
// Example: DORDER20240101120000ABCDE
```

#### 重做操作

```typescript
import { RedisClient } from '@6thbridge/utils';

async function cacheExample() {
  const redis = RedisClient.getInstance();
  redis.connect({
    url: 'redis://localhost:6379',
    keepAlive: true
  });

  // Cache operations
  await RedisClient.getRedis().set('user:123', JSON.stringify({ name: 'John' }));
  const user = await RedisClient.getRedis().get('user:123');
}
```

#### 信件队列

```typescript
import { RabbitMQClient } from '@6thbridge/utils';

async function messagingExample() {
  const broker = RabbitMQClient.getInstance();
  broker.connect({
    url: 'amqp://localhost:5672',
    queues: [
      { queueName: 'user.created' }
    ],
    exchanges: [],
    exchangeBindings: []
  });

  // Send message
  await RabbitMQClient.sendToQueue('user.created', {
    userId: '123',
    event: 'USER_CREATED',
    timestamp: new Date()
  });

  // Listen for messages
  RabbitMQClient.listen('user.created', {}, (message, options) => {
    console.log('Received:', JSON.parse(message));
    options.ack();
  });
}
```

### 电话号码格式化

```typescript
import { formatPhoneNumber, formatPhoneNumberArray } from '@6thbridge/utils';

// Single phone number
let phoneNumber = '08012345678';
phoneNumber = formatPhoneNumber(phoneNumber, 'NG');
console.log(phoneNumber); // 2348012345678

// Multiple phone numbers
let phoneNumbers = ['08012345678', '08012345679'];
phoneNumbers = formatPhoneNumberArray(phoneNumbers, 'NG');
console.log(phoneNumbers); // ['2348012345678', '2348012345679']
```

### 日志

```typescript
import { logger } from '@6thbridge/utils';

// Different log levels
logger.error('Database connection failed', { error: 'Connection refused' });
logger.warn('High memory usage detected', { usage: '85%' });
logger.info('User logged in', { userId: '123' });
logger.debug('Processing request', { requestId: 'req-456' });

// Exception logging
try {
  // risky operation
} catch (error) {
  logger.exception(error, { context: 'user-registration' });
}
```

## 环境变量

库支持各种环境变量配置 :

```bash
# Redis Configuration
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_password
REDIS_URL=redis://localhost:6379
REDIS_CLUSTER_URL=redis://node1:6379,redis://node2:6379

# RabbitMQ Configuration
RABBITMQ_URL=amqp://localhost:5672
RABBITMQ_CLUSTER_URL=amqp://node1:5672,amqp://node2:5672

# Application Configuration
APP_NAME=your-app-name
TZ=Africa/Lagos
LOG_OUT=1

# Service URLs
USER_SERVICE_URL=http://user-service:3000
```

## 测试

该图书馆包括使用Jest的综合测试套房:

```bash
# Run all tests
yarn test

# Run tests in watch mode
yarn test --watch

# Run tests with coverage
yarn test --coverage

# Run specific test file
yarn test reference.util.test.ts
```

### 写入测试

```typescript
import { ReferenceUtil } from '@6thbridge/utils';

describe('ReferenceUtil', () => {
  it('should generate production reference', () => {
    const ref = ReferenceUtil.generateReference('production');
    expect(ref).toMatch(/^L\d{14}[A-Z]{5}$/);
  });
});
```

## 类型脚本支持

此库用 TypeScript 写成, 并提供完整类型定义 :

```typescript
import { 
  RedisConnect, 
  RabbitMQConnectConfig, 
  SaveActivityLogDTO,
  MongooseOptions 
} from '@6thbridge/utils';

// Type-safe configuration
const redisConfig: RedisConnect = {
  url: 'redis://localhost:6379',
  keepAlive: true,
  heartbeat: 30
};
```

## 业绩考量

-   **连接集合**: Redis 和 RabbitMQ 客户端使用连接集合
-   **单子图案**: 数据库和缓存客户端遵循单通模式
-   **懒惰装入**: 仅在需要时才建立连接
-   **内存管理**: 适当清理和关闭连接

## 处理错误

库执行全面的错误处理 :

```typescript
try {
  await RedisClient.getRedis().set('key', 'value');
} catch (error) {
  logger.exception(error, { operation: 'redis-set' });
}
```

## 捐款

1.  叉子存储器
2.  创建您的特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) )
3.  提交更改( E)`git commit -m 'Add amazing feature'`(中文(简体) )
4.  推向分行(`git push origin feature/amazing-feature`(中文(简体) )
5.  打开拉请求

### 开发设置

```bash
# Clone repository
git clone https://github.com/DexlerNG/bridge-utils-package.git

# Install dependencies
yarn install

# Run tests
yarn test

# Build library
yarn build
```

## 许可证

这个项目根据ICC许可证颁发许可证.

## 贡献者

-   [迈克尔·阿金元米](https://github.com/blackhades)

## 支助

欲获取支持和提问,请在 GitHub 存储器上打开一个问题 . **说明**:此图书馆被积极维护和用于生产环境. 请检查date=中的日期值 (帮助) [发布部分](https://github.com/DexlerNG/bridge-utils-package/releases)。 。 。 .

## 出版

将请求拉入 `main` 将软件包发布到 npm 和 GitHub 软件包中,除非牵引请求有 `skip-publish` 标签。 合并前跳出版本 。 添加 `publish-test-version` 到此寄存器库的牵引请求, 将测试版本发布到 GitHub 包 .

仓库行动需要保密:

-   `NPM_TOKEN`: npm 授权发布符 `@6thbridge/utils`。 。 。 .
-   `GH_PACKAGES_TOKEN`: GitHub 个人访问信使(经典) `write:packages` 权限 `6thbridge` 软件包命名空间。 该寄存器目前属于 `DexlerNG`自动 `GITHUB_TOKEN` 无法向该单独的命名空间发布 .

要安装 GitHub 软件包副本, 认证为 `npm.pkg.github.com` 并配置 `@6thbridge:registry=https://npm.pkg.github.com` 在您的 npm 配置中。 寻常 `npm install @6thbridge/utils` 命令使用 npm.

## 日志分批

继续打电话 `logger.info()`, (中文(简体) ), `logger.error()`等 (中文(简体) ). 日志共享数组并冲出 在100条信息或1秒后. `configureLogBatching({ batchSize: 100, flushIntervalMs: 1000 })` 更改这些默认值。 每个冲出一个纯数组 给现有的RabitMQ实例,或 `POST /v1/logs` 当不存在时. 运输选择发生在冲刷时。 向运输故障报告 stderr; 没有背景重试机制 .

打电话 `registerLoggingShutdown()` 一次登记SIGTERM/SIGINT冲洗,或 `await flushLogs()` 明确在关闭运输工具或离开之前。 登记 只冲出库缓冲;它不关闭提供者或退出进程. 未注册关闭时没有自动信号收听器. 在释放更新的日志之前, 在公用事业服务中部署阵列支持 .

向公用事业部门发送10,000个测试日志:

```bash
UTILITY_SERVICE_URL=https://your-utility-service yarn test:logger
```

脚本使用两个日志例并分批分出100个. 它不会开始一个 服务器或验证收件; 检查收到的日志的效用服务.

## 常见问题

### @6thbridge/utils 是什么？

我们常用函数的简单接口

### 如何安装 @6thbridge/utils？

在项目目录运行 npm install @6thbridge/utils，或使用 pnpm add / yarn add / bun add。

### @6thbridge/utils 支持 TypeScript 吗？

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

### @6thbridge/utils 支持 ESM 还是 CommonJS？

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

### @6thbridge/utils 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @6thbridge/utils 可以商用吗？

@6thbridge/utils 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @6thbridge/utils 的下载量有多少？

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

### @6thbridge/utils 还在维护吗？

最新版本 1\.10\.5 发布于 2026/11/06（1 天前）；至今共发布 153 个版本，其中过去 12 个月发布了 71 个；首次发布于 2024/05/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。