MikroORM

Recipe này giúp người dùng bắt đầu với MikroORM trong Nest. MikroORM là ORM TypeScript cho Node.js dựa trên các pattern Data Mapper, Unit of Work và Identity Map. Đây là một lựa chọn thay thế tốt cho TypeORM, và việc migrate từ TypeORM sang khá dễ dàng. Tài liệu đầy đủ về MikroORM có thể tìm thấy tại đây.

Cài đặt

Cách dễ nhất để tích hợp MikroORM vào Nest là qua module @mikro-orm/nestjs. Chỉ cần cài nó cùng với Nest, MikroORM và driver tương ứng:

$ npm i @mikro-orm/core @mikro-orm/nestjs @mikro-orm/sqlite

MikroORM cũng hỗ trợ postgres, sqlite, và mongo. Xem tài liệu chính thức để biết đầy đủ các driver.

Sau khi cài đặt xong, chúng ta có thể import MikroOrmModule vào AppModule gốc.

import { MikroOrmModule } from '@mikro-orm/nestjs';
import { SqliteDriver } from '@mikro-orm/sqlite';

@Module({
  imports: [
    MikroOrmModule.forRoot({
      entities: ['./dist/entities'],
      entitiesTs: ['./src/entities'],
      dbName: 'my-db-name.sqlite3',
      driver: SqliteDriver,
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Method forRoot() nhận vào object cấu hình giống hệt với init() từ package MikroORM. Xem trang này để biết tài liệu cấu hình đầy đủ.

Ngoài ra, chúng ta có thể cấu hình CLI bằng cách tạo một file cấu hình mikro-orm.config.ts rồi gọi forRoot() mà không cần đối số nào.

import { MikroOrmModule } from '@mikro-orm/nestjs';

@Module({
  imports: [
    MikroOrmModule.forRoot(),
  ],
  ...
})
export class AppModule {}

Nhưng cách này sẽ không hoạt động khi bạn dùng các build tool có tree shaking, vì vậy tốt hơn nên cung cấp config một cách tường minh:

import { MikroOrmModule } from '@mikro-orm/nestjs';
import config from './mikro-orm.config.js'; // config ORM của bạn

@Module({
  imports: [
    MikroOrmModule.forRoot(config),
  ],
  ...
})
export class AppModule {}

Sau đó, EntityManager sẽ sẵn sàng để inject trên toàn bộ dự án (mà không cần import lại bất kỳ module nào ở nơi khác).

// Import mọi thứ từ package driver của bạn hoặc `@mikro-orm/knex`
import { EntityManager, MikroORM } from '@mikro-orm/sqlite';

@Injectable()
export class MyService {
  constructor(
    private readonly orm: MikroORM,
    private readonly em: EntityManager,
  ) {}
}

Repository

MikroORM hỗ trợ repository design pattern. Với mỗi entity, chúng ta có thể tạo một repository. Đọc tài liệu đầy đủ về repository tại đây. Để định nghĩa những repository nào nên được đăng ký trong scope hiện tại, bạn có thể dùng method forFeature(). Ví dụ, theo cách sau:

// photo.module.ts
import { MikroOrmModule } from '@mikro-orm/nestjs';

@Module({
  imports: [MikroOrmModule.forFeature([Photo])],
  providers: [PhotoService],
  controllers: [PhotoController],
})
export class PhotoModule {}

và import nó vào AppModule gốc:

// app.module.ts
import { MikroOrmModule } from '@mikro-orm/nestjs';

@Module({
  imports: [MikroOrmModule.forRoot(...), PhotoModule],
})
export class AppModule {}

Theo cách này, chúng ta có thể inject PhotoRepository vào PhotoService bằng decorator @InjectRepository():

import { EntityRepository } from '@mikro-orm/sqlite'; // import từ package driver của bạn

@Injectable()
export class PhotoService {
  constructor(
    @InjectRepository(Photo)
    private readonly photoRepository: EntityRepository<Photo>,
  ) {}
}

Dùng custom repository

Khi dùng custom repository, chúng ta không còn cần decorator @InjectRepository() nữa, vì Nest DI đã resolve dựa trên class reference.

// `**./author.entity.ts**`
import { Entity, EntityRepositoryType } from '@mikro-orm/core';

@Entity({ repository: () => AuthorRepository })
export class Author {
  // để cho phép inference trong `em.getRepository()`
  [EntityRepositoryType]?: AuthorRepository;
}

// `**./author.repository.ts**`
import { EntityRepository } from '@mikro-orm/sqlite'; // import từ package driver của bạn

export class AuthorRepository extends EntityRepository<Author> {
  // các method tùy chỉnh của bạn...
}

Vì tên của custom repository giống hệt với những gì getRepositoryToken() sẽ trả về, chúng ta không cần decorator @InjectRepository() nữa:

@Injectable()
export class MyService {
  constructor(private readonly repo: AuthorRepository) {}
}

Tự động load entity

Việc thêm entity thủ công vào mảng entities trong tùy chọn kết nối có thể khá tốn công. Thêm vào đó, việc tham chiếu entity từ module gốc phá vỡ ranh giới domain của ứng dụng và khiến chi tiết triển khai bị rò rỉ sang các phần khác của ứng dụng. Để giải quyết vấn đề này, ta có thể dùng static glob path.

Tuy nhiên, cần lưu ý rằng glob path không được webpack hỗ trợ, vì vậy nếu bạn build ứng dụng trong một monorepo, bạn sẽ không thể dùng chúng. Để giải quyết vấn đề này, có một giải pháp thay thế được cung cấp. Để tự động load entity, hãy đặt property autoLoadEntities trong object cấu hình (truyền vào method forRoot()) thành true, như bên dưới:

import { MikroOrmModule } from '@mikro-orm/nestjs';

@Module({
  imports: [
    MikroOrmModule.forRoot({
      ...
      autoLoadEntities: true,
    }),
  ],
})
export class AppModule {}

Với tùy chọn đó được chỉ định, mọi entity đăng ký qua method forFeature() sẽ tự động được thêm vào mảng entities của object cấu hình.

Serialization

May mắn là, MikroORM cung cấp một serialization API có thể dùng thay cho ClassSerializerInterceptor.

import { Entity, Property, ManyToOne } from '@mikro-orm/core';

@Entity()
export class Book {
  @Property({ hidden: true }) // Tương đương với `@Exclude` của class-transformer
  hiddenField = Date.now();

  @Property({ persist: false }) // Tương tự `@Expose()` của class-transformer. Chỉ tồn tại trong bộ nhớ, và sẽ được serialize.
  count?: number;

  @ManyToOne({
    serializer: (value) => value.name,
    serializedName: 'authorName',
  }) // Tương đương với `@Transform()` của class-transformer
  author: Author;
}

Hàm xử lý theo scope request trong queue

Như đã đề cập trong tài liệu, chúng ta cần một state “sạch” cho mỗi request. Điều này được xử lý tự động nhờ helper RequestContext được đăng ký qua middleware.

Nhưng middleware chỉ được thực thi cho các request handler HTTP thông thường, vậy nếu chúng ta cần một method có scope request ở ngoài phạm vi đó thì sao? Một ví dụ là handler của queue hoặc scheduled task.

Chúng ta có thể dùng decorator @CreateRequestContext(). Nó yêu cầu bạn trước tiên phải inject instance MikroORM vào context hiện tại, instance này sau đó sẽ được dùng để tạo context giúp bạn. Bên dưới, decorator sẽ đăng ký một request context mới cho method của bạn và thực thi nó bên trong context đó.

import { MikroORM, CreateRequestContext } from '@mikro-orm/core';

@Injectable()
export class MyService {
  constructor(private readonly orm: MikroORM) {}

  @CreateRequestContext()
  async doSomething() {
    // đoạn này sẽ được thực thi trong một context riêng biệt
  }
}

Testing

Package @mikro-orm/nestjs cung cấp hàm getRepositoryToken() trả về một token đã được chuẩn bị sẵn dựa trên entity cho trước, cho phép bạn mock repository.

import { MikroOrmModule, getRepositoryToken } from '@mikro-orm/nestjs';

@Module({
  providers: [
    PhotoService,
    {
      // hoặc khi bạn có custom repository: `provide: PhotoRepository`
      provide: getRepositoryToken(Photo),
      useValue: mockedRepository,
    },
  ],
})
export class PhotoModule {}

Ví dụ

Một ví dụ thực tế về NestJS kết hợp với MikroORM có thể tìm thấy tại đây