# @tumbaland/backend-core 中文文档

规范地址：https://npmcn.com/package/%40tumbaland/backend-core/

版本：1\.57\.0
npm 元数据更新时间：2026-11-02T16:39:44.557Z
中文译文更新时间：2026-11-02T18:40:28.113Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40tumbaland/backend-core
原文对照：https://npmcn.com/package/%40tumbaland/backend-core/?lang=original

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

- 包体积（解压后）：589 kB，276 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：18 个
- peer 依赖：express ^5\.2\.1，mongoose ^9\.7\.3
- 首次发布：2026-07-12T13:10:34.086Z
- 最新版本发布：2026-11-02T16:39:44.362Z
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

Tumbaland后端服务的核心共享功能

## 安装

```sh
npm install @tumbaland/backend-core
```

也可以使用：`pnpm add @tumbaland/backend-core`、`yarn add @tumbaland/backend-core`、`bun add @tumbaland/backend-core`

## README

# @tumbaland / backend-core

Tumbaland后端服务的核心共享功能。

## 安装

```bash
npm install @tumbaland/backend-core
```

## 使用

### 基本服务设置

```typescript
import express from 'express';
import {
  logger,
  healthCheck,
  connectDB,
  requestLogger,
  errorHandler,
  correlationMiddleware
} from '@tumbaland/backend-core';

const app = express();

// Environment variables
process.env.SERVICE_NAME = 'my-service';
process.env.SERVICE_DESCRIPTION = 'My awesome service';

// Middleware
app.use(correlationMiddleware);
app.use(requestLogger);

// Routes
app.get('/health', healthCheck);

// Error handling (must be last)
app.use(errorHandler);

// Start server
connectDB()
  .then(() => {
    const PORT = process.env.PORT || 3000;
    app.listen(PORT, () => {
      logger.info(`🚀 Service running on port ${PORT}`);
    });
  })
  .catch((error) => {
    logger.error('Failed to start service:', error);
    process.exit(1);
  });
```

### 使用身份验证

```typescript
import { authenticateToken } from '@tumbaland/backend-core';

app.get('/protected', authenticateToken, (req, res) => {
  const user = (req as any).user;
  res.json({ message: `Hello ${user.name}!` });
});
```

### 运行状况检查（统一标准）

每个服务都装载相同的内容 `/health` 就绪状态端点 `createHealthCheck` 工厂-跨所有服务的一个响应契约，所以 监控和仪表板的形状相同：

```typescript
import { createHealthCheck } from '@tumbaland/backend-core';

// DB-backed service (default): reports `dependencies.mongodb` and returns 503
// while the connection is down.
export const healthCheck = createHealthCheck({
  service: 'my-service',
  description: 'My awesome service'
});

// Service with no database: readiness is a static ok, no `dependencies`.
export const healthCheck = createHealthCheck({
  service: 'public-service',
  description: 'Public API endpoints service',
  checkDatabase: false
});

app.get('/health', healthCheck);
```

身体反应: `{ status, service, type: 'backend', timestamp, version, description }`， 加上 `dependencies.mongodb` 当 `checkDatabase` 正在进行。 `/health/live` (活性, 没有依赖检查——由Docker使用 `HEALTHCHECK`)分别由 `createBaseApp`.

### 优雅的关闭

`registerShutdown` 电线 `SIGINT` **和** `SIGTERM` (Docker/Kubernetes的信号 在停止和rollout时发送)以耗尽HTTP服务器并关闭MongoDB 进程退出前的连接：

```typescript
import { registerShutdown } from '@tumbaland/backend-core';

const server = app.listen(PORT, () => logger.info('Service started', { port: PORT }));

// DB-backed service
registerShutdown({ serviceName: 'my-service', server });

// No-DB service: skip the Mongo disconnect
registerShutdown({ serviceName: 'public-service', server, disconnectDatabase: false });
```

处理程序是幂等的，并且自武装一个强制退出定时器，因此挂起关闭静止 终止。

### 结构化的日志

```typescript
import { logger } from '@tumbaland/backend-core';

// Different log levels
logger.error('Database connection failed', { error: err.message });
logger.warn('High memory usage detected', { usage: '85%' });
logger.info('User logged in', { userId: '123', ip: '192.168.1.1' });
logger.debug('Processing request', { correlationId: req.correlationId });
```

### API反应

```typescript
import { sendSuccess, sendError } from '@tumbaland/backend-core';

app.get('/api/users', (req, res) => {
  // Success response
  sendSuccess(res, users, 'Users retrieved successfully');

  // Error response
  sendError(res, 'Failed to retrieve users', 500, 'Database error');
});
```

## 环境变量

-   `NODE_ENV`： `development` 或者 `production`
-   `SERVICE_NAME`您的服务名称
-   `SERVICE_DESCRIPTION`您的服务描述
-   `LOG_TO_FILE`：设置为 `true` 也可以记录到文件（仅限开发）

## 码头工人伐木

这个库针对Docker部署进行了优化：

-   默认情况下记录到stdout/stderr
-   在生产中使用结构化JSON
-   与Docker日志驱动程序集成
-   兼容日志聚合工具（ELK， Loki等）

## 开发vs生产

### 开发

-   彩色控制台输出
-   调试级日志记录
-   人类可读的格式

### 生产

-   JSON结构化日志
-   信息级及以上
-   针对日志聚合进行了优化

## 📦发布和版本管理

这个库是一个真正发布的npm包(`@tumbaland/backend-core`)，版本独立 和 [标准版](https://github.com/conventional-changelog/standard-version) 和 [传统的提交](https://conventionalcommits.org/)。看词根 [README的“提交和发布”部分](https://npmcn.com/package/README.md#commits--releases) 要查看整个过程 其背后的原因——总结：使用常规消息提交，然后从这个目录提交 运行 `npm run release` (不要手动编辑 `version` 和 `npm publish` 直接，或者包装， Changelog，和标签偏离彼此的同步)。此包的标记范围为 `backend-core-vX.Y.Z` 所以它们不会碰撞 `frontend-core`的年代, `components`’，或者 monorepo的 `app-vX.Y.Z` 标签。

* * *

## 贡献

1.  中的源文件进行更改 `src/`
2.  运行 `npm run build` 编译TypeScript
3.  测试您的更改
4.  提交拉取请求

## 常见问题

### @tumbaland/backend-core 是什么？

Tumbaland后端服务的核心共享功能

### 如何安装 @tumbaland/backend-core？

在项目目录运行 npm install @tumbaland/backend-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（^5\.2\.1）、mongoose（^9\.7\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @tumbaland/backend-core 支持 TypeScript 吗？

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

### @tumbaland/backend-core 支持 ESM 还是 CommonJS？

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

### @tumbaland/backend-core 可以商用吗？

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

### @tumbaland/backend-core 还在维护吗？

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