# @edifice\.io/edifice-nestjs-core 中文文档

规范地址：https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/

版本：1\.0\.7
npm 元数据更新时间：2026-11-13T16:12:24.895Z
中文译文更新时间：2026-11-13T19:59:05.763Z
软件包许可：AGPL-3\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40edifice.io/edifice-nestjs-core
原文对照：https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/?lang=original
项目主页：https://github.com/edificeio/edifice-nestjs-core#readme
源码仓库：https://github.com/edificeio/edifice-nestjs-core

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

- 包体积（解压后）：1 MB，268 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：23 个
- peer 依赖：rxjs 7\.8\.2，fastify 5\.6\.0，@nestjs/core 11\.0\.20，@nestjs/common 11\.0\.20，@nestjs/config 4\.0\.0，@mikro-orm/core 6\.6\.10，@nestjs/swagger 11\.2\.0，@nestjs/terminus 11\.0\.0，reflect-metadata 0\.2\.0，@mikro-orm/nestjs 6\.1\.1，@mikro-orm/postgresql 6\.6\.10，@nestjs/microservices 11\.0\.20，@nestjs/platform-fastify 11\.0\.20，@edifice\.io/edifice-ent-client 6\.16\.11
- 首次发布：2025-12-01T15:44:05.269Z
- 最新版本发布：2026-11-13T16:12:24.670Z
- 近 30 天下载量：3097（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：117（近 12 个月 117 个）

## 中文简介

Edifice应用软件的核心NestJS模块和公用事业

## 安装

```sh
npm install @edifice.io/edifice-nestjs-core
```

也可以使用：`pnpm add @edifice.io/edifice-nestjs-core`、`yarn add @edifice.io/edifice-nestjs-core`、`bun add @edifice.io/edifice-nestjs-core`

## README

# 关于建筑-nestjs-core

-   许可证: 版权建筑
-   供资者:
-   开发者 :

# @edicle.io/edicle-nestjs-core (英语)

Edifice应用程序的核心NestJS模块和公用事业.

## \* 安装

```bash
pnpm add @edifice.io/edifice-nestjs-core
```

## \* 特性

这个软件包为使用 NestJS 构建 Edifice 后端应用程序提供了必不可少的构件:

### 模块

-   [**应用程序**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-appregistry-application-registration): 申请登记服务
-   [**配置**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-config-centralized-application-configuration): 集中配置管理
-   [**数据库**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-database-mikroorm-integration): MikroORM 与 PostgreSQL 支持的集成
-   [**活动**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-event-user-event-tracking): 数据事件发射器
-   [**卫生**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-health-readiness--liveness-checks)健康检查终点(准备状态、活性)
-   [**I18n 时**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-i18n-internationalization-service):多种语文支助的国际化服务
-   [**锁定器**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-logger-structured-logging): 与皮诺进行结构化记录(访问日志,请求日志)
-   [**海军**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-nats-messaging-client-integration): NATS 消息客户端集成
-   [**权限**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-permission-authorization-guards--decorators): 授权警卫和装饰员(ADMC,基于许可)
-   [**会议**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-session-user-session-management): 会话管理中间软件和装饰器
-   [**时间线**](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/#readme-timeline-notification-service): 时间线通知服务

#### 申请注册( 申请注册)

这个 `AppRegistryService` 自动通过 `CoreModule`。 。 。 .  
它在启动时向Edifice App注册处登记您的申请.

此进程扫描所有控制器 `@RequirePermission` 装饰者,收集所有已声明的工作流程权限,并连同应用程序元数据一起发送给登记册.

**如何运作:**

-   在应用靴子上, `AppRegistryService.registerApp()` 名为.
-   它通过反射从控制器中提取所有权限 .
-   它发出一个 `AppRegistrationRequestDTO` 通过NATS向登记处提交.
-   登记每10秒重审一次,直至成功.

**何时何地:**

-   登记在靴子夹阶段自动进行(见 `createApp()` 内 `bootstrap.utils.ts`) (中文(简体) ).
-   您不需要手动调用; 它是由核心模块所触发的( C)`CoreModule`) (中文(简体) ).

**为什么:**

-   这确保了您的应用及其权限可以被 Edifile 平台发现和管理.
-   它能够进行集中许可管理和工作流程整合.

**示例**

```typescript
import { CoreModule } from '@edifice.io/edifice-nestjs-core';

@Module({
  imports: [CoreModule], // AppRegistryService is included automatically
})
export class AppModule {}

@Controller()
export class ResourceController {
  @Get()
  @RequirePermission('ACCESS')
  async findAll() {
    // This permission will be registered automatically
  }
}
```

#### 配置( 集中应用程序配置)

这个 `ConfigModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它为您的 Edifile 后端提供集中配置管理, 使用 NestJS 的 `ConfigModule` 和辅助环境变量.

**特征 :**

-   从环境变量装入配置 .
-   通过 NestJS 的曝光配置 `ConfigService` 用于依赖性注射.
-   为日志,数据库,斯瓦格等模块提供帮助以读取其设置.

**如何运作:**

-   应用程序启动时,该配置会从环境变量中加载并在全球注入.
-   所有模块(数据库、记录器、NATS等)从 `ConfigService`。 。 。 .
-   您可以通过设置环境变量来覆盖配置 .

**何时何地:**

-   配置系统在应用程序启动时自动初始化 `CoreModule`。 。 。 .
-   不需要手动设置; 只需设置所需的环境变量 .

**配置 :**

-   使用环境变量设定您的主配置 .
-   见 [`src/config/EnvVars.md`](https://npmcn.com/package/%40edifice.io/edifice-nestjs-core/src/config/EnvVars.md) 用于完整列表支持的变量及其默认值.

**示例环境变量:**

```env
APP_NAME=my-edifice-app
APP_DISPLAY_NAME=My Edifice App
APP_PREFIX=/api
APP_ICON=https://example.com/icon.png

HOST=0.0.0.0
PORT=3002

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
DATABASE_USER=user
DATABASE_PASSWORD=pass
DATABASE_SCHEMA=public
DATABASE_DEBUG=true
DATABASE_SSL=false

NATS_URL=nats://localhost:4222
NATS_USER=natsuser
NATS_PASSWORD=natspass
NATS_DEBUG=false

LOG_LEVEL=info
LOG_KEEP_RAW_FIELDS=false

SWAGGER_SERVER_URL=https://api.example.com
HEAP_MEMORY=300
RSS_MEMORY=300
```

**示例**

```typescript
import { Module } from '@nestjs/common';
import { CoreModule } from '@edifice.io/edifice-nestjs-core';
import { ConfigService } from '@nestjs/config';

@Module({
  imports: [CoreModule], // ConfigModule is included automatically
})
export class AppModule {
  constructor(private readonly configService: ConfigService) {
    const appName = this.configService.get<string>('app.name');
    console.log(`App name: ${appName}`);
  }
}
```

**说明:**  
您不需要手动配置配置系统; 它在导入时可以使用 `CoreModule`。 。 。 .  
所有模块和服务都可以通过依赖性注射进入配置 `ConfigService`。 。 。 .

**额外配置 :**

您也可以提供这样的额外配置

```typescript
import { Module } from '@nestjs/common';
import { configuration as CoreConfig } from '@edifice.io/edifice-nestjs-core';
import AppConfig from './config/configuration'; // Your app's configuration object
import { CoreModule } from '@edifice.io/edifice-nestjs-core';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    CoreModule,
    // Use config defined in core + app config
    // (warn: does not override core config fields)
    ConfigModule.forRoot({
      isGlobal: true,
      load: [CoreConfig, AppConfig],
    }),
  ],
})
export class AppModule {}
```

#### 数据库(MikroORM集成)

这个 `DatabaseModule` 为您的 Edifice 后端应用程序提供与 MikroORM 和 PostgreSQL 的无缝集成.

**特征 :**

-   使用 NestJS 自动连接和配置数据库 `ConfigModule`。 。 。 .
-   启动时自动运行等待的迁移( 如果在配置中启用) .
-   提供帮助执行 SQL 脚本并管理 schema 演化.

**如何使用 :**

-   导入 `DatabaseModule` 在您的主要应用模块中( 已经包含在 `CoreModule`) (中文(简体) ).
-   通过环境变量配置您的数据库连接( E)`DATABASE_URL`, (中文(简体) ), `DATABASE_USER`(见a/c.5/49/70,附件).
-   将您的迁移脚本放入 `sql/` 目录,按照命名惯例:
    -   `NN-description.sql` 用于迁移脚本(例如, `01-init.sql`(中文(简体) )
    -   `NN-rollback.sql` 用于回滚脚本(例如, `01-rollback.sql`(中文(简体) )
-   在 `./src/migrations/`,各使用帮助器执行相应的 SQL 文件.

**示例**

-   在 `./src/migrations/`,各使用帮助器执行相应的 SQL 文件.

_SQL 迁移脚本(`sql/01-init.sql`:_

```sql
-- Create a demo table
CREATE TABLE demo_table (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);
```

_SQL 回滚脚本(`sql/01-rollback.sql`:_

```sql
-- Drop the demo table
DROP TABLE IF EXISTS demo_table;
```

_移民类别(`src/migrations/Migration01.ts`:_

```typescript
import { Migration } from '@mikro-orm/migrations';
import { executeScript } from '@edifice.io/edifice-nestjs-core';

export class Migration01 extends Migration {
  async up(): Promise<void> {
    await executeScript(this, '01-init.sql');
  }

  async down(): Promise<void> {
    await executeScript(this, '01-rollback.sql');
  }
}
```

_实体定义`src/entities/demo.entity.ts`:_

```typescript
import { Entity, PrimaryKey, Property } from '@mikro-orm/core';

@Entity()
export class Demo {
  @PrimaryKey()
  id!: number;

  @Property()
  name!: string;
}
```

_使用实体仓库的服务( U)`src/demo/demo.service.ts`:_

```typescript
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@mikro-orm/nestjs';
import { EntityRepository } from '@mikro-orm/postgresql';
import { Demo } from '../entities/demo.entity';

@Injectable()
export class DemoService {
  constructor(
    @InjectRepository(Demo)
    private readonly demoRepository: EntityRepository<Demo>,
  ) {}

  async createDemo(name: string): Promise<Demo> {
    const demo = this.demoRepository.create({ name });
    await this.demoRepository.persistAndFlush(demo);
    return demo;
  }

  async findAll(): Promise<Demo[]> {
    return this.demoRepository.findAll();
  }
}
```

_演示单元(`src/demo/demo.module.ts`:_

```typescript
import { Module } from '@nestjs/common';
import { CoreModule } from '@edifice.io/edifice-nestjs-core';
import { DemoService } from './demo.service';
import { Demo } from '../entities/demo.entity';
import { MikroOrmModule } from '@mikro-orm/nestjs';

@Module({
  imports: [CoreModule, MikroOrmModule.forFeature([Demo])],
  providers: [DemoService],
  exports: [DemoService],
})
export class DemoModule {}
```

**说明:**

-   数据库连接参数和迁移行为通过环境变量控制.
-   该模块确保您的数据库计划符合最新要求,并为高级迁移工作流程提供公用设施.

#### 事件(用户事件跟踪)

这个 `EventModule` 提供跟踪和记录用户事件(例如访问和创建)的服务.

**特征 :**

-   通过NATS将用户事件(ACCESS, CREATE)发布到Edifice事件系统.
-   从请求中自动提取用户/会话信息.
-   为移动网络视图请求跳过访问事件 .
-   集中事件记录用于分析与审计.

**如何使用 :**

-   导入 `CoreModule` 在您的主要应用模块中( 已包含) `EventModule`) (中文(简体) ).
-   弹出 `EventService` 输入您的控制器或服务.
-   打电话 `createAccessEvent(request, resourceType)` 或者说 `createCreateEvent(request, resourceType)` 记录事件.

**示例**

```typescript
import { Controller, Get, Post, Req, Injectable } from '@nestjs/common';
import { EventService, CoreModule } from '@edifice.io/edifice-nestjs-core';
import { FastifyRequest } from 'fastify';

@Module({
  imports: [CoreModule],
})
export class AppModule {}

@Controller()
export class ResourceController {
  constructor(private readonly eventService: EventService) {}

  @Get('/')
  async onResourceAccess(@Req() request: FastifyRequest) {
    await this.eventService.createAccessEvent(request);
  }

  @Post('/')
  async onResourceCreate(@Req() request: FastifyRequest) {
    await this.eventService.createCreateEvent(request, 'RESOURCE_TYPE');
  }
}
```

**配置 :**

-   该模块使用 `ConfigService` 以获取申请名称( e)`app.name`) (中文(简体) ).
-   事件通过NATS客户端发送(`EntNatsServiceClient`),由核心模块自动配置.

**说明:**

-   您不需要手动配置事件系统; 当导入时已准备好使用 `CoreModule`。 。 。 .
-   事件有助于分析、审计和工作流程触发.

#### 健康(准备状态和生活检查)

这个 `HealthModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它为准备和活性检查提供终点和服务,与NestJS Terminus整合.

**特征 :**

-   显示 a `/health` 准备和现场检查的终点.
-   检查数据库连接(MikroORM),内存使用,以及NATS连接.
-   通过配置使用内存的自定义阈值 .
-   与监测和管弦系统相结合(Kubernetes, Docker等).

**如何运作:**

-   这个 `HealthController` 数据库、内存和NATS的汇总检查.
-   健康指标自动注入和运行.
-   这个 `/health` 端点是公开的,可用于探测.

**何时何地:**

-   卫生系统在应用程序启动时自动初始化 `CoreModule`。 。 。 .
-   不需要手动配置;所有依赖都由核心模块接通.

**配置 :**

-   使用环境变量设定内存阈值和其他健康参数:
    
    ```env
    HEAP_MEMORY=300
    RSS_MEMORY=300
    ```
    
-   您可以调整这些值以适应您的部署要求 .

**示例**

```typescript
import { Module } from '@nestjs/common';
import { CoreModule } from '@edifice.io/edifice-nestjs-core';

@Module({
  imports: [CoreModule], // HealthModule is included automatically
})
export class AppModule {}
```

**说明:**  
您不需要手动配置健康端点; 当导入时, 健康端点已准备好使用 `CoreModule`。 。 。 .  
健康检查对云母部署和自动监测至关重要.

#### I18n(国际化服务)

这个 `I18nModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它提供注册和获取翻译服务,为您的 Edifile 后端提供多种语言支持.

**特征 :**

-   启动时为您的应用程序注册翻译文件.
-   根据请求头动态获取翻译( 语言检测) .
-   与Edifice ENT客户端整合,进行集中翻译管理.
-   支持每个语言的自定义翻译文件(例如, `assets/i18n/fr.json`) (中文(简体) ).
-   用于其他模块,如通知提供本地化内容.

**如何运作:**

-   这个 `I18nService` 由核心模块初始化并注入.
-   应用程序启动时, 翻译文件在 `assets/i18n/` 自动注册.
-   您可以使用所提供的服务方法获取当前请求或应用程序的翻译.
-   通知制度`TimelineService` 和自定义通知服务) `I18nService` 将通知内容本地化.

**何时何地:**

-   I18n系统在应用程序启动时自动初始化 `CoreModule`。 。 。 .
-   不需要手动配置;所有依赖都由核心模块接通.

**配置 :**

-   申请名称( E)`APP_NAME`)必须使用环境变量设定.
-   将您的翻译文件放入 `assets/i18n/` 目录(例如, `fr.json`, (中文(简体) ), `en.json`) (中文(简体) ).

**示例**

```typescript
import { Module, Controller, Get, Req } from '@nestjs/common';
import { CoreModule, I18nService } from '@edifice.io/edifice-nestjs-core';
import { FastifyRequest } from 'fastify';

@Module({
  imports: [CoreModule], // I18nModule is included automatically
})
export class AppModule {}

@Injectable()
export class MyService {
  constructor(private readonly i18nService: I18nService) {}

  async getTranslations(@Req() request: FastifyRequest) {
    return await this.i18nService.fetchCurrentAppTranslationsForRequest(
      request,
    );
  }
}
```

> **说明:**  
> 默认, `FrontendController` 暴露一个 `/i18n` 为您的应用程序提供翻译服务的路径.  
> 没错 **没有** 需要为i18n创建自定义控制器或路由;它已经由核心模块处理.

#### Logger (已断接的日志)

这个 `LoggerModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它使用 Pino 提供结构化的日志,包括访问日志和为您的 Edifice 后端请求日志.

**特征 :**

-   对所有请求和应用程序活动进行结构化的JSON记录.
-   请求范围记录器( E)`RequestLogger`用于背景日志(用户、路径、方法).
-   访问登录器( O)`AccessLogger`用于记录认证和访问活动.
-   与 NestJS 整合,并支持日志级别,儿童日志和自定义字段.

**如何运作:**

-   日志由核心模块初始化并注入.
-   可以注射吗 `RequestLogger` 或者说 `AccessLogger` 输入控制器、服务或中间软件.
-   日志自动被请求/会话/用户信息所丰富.

**何时何地:**

-   在应用程序启动时自动初始化日志 `CoreModule`。 。 。 .
-   不需要手动配置;所有依赖都由核心模块接通.

**配置 :**

-   使用环境变量设置日志级别和选项 :
    
    ```env
    LOG_LEVEL=info
    LOG_KEEP_RAW_FIELDS=false
    ```
    
-   您可以调整这些值以适应您的部署要求 .

**示例**

```typescript
import { Module, Controller, Get, Req } from '@nestjs/common';
import { Logger } from 'nestjs-pino';
import { CoreModule } from '@edifice.io/edifice-nestjs-core';
import { FastifyRequest } from 'fastify';

@Module({
  imports: [CoreModule], // LoggerModule is included automatically
})
export class AppModule {}

@Controller()
export class MyController {
  constructor(private readonly logger: Logger) {}

  @Get('hello')
  async hello(@Req() request: FastifyRequest) {
    this.logger.info({ path: request.url }, 'Hello endpoint accessed');
    return { message: 'Hello world' };
  }
}
```

**说明:**  
您不需要手动配置日志; 它已准备好在导入时使用 `CoreModule`。 。 。 .  
所有日志都是结构化的,可以被日志汇总系统所消耗.

#### NATS( 中止客户端集成)

这个 `NatsModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它提供集中的NATS客户端,用于Edifice微服务之间的通讯,服务电话和酒吧/子通信.

**特征 :**

-   集中了NATS配置和连接管理.
-   导出配置的NATS `ClientProxy` 用于通讯和服务通信.
-   使用 NestJS 装饰器支持 pub/sub 和请求/响应模式(`EventPattern`, (中文(简体) ), `MessagePattern`) (中文(简体) ).
-   包括一个安全解冻器来优雅地处理非JSON消息.
-   允许您即时处理外部服务客户端( 如 `EntNatsServiceClient` 从 [`@edifice.io/edifice-ent-client`](https://github.com/edificeio/entcore)使用NATS连接进行服务间通话.
-   提供 `EntNatsServiceClient` 请求/答复.

**如何运作:**

-   NATS客户端由核心模块初始化并注入.
-   可以注射吗 `EntNatsServiceClient` 呼叫外部服务.
-   您可以使用抽象用户类(由 CLI 生成) 来处理即将到来的事件和请求 .

**何时何地:**

-   NATS系统在应用程序启动时自动初始化 `CoreModule`。 。 。 .
-   不需要手动配置;所有依赖都由核心模块接通.

**配置 :**

-   NATS连接参数使用环境变量设定:
    
    ```env
    NATS_URL=nats://localhost:4222
    NATS_USER=natsuser
    NATS_PASSWORD=natspass
    NATS_DEBUG=false
    ```
    
-   您可以调整这些值以适应您的部署要求 .

**调用外部服务:**

> 此示例显示如何使用 `EntNatsServiceClient`。 。 。 .  
> 包裹 [`@edifice.io/edifice-ent-client`](https://github.com/edificeio/entcore) 从 [内核](https://github.com/edificeio/entcore) 通过CLI.  
> 它是外部依赖,使用由核心模块提供的NATS连接.

```typescript
import { Injectable } from '@nestjs/common';
import { EntNatsServiceClient } from '@edifice.io/edifice-ent-client';

@Injectable()
export class CommunicationService {
  constructor(private readonly entServiceClient: EntNatsServiceClient) {}

  async addLinkBetweenGroups(
    sourceGroupId: string,
    targetGroupId: string,
  ): Promise<boolean> {
    const request = { startGroupId: sourceGroupId, endGroupId: targetGroupId };
    const response = await this.entServiceClient.addLinkBetweenGroups(request);
    return response.created ?? false;
  }
}
```

**处理酒吧/分公司和服务请求:**

> 这个例子说明了如何使用NestJS的装饰和由CLI产生的抽象类来订阅事件或响应服务请求.

```typescript
import {
  EventPattern,
  MessagePattern,
  Payload,
  Ctx,
  NatsContext,
} from '@nestjs/microservices';

// These abstract subscriber classes are generated by the CLI.
// You should extend them to implement your own event/message handling logic.

// Example: Subscribe to events
export abstract class BrokerSubscriber {
  @EventPattern('directory.groups.deleted')
  onGroupsDeleted(
    @Payload() data: GroupsDeletedDTO,
    @Ctx() context: NatsContext,
  ) {
    this.handleGroupsDeletedEvent(data, context.getSubject());
  }
  abstract handleGroupsDeletedEvent(
    data: GroupsDeletedDTO,
    subject: string,
  ): void;
}

// Example: Respond to service requests
export abstract class AudienceSubscriber {
  @MessagePattern('audience.check.right.communities.*')
  onCheckResourceAccess(
    @Payload() request: CheckResourceAccessRequestDTO,
    @Ctx() ctx: NatsContext,
  ): Promise<CheckResourceAccessResponseDTO> {
    return this.handleCheckAnnouncementAccess(request, ctx.getSubject());
  }
  abstract handleCheckAnnouncementAccess(
    request: CheckResourceAccessRequestDTO,
    subject: string,
  ): Promise<CheckResourceAccessResponseDTO>;
}

// Example: Concrete implementation
@Controller()
export class MyBrokerSubscriber extends BrokerSubscriber {
  handleGroupsDeletedEvent(data: GroupsDeletedDTO, subject: string): void {
    // Your custom logic here
    console.log(
      `Groups deleted: ${JSON.stringify(data)} from subject: ${subject}`,
    );
  }
}

@Controller()
export class MyAudienceSubscriber extends AudienceSubscriber {
  async handleCheckAnnouncementAccess(
    request: CheckResourceAccessRequestDTO,
    subject: string,
  ): Promise<CheckResourceAccessResponseDTO> {
    // Your custom logic here
    return { accessGranted: true };
  }
}
```

**说明:**

-   您不需要手动配置 NATS; 已准备在导入时使用 `CoreModule`。 。 。 .
-   使用 `EntNatsServiceClient` 用于外部服务呼叫, 以及用于 pub/sub 和 请求/响应模式的抽象用户类.
-   CLI 可以生成抽象用户类来帮助您执行事件和信件处理器.

#### 许可( 授权守护和装饰)

这个 `PermissionModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它为基于工作流程和管理员的授权提供装饰和守卫,为您的端点提供精细的准入控制.

**特征 :**

-   `@RequirePermission('PERMISSION_NAME')`:根据用户工作流程权限限制对端点的访问. 强制装饰.
-   `@RequireAdmc()`: 限制超级管理员访问端点(ADMC).
-   `@Public()`:标记端点为公用(不需要认证).
-   `@BasicAuth()`: 为终点添加基本授权方法. 授权用户和密码设置在配置中.

**如何运作:**

-   装饰者在您的控制器和端点上设置元数据 .
-   守护者读取此元数据并检查用户的会话和权限.
-   权限在AppRegistry服务启动时自动注册.

**何时何地:**

-   许可系统在应用程序启动时自动初始化 `CoreModule`。 。 。 .
-   不需要手动配置;所有依赖都由核心模块接通.

**配置 :**

-   用户权限和角色在会话对象中提供(`entSession`) (中文(简体) ).
-   工作流程权限在您的商业逻辑中定义,并通过装饰者注册.

**示例**

```typescript
import { Controller, Get, Post } from '@nestjs/common';
import {
  RequirePermission,
  RequireAdmc,
  Public,
  CoreModule,
} from '@edifice.io/edifice-nestjs-core';

@Module({
  imports: [CoreModule], // PermissionModule is included automatically
})
export class AppModule {}

@Controller('resources')
export class ResourceController {
  @Get()
  @RequirePermission('COMMUNITY_ACCESS')
  async findAll() {
    // Only users with COMMUNITY_ACCESS permission can access this endpoint
  }

  @Post('/admin')
  @RequireAdmc() // Only super administrators can access this endpoint
  async adminTask() {
    // Admin logic here
  }

  @Get('public-info')
  @Public()
  async publicInfo() {
    // This endpoint is accessible without authentication
  }
}
```

**说明:**  
您不需要手动配置权限守护符; 当您导入时, 它们已准备好使用 `CoreModule`。 。 。 .  
所有权限自动注册并强制执行您的端点 .

#### 会话( 用户会话管理)

这个 `SessionModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它为您 Edifice 后端管理用户会话提供中间软件、装饰和帮助.

**特征 :**

-   用于验证每个请求并附加用户会话的中端软件 .
-   会话装饰器( E)`@Session()`)直接将会话注入控制器方法.
-   展出关于原始快速化请求对象的会话信息( E)`request.raw.entSession`) (中文(简体) ).
-   通过NATS与ENT服务相融合,用于会话验证和刷新.

**如何运作:**

-   会话中间软件运行在每一个API请求上,通过ENT服务验证会话,并附在请求上.
-   您可以使用任意一个 `@Session()` 装饰或直接取自请求对象.

**何时何地:**

-   会话系统在应用程序启动时自动初始化 `CoreModule`。 。 。 .
-   不需要手动配置;所有依赖都由核心模块接通.

**配置 :**

-   会话验证使用由核心模块提供的NATS连接.

**示例**

```typescript
import { Controller, Get, Req } from '@nestjs/common';
import { CoreModule, Session } from '@edifice.io/edifice-nestjs-core';
import { FastifyRequest } from 'fastify';
import { ENTUserSession } from '@edifice.io/edifice-ent-client';

@Module({
  imports: [CoreModule], // SessionModule is included automatically
})
export class AppModule {}

@Controller('profile')
export class ProfileController {
  @Get()
  async getProfile(@Session() session: ENTUserSession) {
    // Access session directly via decorator
    return { userId: session.userId, name: session.displayName };
  }

  @Get('raw')
  async getProfileRaw(@Req() request: FastifyRequest) {
    // Access session via Fastify request object
    const session = request.raw.entSession;
    return { userId: session.userId, name: session.displayName };
  }
}
```

**说明:**  
您不需要手动配置会话管理; 它已经准备好在导入时使用 `CoreModule`。 。 。 .  
会话信息在所有控制器中都有,可以通过装饰器或请求对象访问.

#### 时间表(通知处)

这个 `TimelineModule` 在导入时自动包含 `CoreModule` 在您的申请.  
它为登记通知模板和通过Edifice时间表系统向用户发送通知提供服务.

**特征 :**

-   注册您的应用程序的通知模板 .
-   向用户发送通知(带有推取,邮件和预览选项).
-   与ENT客户端和NATS结合交付.
-   通过I18n服务支持本地化.

**如何运作:**

-   这个 `TimelineService` 由核心模块初始化并注入.
-   您可以在启动时或需要时注册通知模板.
-   您可以通过调用服务方法向用户发送通知.

**何时何地:**

-   程序启动时自动初始化时间段系统 `CoreModule`。 。 。 .
-   不需要手动配置;所有依赖都由核心模块接通.

**配置 :**

-   申请名称( E)`APP_NAME`)必须使用环境变量设定.
-   通知模板可以在模块初始化或动态化时注册.

**登记通知模板 :**

注册通知模板时,您提供 `RegisterNotificationRequestDTO` 对象.  
此对象描述您在 Edifice 时间表系统中的通知将如何出现和行为 .

**主要领域 `RegisterNotificationRequestDTO`数字 :**

-   `notificationName` (字符串):  
    通知事件的独特标识符(例如, `"MY_EVENT"`) (中文(简体) ).
    
-   `title` (字符串):  
    在时间线中向用户显示标题 .
    
-   `body` (字符串):  
    通知的主要内容或消息(可以包括HTML).
    
-   `appAddress` (弦,可选):  
    访问与通知相关的应用程序或资源的URL路径.
    
-   `defaultFrequency` (单位:千美元)`IMMEDIATE` | `DAILY` | `WEEKLY` | `NEVER`,可选:  
    通知的默认发送频率 .
    
-   `restriction` (单位:千美元)`NONE` | `INTERNAL` | `EXTERNAL` | `HIDDEN`,可选:  
    对能见度的限制级别(如只限内部用户).
    
-   `pushNotif` (对象,可选):  
    按下通知选项, 如移动/网络推的标题和正文 .
    
-   `preview` (对象,可选):  
    通知的预览配置 .
    
-   `params` (对象,可选):  
    动态内容或链接的自定义参数.
    

**示例**

```typescript
const template: RegisterNotificationRequestDTO = {
  notificationName: 'MY_EVENT',
  title: 'My Event',
  body: '<b>A new event occurred!</b>',
  appAddress: '/events/123',
  defaultFrequency: 'IMMEDIATE',
  restriction: 'NONE',
  pushNotif: {
    title: 'Event!',
    body: 'You have a new event.',
  },
  preview: {
    imageUrl: '/assets/event.png',
    description: 'Preview of the event notification',
  },
  params: {
    resourceId: '123',
    customParam: 'value',
  },
};
```

```typescript
import { Injectable, OnModuleInit } from '@nestjs/common';
import { TimelineService } from '@edifice.io/edifice-nestjs-core';
import { RegisterNotificationRequestDTO } from '@edifice.io/edifice-ent-client';

@Injectable()
export class MyNotificationService implements OnModuleInit {
  constructor(private readonly timelineService: TimelineService) {}

  async onModuleInit() {
    const templates: RegisterNotificationRequestDTO[] = [
      {
        notificationName: 'MY_EVENT',
        title: 'My Event',
        body: 'A new event occurred!',
        // ...other template fields
      },
    ];
    await this.timelineService.registerNotifications(templates);
  }
}
```

**发送通知:**

```typescript
import { TimelineService } from '@edifice.io/edifice-nestjs-core';
import {
  SessionDto,
  SendNotificationRequestDTO,
} from '@edifice.io/edifice-ent-client';

@Injectable()
export class MyService {
  constructor(private readonly timelineService: TimelineService) {}

  async sendNotification(session: SessionDto) {
    const notification: SendNotificationRequestDTO = {
      notificationName: 'MY_EVENT',
      recipientIds: ['userId1', 'userId2'],
      resourceUri: '/resource/123',
      params: { customParam: 'value' },
      pushNotif: {
        title: 'Event!',
        body: 'You have a new event.',
      },
    };

    await this.timelineService.sendNotification(session, notification);
  }
}
```

**说明:**

-   您不需要手动配置时间段系统; 它在导入时可以使用 `CoreModule`。 。 。 .
-   通知使用I18n服务本地化,并通过NATS和ENT客户端发送.

#### Swagger( OpenAPI 文档)

导入时自动启用 Swagger 模块 `CoreModule` 在应用程序中(除非您通过环境变量禁用).  
它为您的 API 提供了交互式 OpenAPI 文档, 可用于 `/openapi`。 。 。 .

**特征 :**

-   从控制器和 DTO 自动生成 OpenAPI 文档.
-   服务 Swagger UI 在 `/openapi` 默认.
-   通过环境变量支持自定义标题,描述,版本和服务器URL.

**如何运作:**

-   在应用程序启动时, Swagger 配置并自动启动, 如果 `ENABLE_SWAGGER=true` (默认).
-   配置从环境变量读取,并通过 `ConfigService`。 。 。 .

**配置 :** 设置以下环境变量来自定义 Swagger :

```env
ENABLE_SWAGGER=true
SWAGGER_SERVER_URL=https://api.example.com
SWAGGER_TITLE=My Edifice API
SWAGGER_DESCRIPTION=API documentation for my Edifice backend
VERSION=1.0.0
```

**说明:**  
您不需要手动配置 Swagger; 已准备好在导入时使用 `CoreModule`。 。 。 .  
访问您的 API 文档 `/openapi`。 。 。 .

### 公用事业

-   **诱饵**: 应用程序拖曳工具
-   **实体命名**: 数据库实体命名公约
-   **静态资产**: 为公用事业服务的静态文件

## 使用量

### 基本设置

```typescript
import { Module } from '@nestjs/common';
import { CoreModule } from '@edifice.io/edifice-nestjs-core';

@Module({
  imports: [CoreModule],
})
export class AppModule {}
```

### CLI 工具

这个软件包提供了几个CLI工具来帮助您实现常见后端任务的自动化.  
安装时每个工具都可以作为二进制 `@edifice.io/edifice-nestjs-core`。 。 。 .

-   **建筑-遗传-实体**: 从数据库中生成 MikroORM 实体
-   **建筑-遗传-元数据**: 生成应用程序元数据文件
-   **建筑- k6- 同步- dto**: 为 K6 测试同步 DTO
-   **生成- swagger- pdf**: 从您的 NestJS API Swagger 文档中生成 PDF

* * *

#### 生成实体

**目的:**  
从您的 PostgreSQL 数据库中生成 MikroORM 实体文件 .

**用法 :**

```bash
pnpm edifice-generate-entities --schema <schema-name> [options]
```

**参数 :**

-   `--schema` (需要):用于实体生成的数据库计划名称.
-   `--path`: 生成实体的目标目录(默认: `./src/entities`) (中文(简体) ).
-   `--temp-dir`: 初始生成的临时目录(默认值 : `./src/temp/entities`) (中文(简体) ).
-   `--mapping-config`: 实体模块映射文件的路径( 默认 : `./src/config/entity-mapping.config.json`) (中文(简体) ).
-   `--keep-temp`: 生成后保留临时目录( E)`true` 或者说 `false`,默认值 : `false`) (中文(简体) ).

**实例:**

```bash
pnpm edifice-generate-entities --schema community
pnpm edifice-generate-entities --schema community --temp-dir ./src/temp --path ./src/entities
pnpm edifice-generate-entities --schema community --mapping-config ./src/config/entity-mapping.config.json
pnpm edifice-generate-entities --schema community --keep-temp true
```

* * *

#### 生成元数据

**目的:**  
生成包含构建日期、 git 承诺散列和分支名称的构建元数据文件 .

**用法 :**

```bash
pnpm edifice-generate-metadata <target-file-path>
```

**参数 :**

-   `<target-file-path>` (需要):将写入元数据的文件路径.

**示例**

```bash
pnpm edifice-generate-metadata ./dist/metadata.txt
```

* * *

#### 同步 K6 DTO

**目的:**  
将DTO TypeScript定义同步到K6相容类型,用于API测试.

**用法 :**

```bash
pnpm edifice-k6-sync-dto
```

**参数 :**  
此脚本对 DTO 和输出路径使用配置常数.  
如果支持的话, 您可以调整脚本中的路径或通过环境变量 .

**示例**

```bash
pnpm edifice-k6-sync-dto
```

**细节 :**

-   解析来自 `client/rest/src/dtos`。 。 。 .
-   生成 K6 兼容类型 `types/generated`。 。 。 .
-   不包括命名的文件 `index.ts` 默认.

* * *

#### 生成- swagger- pdf

**目的:**  
从您的 NestJS 服务器所曝光的 Swagger (OpenAPI) 文档中生成一个 PDF .

**用法 :**

```bash
npx generate-swagger-pdf --host <host> --port <port>
```

**选项 :**

-   `--host`, (中文(简体) ), `-h`: Swagger 服务器主机( 默认 : `127.0.0.1`(中文(简体) )
-   `--port`, (中文(简体) ), `-p`: Swagger 服务器端口(默认值 : `3002`(中文(简体) )

PDF 将在 `documentation/api-docs.pdf` 您的工程文件夹 .

**示例**

```bash
npx generate-swagger-pdf --host 127.0.0.1 --port 4000
```

这个软件包提供了几个CLI工具来帮助您实现常见后端任务的自动化.  
安装时每个工具都可以作为二进制 `@edifice.io/edifice-nestjs-core`。 。 。 .

-   **建筑-遗传-实体**: 从数据库中生成 MikroORM 实体
-   **建筑-遗传-元数据**: 生成应用程序元数据文件
-   **建筑- k6- 同步- dto**: 为 K6 测试同步 DTO
-   **生成- swagger- pdf**: 从您的 NestJS API Swagger 文档中生成 PDF

* * *

**说明:**  
所有CLI工具安装后都可以使用.  
你可以和他们一起运行 `pnpm` 或者说 `npx` 从您的项目根.

## QQ 配置

核心模块使用 NestJS `ConfigModule` 用于配置。 您可以通过环境变量或配置文件提供配置.

### 环境变量

-   `DATABASE_URL`: PostgreSQL 连接字符串
-   `NATS_URL`: NATS 服务器 URL
-   `LOG_LEVEL`: 日志级别(调试、信息、警告、错误)
-   `NODE_ENV`环境(发展、生产)

## 发展

```bash
# Install dependencies
pnpm install

# Build
pnpm build

# Format code
pnpm format

# Lint code
pnpm lint
```

## 有关软件包

-   [@edicle.io/edicle-ent-客户端](https://github.com/edificeio/entcore) - Edifice ENT客户端图书馆

## 问题

报告问题 [GitHub 问题](https://github.com/edificeio/edifice-nestjs-core/issues)。 。 。 .

## 常见问题

### @edifice\.io/edifice-nestjs-core 是什么？

Edifice应用软件的核心NestJS模块和公用事业

### 如何安装 @edifice\.io/edifice-nestjs-core？

在项目目录运行 npm install @edifice\.io/edifice-nestjs-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（7\.8\.2）、fastify（5\.6\.0）、@nestjs/core（11\.0\.20）、@nestjs/common（11\.0\.20）、@nestjs/config（4\.0\.0）、@mikro-orm/core（6\.6\.10）、@nestjs/swagger（11\.2\.0）、@nestjs/terminus（11\.0\.0）、reflect-metadata（0\.2\.0）、@mikro-orm/nestjs（6\.1\.1）、@mikro-orm/postgresql（6\.6\.10）、@nestjs/microservices（11\.0\.20）、@nestjs/platform-fastify（11\.0\.20）、@edifice\.io/edifice-ent-client（6\.16\.11）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 edifice-k6-sync-dto、edifice-update-version、edifice-generate-entities、edifice-generate-metadata、edifice-update-rn-version、edifice-generate-rest-client、edifice-generate-swagger-pdf，可以用 npx edifice-k6-sync-dto 直接运行。

### @edifice\.io/edifice-nestjs-core 支持 TypeScript 吗？

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

### @edifice\.io/edifice-nestjs-core 支持 ESM 还是 CommonJS？

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

### @edifice\.io/edifice-nestjs-core 需要什么版本的 Node\.js？

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

### @edifice\.io/edifice-nestjs-core 可以商用吗？

@edifice\.io/edifice-nestjs-core 使用 AGPL-3\.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @edifice\.io/edifice-nestjs-core 的下载量有多少？

根据 npm 官方下载统计，@edifice\.io/edifice-nestjs-core 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,097 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @edifice\.io/edifice-nestjs-core 还在维护吗？

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