@gaias/basenode

![License]()

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.

$3

- 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

$3

#### 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

``bash


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:

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

2. Application Configuration

Edit cfg/application.yml:

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

3. Redis Configuration (Optional)

Edit cfg/redis.yml:

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

4. RabbitMQ Configuration (Optional)

Edit cfg/rabbitmq.yml:

`yaml
url: amqp://localhost:5672
`

5. Environment Variables (Optional)

Create a .env file or export variables:

`bash
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

`bash


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

$3

`
.
├── 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)
`

$3

#### Running

`bash


Development with hot reload

yarn dev

Development with API gateway

yarn devPro

Run compiled app

yarn ncc:run
`

#### Building

`bash


Build for publishing

yarn build:publish

Build single-file executable

yarn ncc:build
`

#### Database Code Generation

`bash


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

`bash


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

`bash


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

`bash


Check for outdated dependencies

yarn deps:check

Update dependencies

yarn deps:update
`

#### Other Tools

`bash


Generate RSA keys for JWT

yarn gen:keys

Update build number

yarn buildNum
`

$3

#### Creating a RESTful Controller

`typescript
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

`typescript
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 {
constructor(@di.Inject(() => UserRepo) private userRepo: UserRepo) {
super(userRepo);
}

async findByEmail(email: string): Promise {
return this.userRepo.findOne({ where: { email } });
}
}
`

#### Validation with VO (Value Object)

`typescript
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

`typescript
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> {
return this.userService.search(pagination);
}
}
`

#### Caching

`typescript
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

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

$3

#### 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

$3

- 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

$3

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.

$3

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

$3

This is a private npm package. To publish:

`bash


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.

$3

#### 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

$3

UNLICENSED - Private package

$3

FOT Team

$3

- Repository
- Issue Tracker
- npm Package

$3

- 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 网关集成。

$3

- 现代框架栈：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 文档
- 开发工具：热重载、代码检查、测试、代码生成

$3

#### 系统要求

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

#### 安装

`bash


克隆仓库

git clone https://github.com/gaias/basenode.git
cd basenode

安装依赖

yarn install
`

#### 配置

1. 数据库配置

编辑 cfg/database.yml：

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

2. 应用配置

编辑 cfg/application.yml：

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

3. Redis 配置（可选）

编辑 cfg/redis.yml：

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

4. RabbitMQ 配置（可选）

编辑 cfg/rabbitmq.yml：

`yaml
url: amqp://localhost:5672
`

5. 环境变量（可选）

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

`bash
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 # 网关允许的域名
`

#### 运行应用

`bash


开发模式（热重载）

yarn dev

开发模式（启用 API 网关）

yarn devPro

生产模式（构建后）

yarn ncc:run
`

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

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

$3

`
.
├── 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 密钥（生成的）
`

$3

#### 运行

`bash


开发模式（热重载）

yarn dev

开发模式（带 API 网关）

yarn devPro

运行编译后的应用

yarn ncc:run
`

#### 构建

`bash


构建用于发布

yarn build:publish

构建单文件可执行文件

yarn ncc:build
`

#### 数据库代码生成

`bash


从数据库架构生成实体

yarn gen:db-schema

生成仓储类

yarn gen:db-repo

生成实体和仓储

yarn gen:db

生成索引文件

yarn gen:idx
`

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

#### 测试与质量

`bash


运行测试

yarn test

监视模式运行测试

yarn test:watch

带覆盖率运行测试

yarn test:coverage

类型检查和代码检查

yarn lint

自动修复代码检查问题

yarn lint:fix
`

#### 安全

`bash


运行安全审计

yarn security

显示审计摘要

yarn security:summary

增强安全检查（推荐）

yarn security:check

生成安全报告

yarn security:json
`

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

#### 依赖管理

`bash


检查过时的依赖

yarn deps:check

更新依赖

yarn deps:update
`

#### 其他工具

`bash


为 JWT 生成 RSA 密钥

yarn gen:keys

更新构建编号

yarn buildNum
`

$3

#### 创建 RESTful 控制器

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

#### 创建带仓储的服务

`typescript
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 {
constructor(@di.Inject(() => UserRepo) private userRepo: UserRepo) {
super(userRepo);
}

async findByEmail(email: string): Promise {
return this.userRepo.findOne({ where: { email } });
}
}
`

#### 使用 VO 进行验证

`typescript
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;
}
`

#### 分页

`typescript
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> {
return this.userService.search(pagination);
}
}
`

#### 缓存

`typescript
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;
}
}
`

#### 分布式事件

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

$3

#### 核心框架

- 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 - 安全头

$3

- 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 模式

$3

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

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

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

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

$3

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

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

#### 开发指南

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

$3

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

`bash


更新 package.json 中的版本

更新构建编号

yarn buildNum

运行发布前检查

yarn publish:check

构建用于发布

yarn build:publish

发布到 npm

yarn publish:npmjs

或发布到 GitHub packages

yarn publish:github
`

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

$3

#### 数据库连接问题

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

#### Redis 连接问题

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

#### TypeORM 实体未找到

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

$3

UNLICENSED - 私有包

$3

FOT 团队

$3

- 仓库
- 问题跟踪
- npm 包

$3

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

---

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