はじめに
Node.jsのバックエンドフレームワークとして人気の高いNest.js。Angularにインスパイアされた設計で、TypeScriptファーストな開発体験を提供しています。
しかし、初めてNest.jsに触れる方にとって「モジュール」「コントローラー」「サービス」といった概念の関係性は少し複雑に感じるかもしれません。
この記事では、Nest.jsの核となるアーキテクチャを図解を交えながら、わかりやすく解説していきます。
Nest.jsアーキテクチャの全体像
Nest.jsは以下のような階層構造でアプリケーションを構成します：
ルートモジュール (AppModule)
↓
機能モジュール (UserModule, ProductModule...)
↓
コントローラー/リゾルバー (HTTP/GraphQL)
↓
サービス (ビジネスロジック)
各レイヤーには明確な責務があり、この分離により保守性の高いアプリケーションを構築できます。
1. ルートモジュール - アプリケーションの司令塔
ルートモジュール（AppModule） は、アプリケーション全体の「本社」のような存在です。
身近な例で理解する
会社組織で例えると：
- ルートモジュール = 本社（全体を統括）
- 機能モジュール = 各部署（営業部、開発部、経理部など）
// 本社（ルートモジュール）が各部署を管理
@Module({
imports: [
UserModule, // ユーザー管理部署
ProductModule, // 商品管理部署
OrderModule, // 注文管理部署
AuthModule // 認証管理部署
],
controllers: [AppController], // 本社直属の窓口
providers: [AppService], // 本社直属のサービス
})
export class AppModule {}
ルートモジュールの役割
- 統括管理: 全ての機能モジュールを束ねる
- アプリ起動: Nest.jsがアプリを起動する際の出発点
- グローバル設定: データベース接続、環境設定など全体に関わる設定
2. 機能モジュール - 専門部署のような存在
機能モジュール は、特定の業務を担当する「部署」のようなものです。
具体的な例：ECサイトの場合
// ユーザー管理部署（UserModule）
@Module({
imports: [
TypeOrmModule.forFeature([User]), // ユーザーデータベース
JwtModule.register({...}) // JWT認証
],
controllers: [UserController], // ユーザー関連のAPI窓口
providers: [UserService], // ユーザー業務処理
exports: [UserService], // 他部署でも利用可能にする
})
export class UserModule {}
// 商品管理部署（ProductModule）
@Module({
imports: [
TypeOrmModule.forFeature([Product]),
CloudinaryModule // 画像アップロード
],
controllers: [ProductController], // 商品関連のAPI窓口
providers: [ProductService], // 商品業務処理
exports: [ProductService],
})
export class ProductModule {}
// 注文管理部署（OrderModule）
@Module({
imports: [
TypeOrmModule.forFeature([Order]),
UserModule, // ユーザー部署と連携
ProductModule, // 商品部署と連携
PaymentModule // 決済部署と連携
],
controllers: [OrderController],
providers: [OrderService],
})
export class OrderModule {}
機能モジュールの特徴
1. 専門性
各モジュールは特定の業務領域に特化
- UserModule → ユーザー登録、ログイン、プロフィール管理
- ProductModule → 商品登録、在庫管理、カテゴリ管理
- OrderModule → 注文処理、注文履歴、配送管理
2. 独立性
各モジュールは独立して動作可能
// 商品モジュールだけでも完結した機能を提供
@Get('products')
getProducts() {
return this.productService.findAll(); // 他のモジュールに依存しない
}
3. 連携性
必要に応じて他のモジュールと連携
// 注文作成時は複数のモジュールと連携
async createOrder(userId: number, productId: number) {
const user = await this.userService.findById(userId); // ユーザーモジュール
const product = await this.productService.findById(productId); // 商品モジュール
// 注文処理...
}
実際のフォルダ構成
src/
├── app.module.ts # ルートモジュール（本社）
├── main.ts # アプリケーション起動
└── modules/
├── user/ # ユーザー管理部署
│ ├── user.module.ts
│ ├── user.controller.ts
│ ├── user.service.ts
│ └── entities/user.entity.ts
├── product/ # 商品管理部署
│ ├── product.module.ts
│ ├── product.controller.ts
│ ├── product.service.ts
│ └── entities/product.entity.ts
└── order/ # 注文管理部署
├── order.module.ts
├── order.controller.ts
├── order.service.ts
└── entities/order.entity.ts
モジュールの設定項目を理解する
モジュールの@Module()デコレータには、以下の重要なプロパティがあります：
@Module({
imports: [...], // 他のモジュールを取り込む
controllers: [...], // このモジュールのAPI窓口
providers: [...], // このモジュールのサービス類
exports: [...] // 他のモジュールに提供する機能
})
export class UserModule {}
imports - 他のモジュールを取り込む
imports: [
TypeOrmModule.forFeature([User]), // データベース機能
JwtModule.register({...}), // JWT認証機能
EmailModule, // メール送信機能
ProductModule // 商品管理機能
]
- 役割: 他のモジュールの機能を使用できるようにする
- 例: ユーザーモジュールで商品情報が必要な場合、ProductModuleをimport
controllers - API窓口の定義
controllers: [
UserController, // /users のAPI処理
AuthController // /auth のAPI処理
]
- 役割: HTTPリクエストを受け取るエンドポイントを定義
-
例:
GET /users,POST /users/loginなどのAPIを処理
providers - サービス類の登録
providers: [
UserService, // ユーザー業務処理
UserRepository, // データベース操作
EmailService, // メール送信処理
{
provide: 'CONFIG',
useValue: { apiKey: 'xxx' } // 設定値の注入
}
]
- 役割: このモジュール内で使用するサービスやクラスを登録
- 例: ビジネスロジックを実装したサービスクラス
exports - 他のモジュールに機能を提供
exports: [
UserService, // 他のモジュールからも利用可能
UserRepository // 他のモジュールからも利用可能
]
- 役割: このモジュールの機能を他のモジュールでも使えるようにする
- 例: OrderModuleでUserServiceを使いたい場合、UserModuleでexportが必要
実際の連携例
// UserModule: ユーザー機能を他のモジュールに提供
@Module({
imports: [TypeOrmModule.forFeature([User])],
controllers: [UserController],
providers: [UserService],
exports: [UserService] // 👈 他のモジュールでも使用可能
})
export class UserModule {}
// OrderModule: UserModuleの機能を利用
@Module({
imports: [
TypeOrmModule.forFeature([Order]),
UserModule // 👈 UserServiceを使用可能になる
],
controllers: [OrderController],
providers: [OrderService]
})
export class OrderModule {}
// OrderService内でUserServiceを使用
@Injectable()
export class OrderService {
constructor(
private userService: UserService // 👈 自動的に注入される
) {}
}
なぜこの構成が良いのか？
1. チーム開発に最適
- 各チームが担当モジュールに集中できる
- 他チームの作業に影響されにくい
- コードの衝突が起きにくい
2. 保守性の向上
- 機能追加時、該当モジュールだけを修正
- バグ修正の影響範囲が限定的
- テストも部署単位で実施可能
3. 再利用性
- 他のプロジェクトでもモジュール単位で再利用
- マイクロサービス化への移行も容易
3. コントローラー - HTTPリクエストの窓口
コントローラー はHTTPリクエストを受け取り、適切なレスポンスを返す役割を担います。
@Controller('users')
export class UserController {
constructor(private readonly userService: UserService) {}
@Get()
async findAll(): Promise<User[]> {
return this.userService.findAll();
}
@Post()
async create(@Body() createUserDto: CreateUserDto): Promise<User> {
return this.userService.create(createUserDto);
}
@Get(':id')
async findOne(@Param('id') id: string): Promise<User> {
return this.userService.findOne(+id);
}
}
役割
- HTTPリクエストのルーティング
- リクエストデータの検証
- サービス層への処理委譲
- レスポンスの整形
4. リゾルバー - GraphQLの橋渡し役
GraphQLを使用する場合は、リゾルバー がクエリやミューテーションを処理します。
@Resolver(() => User)
export class UserResolver {
constructor(private readonly userService: UserService) {}
@Query(() => [User])
async users(): Promise<User[]> {
return this.userService.findAll();
}
@Mutation(() => User)
async createUser(
@Args('createUserInput') createUserInput: CreateUserInput
): Promise<User> {
return this.userService.create(createUserInput);
}
}
役割
- GraphQLクエリ/ミューテーションの処理
- GraphQLスキーマの定義
- サービス層への処理委譲
5. サービス - ビジネスロジックの心臓部
サービス はアプリケーションの核となるビジネスロジックを実装します。
@Injectable()
export class UserService {
constructor(
@InjectRepository(User)
private userRepository: Repository<User>,
) {}
async findAll(): Promise<User[]> {
return this.userRepository.find();
}
async create(createUserDto: CreateUserDto): Promise<User> {
// ビジネスロジック
const existingUser = await this.userRepository.findOne({
where: { email: createUserDto.email }
});
if (existingUser) {
throw new ConflictException('Email already exists');
}
const user = this.userRepository.create(createUserDto);
return this.userRepository.save(user);
}
async findOne(id: number): Promise<User> {
const user = await this.userRepository.findOne({ where: { id } });
if (!user) {
throw new NotFoundException('User not found');
}
return user;
}
}
役割
- ビジネスロジックの実装
- データベースとの連携
- 他サービスとの協調
- 例外処理
データフローの全体像
実際のリクエスト処理は以下の流れで進みます：
1. クライアント → HTTP Request
2. コントローラー → リクエスト受信・検証
3. サービス → ビジネスロジック実行
4. データベース → データ操作
5. サービス → 結果をコントローラーに返却
6. コントローラー → HTTP Response
7. クライアント → レスポンス受信
依存性注入（DI）の威力
Nest.jsの強力な機能の一つが 依存性注入（Dependency Injection） です。
// サービスをコントローラーに自動注入
@Controller('users')
export class UserController {
constructor(
private readonly userService: UserService, // 自動注入
private readonly emailService: EmailService // 自動注入
) {}
}
DIのメリット
- 疎結合: クラス間の依存関係が緩やか
- テスタビリティ: モックオブジェクトの注入が簡単
- 保守性: 実装の変更が他に影響しにくい
実践的な設計パターン
フォルダ構成例
src/
├── app.module.ts
├── main.ts
└── modules/
├── user/
│ ├── user.module.ts
│ ├── user.controller.ts
│ ├── user.service.ts
│ ├── user.entity.ts
│ └── dto/
│ ├── create-user.dto.ts
│ └── update-user.dto.ts
└── product/
├── product.module.ts
├── product.controller.ts
└── product.service.ts
モジュール間の連携
@Module({
imports: [UserModule], // UserServiceを利用可能に
controllers: [OrderController],
providers: [OrderService],
})
export class OrderModule {}
@Injectable()
export class OrderService {
constructor(
private readonly userService: UserService, // 他モジュールのサービス注入
) {}
}
まとめ
Nest.jsのアーキテクチャは一見複雑に見えますが、各コンポーネントの役割を理解すれば、非常に合理的な設計であることがわかります。
- ルートモジュール: アプリケーション全体の統合
- モジュール: 機能の境界とスコープ管理
- コントローラー/リゾルバー: リクエスト処理の窓口
- サービス: ビジネスロジックの実装
この階層構造により、大規模なアプリケーションでも保守性を保ちながら開発できます。
次回は実際にCRUD APIを構築しながら、これらのコンポーネントを実装する方法を解説予定です！
参考リンク
#NestJS #TypeScript #Node.js #バックエンド #アーキテクチャ