@gaias/basenode

English | 简体中文

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

English

A comprehensive Node.js API development framework built on Koa, TypeORM, TypeDI, and routing-controllers. Provides a microframework architecture with built-in support for RESTful APIs, WebSocket controllers, database ORM, distributed events, Redis caching, and API gateway integration.

Features

• Modern Framework Stack: Koa 3.x, TypeORM 0.3.x, TypeDI, routing-controllers
• TypeScript First: Full TypeScript support with decorators and strict type checking
• RESTful & WebSocket: Support for both REST APIs and WebSocket controllers
• Database ORM: TypeORM with MySQL/MariaDB support, automatic entity generation
• Dependency Injection: TypeDI-based IoC container for clean architecture
• Validation: class-validator with i18n support for error messages
• Caching: Two-level caching (L1 in-memory, L2 Redis)
• Distributed Events: RabbitMQ-based pub/sub system
• API Gateway: APISIX integration for service registration
• Leader Election: Redis-based leader election for distributed systems
• Health Check: Built-in health check endpoint with system metrics
• Pagination: Complete pagination solution with sorting support
• Security: Built-in security features, vulnerability tracking, and mitigation
• OpenAPI: Automatic OpenAPI/Swagger documentation generation
• Development Tools: Hot reload, linting, testing, code generation

Quick Start

Prerequisites

• Node.js >= 18.0.0
• Yarn >= 1.22.x
• MariaDB/MySQL 5.7+ or 8.0+ (for production)
• Redis 6.0+ (optional, for caching)
• RabbitMQ 3.8+ (optional, for distributed events)

Installation

# Clone the repository
git clone https://github.com/gaias/basenode.git
cd basenode

# Install dependencies
yarn install

Configuration

1. Database Configuration

Edit cfg/database.yml:

mariaDBUrl: mysql://username:password@localhost:3306/database
output: ./example

2. Application Configuration

Edit cfg/application.yml:

appName: example
version: 1
port: 3000
privateKeyPath: ./keys/privateKey
publicKeyPath: ./keys/publicKey

3. Redis Configuration (Optional)

Edit cfg/redis.yml:

host: localhost
port: 6379
password: your_password
db: 0

4. RabbitMQ Configuration (Optional)

Edit cfg/rabbitmq.yml:

url: amqp://localhost:5672

5. Environment Variables (Optional)

Create a .env file or export variables:

NODE_ENV=development                        # Environment: development, production, test
ENABLE_API_GATEWAY=true                     # Enable APISIX gateway registration
API_GATEWAY_HOST_PORT=192.168.1.100:9180    # Gateway admin API address
DOMAINS=example.com,*.example.com           # Allowed domains for gateway

Running the Application

# Development mode with hot reload
yarn dev

# Development mode with API gateway enabled
yarn devPro

# Production mode (after building)
yarn ncc:run

The application will start on http://localhost:3000 (or configured port).

Access the health check endpoint: http://localhost:3000/_healthcheck

Project Structure

.
├── src/                    # Framework source code
│   ├── libs/              # Framework components
│   │   ├── apisix/        # APISIX HTTP client
│   │   ├── cache/         # Two-level caching system
│   │   ├── configure/     # YAML configuration management
│   │   ├── deps/          # Dependency library exports
│   │   ├── error/         # Error handling
│   │   ├── gateway/       # API Gateway integration
│   │   ├── generator/     # ID generation (nanoid, snowflake)
│   │   ├── healthcheck/   # Health check endpoint
│   │   ├── koa/           # Koa server setup
│   │   ├── leader/        # Redis-based leader election
│   │   ├── logger/        # Pino logger wrapper
│   │   ├── network/       # Network utilities
│   │   ├── orm/           # TypeORM extensions
│   │   ├── pagination/    # Pagination utilities
│   │   ├── rabbitmq/      # RabbitMQ distributed events
│   │   ├── redis/         # Redis client wrapper
│   │   ├── register/      # API route registration
│   │   ├── type/          # Type definitions
│   │   ├── universal/     # Universal CRUD patterns
│   │   └── validator/     # Validation helpers
│   ├── server/            # Bootstrap logic
│   └── utils/             # Utilities (JWT, crypto, YAML)
├── example/               # Example application
│   ├── app.ts            # Entry point
│   ├── controllers/       # RESTful controllers
│   ├── wsControllers/     # WebSocket controllers
│   ├── entities/          # TypeORM entities
│   ├── repositories/      # Repository classes
│   ├── services/          # Business logic services
│   ├── vo/                # Value Objects (DTOs)
│   └── events/            # Distributed event handlers
├── cfg/                   # YAML configuration files
│   ├── application.yml    # App settings
│   ├── database.yml       # Database connection
│   ├── redis.yml          # Redis connection
│   ├── rabbitmq.yml       # RabbitMQ connection
│   ├── logger.yml         # Logger settings
│   ├── apisix.apikey.yml  # API gateway settings
│   └── openapi.yml        # OpenAPI/Swagger config
├── tools/                 # Development tools
│   ├── DBSchemaGenerator.ts      # Generate entities from DB
│   ├── RepositoryGenerator.ts    # Generate repositories
│   └── repository.mst            # Mustache template
├── docs/                  # Documentation
├── k8s/                   # Kubernetes manifests
└── keys/                  # JWT keys (generated)

Development Commands

Running

# Development with hot reload
yarn dev

# Development with API gateway
yarn devPro

# Run compiled app
yarn ncc:run

Building

# Build for publishing
yarn build:publish

# Build single-file executable
yarn ncc:build

Database Code Generation

# Generate entities from database schema
yarn gen:db-schema

# Generate repository classes
yarn gen:db-repo

# Generate both entities and repositories
yarn gen:db

# Generate index files
yarn gen:idx

Note: Define tables to generate in gen_db.json before running.

Testing & Quality

# Run tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage
yarn test:coverage

# Type check and lint
yarn lint

# Auto-fix linting issues
yarn lint:fix

Security

# Run security audit
yarn security

# Show audit summary
yarn security:summary

# Enhanced security check (recommended)
yarn security:check

# Generate security report
yarn security:json

See docs/SECURITY.md for comprehensive security guidelines.

Dependency Management

# Check for outdated dependencies
yarn deps:check

# Update dependencies
yarn deps:update

Other Tools

# Generate RSA keys for JWT
yarn gen:keys

# Update build number
yarn buildNum

Usage Examples

Creating a RESTful Controller

import { rest, di } from '@/libs/deps';
import { UniversalController } from '@/libs/universal';
import { UserService } from './services/UserService';
import { UserVo } from './vo/UserVo';

@rest.JsonController('/api/users')
@di.Service()
export class UserController extends UniversalController {
  @di.Inject()
  private userService: UserService;

  @rest.Get('/')
  async getAll() {
    return this.userService.getAll(UserVo);
  }

  @rest.Post('/')
  async create(@rest.Body() data: UserVo) {
    return this.userService.create(data);
  }

  @rest.Get('/:id')
  async getById(@rest.Param('id') id: number) {
    return this.userService.readById(id, UserVo);
  }
}

Creating a Service with Repository

import { di } from '@/libs/deps';
import { UniversalService } from '@/libs/universal';
import { User } from './entities/User';
import { UserRepo } from './repositories/UserRepo';

@di.Service()
export class UserService extends UniversalService<User> {
  constructor(@di.Inject(() => UserRepo) private userRepo: UserRepo) {
    super(userRepo);
  }

  async findByEmail(email: string): Promise<User | null> {
    return this.userRepo.findOne({ where: { email } });
  }
}

Validation with VO (Value Object)

import { cv } from '@/libs/deps';
import { i18n } from '@/libs/validator';
import { IsSafeUrl } from '@/libs/validator';

export class UserVo {
  @i18n(cv.IsString)
  @i18n(cv.MaxLength, 50)
  userName: string;

  @i18n(cv.IsEmail)
  email: string;

  @IsSafeUrl()
  website?: string;

  @i18n(cv.IsOptional)
  @i18n(cv.MinLength, 6)
  password?: string;
}

Pagination

import { rest, di } from '@/libs/deps';
import { PaginationIn, PaginationOut } from '@/libs/pagination';
import { UserService } from './services/UserService';
import { UserVo } from './vo/UserVo';

@rest.JsonController('/api/users')
@di.Service()
export class UserController {
  @di.Inject()
  private userService: UserService;

  @rest.Post('/search')
  async search(@rest.Body() pagination: PaginationIn): Promise<PaginationOut<UserVo, User>> {
    return this.userService.search(pagination);
  }
}

Caching

import { rest, di } from '@/libs/deps';
import { L1Cache } from '@/libs/cache';
import { CacheService } from '@/libs/cache';

@rest.JsonController('/api/data')
@di.Service()
export class DataController {
  @di.Inject()
  private cacheService: CacheService;

  @rest.Get('/cached')
  @L1Cache({ ttlSeconds: 60 })
  async getCachedData() {
    // L1 cache - in-memory
    return { data: 'This is cached for 60 seconds' };
  }

  @rest.Get('/redis')
  async getRedisData() {
    // L2 cache - Redis
    const cached = await this.cacheService.get('key');
    if (cached) return cached;

    const data = { data: 'Fresh data' };
    await this.cacheService.set('key', data, 300);
    return data;
  }
}

Distributed Events

import { di } from '@/libs/deps';
import { DistributedEvents } from '@/libs/rabbitmq';

@di.Service()
export class UserService {
  @di.Inject()
  private events: DistributedEvents;

  async createUser(data: UserVo) {
    const user = await this.userRepo.save(data);

    // Publish event to RabbitMQ
    await this.events.pub('user.created', { userId: user.id });

    return user;
  }
}

// Event handler
@di.Service()
export class UserEventHandler {
  @di.Inject()
  private events: DistributedEvents;

  async init() {
    // Subscribe to events
    await this.events.sub(['user.created']);

    this.events.on('RemoteEvent', (eventName, data) => {
      if (eventName === 'user.created') {
        console.log('User created:', data);
      }
    });
  }
}

Key Technologies

Core Framework

• Koa 3.0.3 - Lightweight web framework
• routing-controllers 0.11.3 - Decorator-based routing
• socket-controllers 0.3.1 - WebSocket controllers
• TypeDI 0.10.0 - Dependency injection
• microframework 0.6.4 - Loader pattern

Data Layer

• TypeORM 0.3.27 - SQL ORM
• typeorm-transactional 0.5.0 - Transaction management
• mysql2 3.15.2 - MySQL/MariaDB driver
• class-validator 0.14.2 - Validation
• class-transformer 0.5.1 - Transformation

Caching & Messaging

• ioredis 5.8.1 - Redis client
• amqplib 0.10.9 - RabbitMQ client

Utilities

• pino 10.0.0 - High-performance logger
• jsonwebtoken 9.0.2 - JWT authentication
• nanoid 5.1.6 - Unique ID generator
• axios 1.12.2 - HTTP client
• helmet 8.1.0 - Security headers

Documentation

• CLAUDE.md - Comprehensive framework documentation
• docs/SECURITY.md - Security guidelines and best practices
• docs/VULNERABILITY_MITIGATION.md - Vulnerability tracking
• docs/QUICKSTART.md - Quick start guide
• docs/PUBLISHING.md - Publishing guide
• docs/BUILD_AND_USE.md - Building and usage instructions
• docs/DOCKER_OPTIMIZATION.md - Docker optimization guide

Module Documentation

• src/libs/deps/README.md - Unified dependency exports
• src/libs/validator/README.md - Validation helpers
• src/libs/apisix/README.md - API gateway integration
• src/libs/gateway/README.md - Gateway loader
• src/libs/generator/README.md - ID generation
• src/libs/koa/README.md - Koa server setup
• src/libs/network/README.md - Network utilities
• src/libs/rabbitmq/README.md - Distributed events
• src/libs/register/README.md - API route registration
• src/libs/type/README.md - Type utilities
• src/libs/universal/README.md - Universal CRUD patterns

Security

This project takes security seriously. We use:

• Regular security audits with yarn security:check
• Dependency vulnerability tracking and mitigation
• Custom validators to avoid known CVEs (e.g., @IsSafeUrl() instead of @IsUrl())
• Secure dependency resolutions for transitive dependencies
• Security documentation and best practices

See docs/SECURITY.md for detailed information.

Important: Always use @IsSafeUrl() instead of @IsUrl() to avoid CVE-2025-56200.

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch from develope
3. Make your changes with descriptive commits
4. Run tests and linting: yarn test && yarn lint
5. Run security check: yarn security:check
6. Create a pull request to develope branch

Development Guidelines

• Follow existing code conventions
• Use TypeScript strict mode
• Add JSDoc comments for public APIs
• Write tests for new features
• Update documentation as needed

Publishing

This is a private npm package. To publish:

# Update version in package.json
# Update build number
yarn buildNum

# Run pre-publish checks
yarn publish:check

# Build for publishing
yarn build:publish

# Publish to npm
yarn publish:npmjs

# Or publish to GitHub packages
yarn publish:github

See docs/PUBLISHING.md for detailed publishing instructions.

Troubleshooting

Database Connection Issues

• Verify cfg/database.yml connection string
• Check MariaDB/MySQL is running
• Ensure database user has proper permissions

Redis Connection Issues

• Check Redis is running: redis-cli ping
• Verify cfg/redis.yml settings
• Can disable Redis by setting disableRedis: true in bootstrap

TypeORM Entity Not Found

• Ensure entity is registered in bootstrap entities array
• Check entity file has @Entity() decorator
• Verify import path is correct

License

UNLICENSED - Private package

Author

FOT Team

Links

• Repository
• Issue Tracker
• npm Package

Version History

• 1.3.6 (Current) - Latest updates and improvements
• 1.0.13 - Security enhancements and dependency updates
• 1.0.0 - Initial release

简体中文

一个基于 Koa、TypeORM、TypeDI 和 routing-controllers 构建的全面的 Node.js API 开发框架。提供微框架架构，内置支持 RESTful API、WebSocket 控制器、数据库 ORM、分布式事件、Redis 缓存和 API 网关集成。

特性

• 现代框架栈：Koa 3.x、TypeORM 0.3.x、TypeDI、routing-controllers
• TypeScript 优先：完整的 TypeScript 支持，包括装饰器和严格类型检查
• RESTful 和 WebSocket：同时支持 REST API 和 WebSocket 控制器
• 数据库 ORM：TypeORM 支持 MySQL/MariaDB，自动生成实体
• 依赖注入：基于 TypeDI 的 IoC 容器，实现清晰架构
• 验证：class-validator 支持国际化错误消息
• 缓存：双层缓存（L1 内存、L2 Redis）
• 分布式事件：基于 RabbitMQ 的发布/订阅系统
• API 网关：APISIX 集成实现服务注册
• 领导者选举：基于 Redis 的分布式系统领导者选举
• 健康检查：内置健康检查端点和系统指标
• 分页：完整的分页解决方案，支持排序
• 安全性：内置安全特性、漏洞跟踪和缓解措施
• OpenAPI：自动生成 OpenAPI/Swagger 文档
• 开发工具：热重载、代码检查、测试、代码生成

快速开始

系统要求

• Node.js >= 18.0.0
• Yarn >= 1.22.x
• MariaDB/MySQL 5.7+ 或 8.0+（生产环境）
• Redis 6.0+（可选，用于缓存）
• RabbitMQ 3.8+（可选，用于分布式事件）

安装

# 克隆仓库
git clone https://github.com/gaias/basenode.git
cd basenode

# 安装依赖
yarn install

配置

1. 数据库配置

编辑 cfg/database.yml：

mariaDBUrl: mysql://用户名:密码@localhost:3306/数据库名
output: ./example

2. 应用配置

编辑 cfg/application.yml：

appName: example
version: 1
port: 3000
privateKeyPath: ./keys/privateKey
publicKeyPath: ./keys/publicKey

3. Redis 配置（可选）

编辑 cfg/redis.yml：

host: localhost
port: 6379
password: 你的密码
db: 0

4. RabbitMQ 配置（可选）

编辑 cfg/rabbitmq.yml：

url: amqp://localhost:5672

5. 环境变量（可选）

创建 .env 文件或导出变量：

NODE_ENV=development                        # 环境：development、production、test
ENABLE_API_GATEWAY=true                     # 启用 APISIX 网关注册
API_GATEWAY_HOST_PORT=192.168.1.100:9180    # 网关管理 API 地址
DOMAINS=example.com,*.example.com           # 网关允许的域名

运行应用

# 开发模式（热重载）
yarn dev

# 开发模式（启用 API 网关）
yarn devPro

# 生产模式（构建后）
yarn ncc:run

应用将在 http://localhost:3000（或配置的端口）启动。

访问健康检查端点：http://localhost:3000/_healthcheck

项目结构

.
├── src/                    # 框架源代码
│   ├── libs/              # 框架组件
│   │   ├── apisix/        # APISIX HTTP 客户端
│   │   ├── cache/         # 双层缓存系统
│   │   ├── configure/     # YAML 配置管理
│   │   ├── deps/          # 依赖库导出
│   │   ├── error/         # 错误处理
│   │   ├── gateway/       # API 网关集成
│   │   ├── generator/     # ID 生成（nanoid、snowflake）
│   │   ├── healthcheck/   # 健康检查端点
│   │   ├── koa/           # Koa 服务器设置
│   │   ├── leader/        # 基于 Redis 的领导者选举
│   │   ├── logger/        # Pino 日志包装器
│   │   ├── network/       # 网络工具
│   │   ├── orm/           # TypeORM 扩展
│   │   ├── pagination/    # 分页工具
│   │   ├── rabbitmq/      # RabbitMQ 分布式事件
│   │   ├── redis/         # Redis 客户端包装器
│   │   ├── register/      # API 路由注册
│   │   ├── type/          # 类型定义
│   │   ├── universal/     # 通用 CRUD 模式
│   │   └── validator/     # 验证辅助工具
│   ├── server/            # 启动逻辑
│   └── utils/             # 工具类（JWT、加密、YAML）
├── example/               # 示例应用
│   ├── app.ts            # 入口点
│   ├── controllers/       # RESTful 控制器
│   ├── wsControllers/     # WebSocket 控制器
│   ├── entities/          # TypeORM 实体
│   ├── repositories/      # 仓储类
│   ├── services/          # 业务逻辑服务
│   ├── vo/                # 值对象（DTO）
│   └── events/            # 分布式事件处理器
├── cfg/                   # YAML 配置文件
│   ├── application.yml    # 应用设置
│   ├── database.yml       # 数据库连接
│   ├── redis.yml          # Redis 连接
│   ├── rabbitmq.yml       # RabbitMQ 连接
│   ├── logger.yml         # 日志设置
│   ├── apisix.apikey.yml  # API 网关设置
│   └── openapi.yml        # OpenAPI/Swagger 配置
├── tools/                 # 开发工具
│   ├── DBSchemaGenerator.ts      # 从数据库生成实体
│   ├── RepositoryGenerator.ts    # 生成仓储类
│   └── repository.mst            # Mustache 模板
├── docs/                  # 文档
├── k8s/                   # Kubernetes 清单
└── keys/                  # JWT 密钥（生成的）

开发命令

运行

# 开发模式（热重载）
yarn dev

# 开发模式（带 API 网关）
yarn devPro

# 运行编译后的应用
yarn ncc:run

构建

# 构建用于发布
yarn build:publish

# 构建单文件可执行文件
yarn ncc:build

数据库代码生成

# 从数据库架构生成实体
yarn gen:db-schema

# 生成仓储类
yarn gen:db-repo

# 生成实体和仓储
yarn gen:db

# 生成索引文件
yarn gen:idx

注意：运行前在 gen_db.json 中定义要生成的表。

测试与质量

# 运行测试
yarn test

# 监视模式运行测试
yarn test:watch

# 带覆盖率运行测试
yarn test:coverage

# 类型检查和代码检查
yarn lint

# 自动修复代码检查问题
yarn lint:fix

安全

# 运行安全审计
yarn security

# 显示审计摘要
yarn security:summary

# 增强安全检查（推荐）
yarn security:check

# 生成安全报告
yarn security:json

查看 docs/SECURITY.md 了解全面的安全指南。

依赖管理

# 检查过时的依赖
yarn deps:check

# 更新依赖
yarn deps:update

其他工具

# 为 JWT 生成 RSA 密钥
yarn gen:keys

# 更新构建编号
yarn buildNum

使用示例

创建 RESTful 控制器

import { rest, di } from '@/libs/deps';
import { UniversalController } from '@/libs/universal';
import { UserService } from './services/UserService';
import { UserVo } from './vo/UserVo';

@rest.JsonController('/api/users')
@di.Service()
export class UserController extends UniversalController {
  @di.Inject()
  private userService: UserService;

  @rest.Get('/')
  async getAll() {
    return this.userService.getAll(UserVo);
  }

  @rest.Post('/')
  async create(@rest.Body() data: UserVo) {
    // rest.Body 自动启用 excludeExtraneousValues 以提高安全性
    return this.userService.create(data);
  }

  @rest.Get('/:id')
  async getById(@rest.Param('id') id: number) {
    return this.userService.readById(id, UserVo);
  }
}

创建带仓储的服务

import { di } from '@/libs/deps';
import { UniversalService } from '@/libs/universal';
import { User } from './entities/User';
import { UserRepo } from './repositories/UserRepo';

@di.Service()
export class UserService extends UniversalService<User> {
  constructor(@di.Inject(() => UserRepo) private userRepo: UserRepo) {
    super(userRepo);
  }

  async findByEmail(email: string): Promise<User | null> {
    return this.userRepo.findOne({ where: { email } });
  }
}

使用 VO 进行验证

import { cv } from '@/libs/deps';
import { i18n } from '@/libs/validator';
import { IsSafeUrl } from '@/libs/validator';

export class UserVo {
  @i18n(cv.IsString)
  @i18n(cv.MaxLength, 50)
  userName: string;

  @i18n(cv.IsEmail)
  email: string;

  @IsSafeUrl()
  website?: string;

  @i18n(cv.IsOptional)
  @i18n(cv.MinLength, 6)
  password?: string;
}

分页

import { rest, di } from '@/libs/deps';
import { PaginationIn, PaginationOut } from '@/libs/pagination';
import { UserService } from './services/UserService';
import { UserVo } from './vo/UserVo';

@rest.JsonController('/api/users')
@di.Service()
export class UserController {
  @di.Inject()
  private userService: UserService;

  @rest.Post('/search')
  async search(@rest.Body() pagination: PaginationIn): Promise<PaginationOut<UserVo, User>> {
    return this.userService.search(pagination);
  }
}

缓存

import { rest, di } from '@/libs/deps';
import { L1Cache } from '@/libs/cache';
import { CacheService } from '@/libs/cache';

@rest.JsonController('/api/data')
@di.Service()
export class DataController {
  @di.Inject()
  private cacheService: CacheService;

  @rest.Get('/cached')
  @L1Cache({ ttlSeconds: 60 })
  async getCachedData() {
    // L1 缓存 - 内存
    return { data: '这将被缓存 60 秒' };
  }

  @rest.Get('/redis')
  async getRedisData() {
    // L2 缓存 - Redis
    const cached = await this.cacheService.get('key');
    if (cached) return cached;

    const data = { data: '新数据' };
    await this.cacheService.set('key', data, 300);
    return data;
  }
}

分布式事件

import { di } from '@/libs/deps';
import { DistributedEvents } from '@/libs/rabbitmq';

@di.Service()
export class UserService {
  @di.Inject()
  private events: DistributedEvents;

  async createUser(data: UserVo) {
    const user = await this.userRepo.save(data);

    // 发布事件到 RabbitMQ
    await this.events.pub('user.created', { userId: user.id });

    return user;
  }
}

// 事件处理器
@di.Service()
export class UserEventHandler {
  @di.Inject()
  private events: DistributedEvents;

  async init() {
    // 订阅事件
    await this.events.sub(['user.created']);

    this.events.on('RemoteEvent', (eventName, data) => {
      if (eventName === 'user.created') {
        console.log('用户已创建:', data);
      }
    });
  }
}

核心技术

核心框架

• Koa 3.0.3 - 轻量级 Web 框架
• routing-controllers 0.11.3 - 基于装饰器的路由
• socket-controllers 0.3.1 - WebSocket 控制器
• TypeDI 0.10.0 - 依赖注入
• microframework 0.6.4 - 加载器模式

数据层

• TypeORM 0.3.27 - SQL ORM
• typeorm-transactional 0.5.0 - 事务管理
• mysql2 3.15.2 - MySQL/MariaDB 驱动
• class-validator 0.14.2 - 验证
• class-transformer 0.5.1 - 转换

缓存与消息

• ioredis 5.8.1 - Redis 客户端
• amqplib 0.10.9 - RabbitMQ 客户端

工具

• pino 10.0.0 - 高性能日志
• jsonwebtoken 9.0.2 - JWT 认证
• nanoid 5.1.6 - 唯一 ID 生成器
• axios 1.12.2 - HTTP 客户端
• helmet 8.1.0 - 安全头

文档

• CLAUDE.md - 全面的框架文档
• docs/SECURITY.md - 安全指南和最佳实践
• docs/VULNERABILITY_MITIGATION.md - 漏洞跟踪
• docs/QUICKSTART.md - 快速开始指南
• docs/PUBLISHING.md - 发布指南
• docs/BUILD_AND_USE.md - 构建和使用说明
• docs/DOCKER_OPTIMIZATION.md - Docker 优化指南

模块文档

• src/libs/deps/README.md - 统一依赖导出
• src/libs/validator/README.md - 验证辅助工具
• src/libs/apisix/README.md - API 网关集成
• src/libs/gateway/README.md - 网关加载器
• src/libs/generator/README.md - ID 生成
• src/libs/koa/README.md - Koa 服务器设置
• src/libs/network/README.md - 网络工具
• src/libs/rabbitmq/README.md - 分布式事件
• src/libs/register/README.md - API 路由注册
• src/libs/type/README.md - 类型工具
• src/libs/universal/README.md - 通用 CRUD 模式

安全性

本项目高度重视安全性。我们使用：

• 使用 yarn security:check 定期进行安全审计
• 依赖漏洞跟踪和缓解
• 自定义验证器避免已知 CVE（例如，使用 @IsSafeUrl() 而非 @IsUrl()）
• 传递依赖的安全解析
• 安全文档和最佳实践

详细信息请查看 docs/SECURITY.md。

重要：始终使用 @IsSafeUrl() 而非 @IsUrl() 以避免 CVE-2025-56200。

贡献

欢迎贡献！请遵循以下指南：

1. Fork 仓库
2. 从 develope 创建功能分支
3. 使用描述性提交进行更改
4. 运行测试和代码检查：yarn test && yarn lint
5. 运行安全检查：yarn security:check
6. 创建到 develope 分支的拉取请求

开发指南

• 遵循现有代码约定
• 使用 TypeScript 严格模式
• 为公共 API 添加 JSDoc 注释
• 为新功能编写测试
• 根据需要更新文档

发布

这是一个私有 npm 包。要发布：

# 更新 package.json 中的版本
# 更新构建编号
yarn buildNum

# 运行发布前检查
yarn publish:check

# 构建用于发布
yarn build:publish

# 发布到 npm
yarn publish:npmjs

# 或发布到 GitHub packages
yarn publish:github

详细发布说明请查看 docs/PUBLISHING.md。

故障排除

数据库连接问题

• 验证 cfg/database.yml 连接字符串
• 检查 MariaDB/MySQL 是否正在运行
• 确保数据库用户具有适当的权限

Redis 连接问题

• 检查 Redis 是否正在运行：redis-cli ping
• 验证 cfg/redis.yml 设置
• 可以通过在启动时设置 disableRedis: true 来禁用 Redis

TypeORM 实体未找到

• 确保实体在启动时注册到 entities 数组中
• 检查实体文件是否有 @Entity() 装饰器
• 验证导入路径是否正确

许可证

UNLICENSED - 私有包

作者

FOT 团队

链接

• 仓库
• 问题跟踪
• npm 包

版本历史

• 1.3.6（当前）- 最新更新和改进
• 1.0.13 - 安全增强和依赖更新
• 1.0.0 - 初始版本

Last Updated | 最后更新: 2025-12-31 Framework Version | 框架版本: 1.3.6 Build Number | 构建编号: 251025471