@tumbaland / backend-core

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

安装

npm install @tumbaland/backend-core

使用

基本服务设置

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);
  });

使用身份验证

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 工厂-跨所有服务的一个响应契约，所以 监控和仪表板的形状相同：

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 进程退出前的连接：

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 });

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

结构化的日志

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反应

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)，版本独立 和 标准版 和 传统的提交。看词根 README的“提交和发布”部分 要查看整个过程 其背后的原因——总结：使用常规消息提交，然后从这个目录提交 运行 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. 提交拉取请求