.NET 9とMediatRで実践するクリーンアーキテクチャとCQRS:スケーラブルなREST APIの構築

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

ファットコントローラーが抱える問題点

多くのバックエンド開発者は、コントローラーがすべての処理を担うREST APIの構築からスタートします。単一のコントローラーアクションがHTTPペイロードを受け取り、バリデーションを実行し、EF Core経由でデータベースに問い合わせ、価格計算を行い、JSONレスポンスを整形します。この手軽な手法は、プロトタイプ作成や週末のハッカソンなどでは問題なく機能します。

しかし、規模が拡大するとこのパターンはすぐに破綻します。半年も経つと、日常的に使われるOrdersControllerのコードが1,200行を超えることも珍しくありません。生(Raw)のLINQクエリが何十ものエンドポイントに散らばり、税金計算のロジックを1箇所変更しただけで、顧客の決済、請求書生成、管理画面のレポート機能が同時に壊れてしまうリスクを抱えることになります。また、単一のHTTPステータスコードをテストするだけで、データベースコンテキスト全体と3つの外部HTTPクライアントをモック化しなければならず、ユニットテストは悪夢と化します。

私たちには明確な境界線が必要です。ビジネスルールは、データベース、プレゼンテーションフレームワーク、トランスポートプロトコルから完全に独立して存在しなければなりません。

基本概念:クリーンアーキテクチャ、CQRS、MediatR

クリーンアーキテクチャは、コードを同心円状のレイヤーに整理します。依存関係は常に内側のみに向かいます。内側のレイヤーが契約(インターフェース)を定義し、外側のレイヤーがその実装を提供します。

  • Domainレイヤー:コアエンティティ、値オブジェクト、ビジネスルール、ドメイン例外を含みます。外部パッケージへの依存は一切持ちません。
  • Applicationレイヤー:ユースケースのオーケストレーションを行います。リポジトリインターフェース、DTO、MediatRコマンド、クエリ、ビジネスパイプラインを定義します。
  • Infrastructureレイヤー:外部の関心事を扱います。EF CoreのDbContext、Redisキャッシュ、SendGridクライアント、バックグラウンドワーカーなどが含まれます。
  • Presentationレイヤー:ASP.NET CoreのコントローラーまたはMinimal APIを使用して、システムを外部へ公開します。

Applicationレイヤーの内部では、CQRS(コマンドクエリ責務分離:Command Query Responsibility Segregation)を実装します。CQRSは読み取り操作と書き込み操作を分離します:

  • コマンド(Commands):システムのステートを変更します(例:CreateProductCommand)。バリデーションとドメインの不変条件(Invariants)の維持に専念します。
  • クエリ(Queries):ステートを変更せずにデータを取得します(例:GetProductByIdQuery)。重厚なドメインエンティティをバイパスし、フラットなDTOに直接プロジェクション(射影)します。

コントローラーのコンストラクタに5つもの異なるサービスインターフェースをインジェクションする代わりに、MediatRのISenderをインジェクションします。MediatRはプロセス内メディエーターとして機能します。コントローラーがリクエストオブジェクトをディスパッチすると、MediatRが対応するハンドラーへそれを配信します。12人のエンジニアが50のエンドポイントを並行開発するようなコードベースでも、このパターンによりマージコンフリクトを大幅に削減し、コントローラーのメソッドを10行未満に維持できます。

実践演習:.NET 9によるECカタログAPIの構築

.NET 9 CLIを使用して、空のディレクトリから完全なカタログサービスを構築してみましょう。

ステップ1:ソリューションとプロジェクトのセットアップ

ターミナルで以下のコマンドを実行し、4層のプロジェクト構造を生成します:

# ソリューションディレクトリの作成
mkdir CleanCatalog && cd CleanCatalog
dotnet new sln -n CleanCatalog

# Coreプロジェクトの作成
dotnet new classlib -n CleanCatalog.Domain
dotnet new classlib -n CleanCatalog.Application

# 外部プロジェクトの作成
dotnet new classlib -n CleanCatalog.Infrastructure
dotnet new webapi -n CleanCatalog.Api --use-controllers

# ソリューションにプロジェクトを追加
dotnet sln add CleanCatalog.Domain CleanCatalog.Application CleanCatalog.Infrastructure CleanCatalog.Api

# 依存関係を内側に向けて接続
dotnet add CleanCatalog.Application reference CleanCatalog.Domain
dotnet add CleanCatalog.Infrastructure reference CleanCatalog.Application
dotnet add CleanCatalog.Api reference CleanCatalog.Application
dotnet add CleanCatalog.Api reference CleanCatalog.Infrastructure

それぞれのレイヤーに対応するMediatRとEF Coreを追加します:

# MediatR v12以降でコアク約とDI拡張機能をインストール
dotnet add CleanCatalog.Application package MediatR

# Infrastructure層のデータベース永続化パッケージ
dotnet add CleanCatalog.Infrastructure package Microsoft.EntityFrameworkCore.InMemory

# プレゼンテーションホストでのMediatR解決用パッケージ
dotnet add CleanCatalog.Api package MediatR

ステップ2:ドメインエンティティの定義

CleanCatalog.Domain内のClass1.csを削除します。自己カプセル化されたエンティティProduct.csを追加します:

namespace CleanCatalog.Domain.Entities;

public class Product
{
    public Guid Id { get; private set; }
    public string Name { get; private set; } = string.Empty;
    public string Sku { get; private set; } = string.Empty;
    public decimal Price { get; private set; }
    public DateTime CreatedAtUtc { get; private set; }

    private Product() { } // EF Coreで必要

    public Product(string name, string sku, decimal price)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("商品名は空にできません。", nameof(name));

        if (string.IsNullOrWhiteSpace(sku) || sku.Length < 3)
            throw new ArgumentException("SKUは3文字以上である必要があります。", nameof(sku));

        if (price <= 0.01m)
            throw new ArgumentOutOfRangeException(nameof(price), "価格は0.01ドル以上である必要があります。");

        Id = Guid.NewGuid();
        Name = name.Trim();
        Sku = sku.ToUpperInvariant().Trim();
        Price = price;
        CreatedAtUtc = DateTime.UtcNow;
    }
}

ステップ3:ApplicationレイヤーでのCQRSハンドラーの作成

まず、CleanCatalog.Application/Common/Interfaces/IProductRepository.csにリポジトリのインターフェース契約を定義します:

using CleanCatalog.Domain.Entities;

namespace CleanCatalog.Application.Common.Interfaces;

public interface IProductRepository
{
    Task<Product?> GetByIdAsync(Guid id, CancellationToken cancellationToken);
    Task AddAsync(Product product, CancellationToken cancellationToken);
}

次に、CleanCatalog.Application/Products/Commands/CreateProduct/CreateProductCommand.cs内にコマンドとそのハンドラーをまとめて実装します:

using CleanCatalog.Application.Common.Interfaces;
using CleanCatalog.Domain.Entities;
using MediatR;

namespace CleanCatalog.Application.Products.Commands.CreateProduct;

public record CreateProductCommand(string Name, string Sku, decimal Price) : IRequest<Guid>;

public class CreateProductCommandHandler : IRequestHandler<CreateProductCommand, Guid>
{
    private readonly IProductRepository _repository;

    public CreateProductCommandHandler(IProductRepository repository)
    {
        _repository = repository;
    }

    public async Task<Guid> Handle(CreateProductCommand request, CancellationToken cancellationToken)
    {
        var product = new Product(request.Name, request.Sku, request.Price);
        await _repository.AddAsync(product, cancellationToken);
        return product.Id;
    }
}

続いて、CleanCatalog.Application/Products/Queries/GetProductById/GetProductByIdQuery.csに読み取りクエリを作成します。ハンドラーがドメインエンティティを直接公開せず、フラットなDTOを返している点に注目してください:

using CleanCatalog.Application.Common.Interfaces;
using MediatR;

namespace CleanCatalog.Application.Products.Queries.GetProductById;

public record ProductDto(Guid Id, string Name, string Sku, decimal Price, DateTime CreatedAtUtc);

public record GetProductByIdQuery(Guid Id) : IRequest<ProductDto?>;

public class GetProductByIdQueryHandler : IRequestHandler<GetProductByIdQuery, ProductDto?>
{
    private readonly IProductRepository _repository;

    public GetProductByIdQueryHandler(IProductRepository repository)
    {
        _repository = repository;
    }

    public async Task<ProductDto?> Handle(GetProductByIdQuery request, CancellationToken cancellationToken)
    {
        var product = await _repository.GetByIdAsync(request.Id, cancellationToken);
        if (product is null) return null;

        return new ProductDto(
            product.Id,
            product.Name,
            product.Sku,
            product.Price,
            product.CreatedAtUtc);
    }
}

ステップ4:EF CoreによるInfrastructureの実装

CleanCatalog.Infrastructure/Persistence/AppDbContext.csおよびProductRepository.cs内にデータベースの永続化ロジックを実装します:

using CleanCatalog.Application.Common.Interfaces;
using CleanCatalog.Domain.Entities;
using Microsoft.EntityFrameworkCore;

namespace CleanCatalog.Infrastructure.Persistence;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<Product> Products => Set<Product>();
}

public class ProductRepository : IProductRepository
{
    private readonly AppDbContext _context;

    public ProductRepository(AppDbContext context)
    {
        _context = context;
    }

    public async Task AddAsync(Product product, CancellationToken cancellationToken)
    {
        await _context.Products.AddAsync(product, cancellationToken);
        await _context.SaveChangesAsync(cancellationToken);
    }

    public async Task<Product?> GetByIdAsync(Guid id, CancellationToken cancellationToken)
    {
        return await _context.Products
            .AsNoTracking()
            .FirstOrDefaultAsync(p => p.Id == id, cancellationToken);
    }
}

ステップ5:軽量なコントローラーの実装

コントローラーの役割は、HTTPリクエストをアプリケーションメッセージに変換することだけに留めるべきです。CleanCatalog.Api/ControllersにProductsController.csを追加します:

using CleanCatalog.Application.Products.Commands.CreateProduct;
using CleanCatalog.Application.Products.Queries.GetProductById;
using MediatR;
using Microsoft.AspNetCore.Mvc;

namespace CleanCatalog.Api.Controllers;

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly ISender _sender;

    public ProductsController(ISender sender)
    {
        _sender = sender;
    }

    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> Create([FromBody] CreateProductCommand command, CancellationToken ct)
    {
        var productId = await _sender.Send(command, ct);
        return CreatedAtAction(nameof(GetById), new { id = productId }, new { id = productId });
    }

    [HttpGet("{id:guid}")]
    [ProducesResponseType(typeof(ProductDto), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
    {
        var result = await _sender.Send(new GetProductByIdQuery(id), ct);
        return result is not null ? Ok(result) : NotFound();
    }
}

ステップ6:Program.csでのサービス登録

CleanCatalog.Api/Program.csを開き、.NET 9の依存関係注入(DI)コンテナにサービスを登録します:

using CleanCatalog.Application.Common.Interfaces;
using CleanCatalog.Application.Products.Commands.CreateProduct;
using CleanCatalog.Infrastructure.Persistence;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// ローカルテスト用にインメモリデータベースを使用
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseInMemoryDatabase("CatalogDb"));

builder.Services.AddScoped<IProductRepository, ProductRepository>();

// ApplicationアセンブリからMediatRハンドラーを登録
builder.Services.AddMediatR(cfg =>
    cfg.RegisterServicesFromAssembly(typeof(CreateProductCommand).Assembly));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

dotnet run --project CleanCatalog.Apiを実行してAPIを起動します。https://localhost:5001/swaggerにアクセスしてください。{"name": "Mechanical Keyboard", "sku": "KB-980", "price": 129.99}のボディでPOSTリクエストを送信すると、約15ミリ秒で201 Createdステータスコードが返されます。コントローラーは簡潔に保たれたままであり、ドメインルールによってデータの妥当性が確実に保証されます。

次のステップ

この構成により、各レイヤー間のクリーンな分離が実現されます。プロジェクトが成長してエンドポイントが2個から150個に増えたとしても、既存のハンドラーに手を加えることなく、新しいコマンドやクエリのレコードを追加していくだけで対応できます。

ここからさらに、MediatRのパイプラインビヘイビア(Pipeline Behavior)を組み込むことで、バリデーション(FluentValidationの活用など)やパフォーマンスログの記録といった横断的関心事(Cross-Cutting Concerns)を単一箇所で一元管理できるようになります。また、読み取りトラフィックが急増した際には、ProductRepository.GetByIdAsyncを高速な生DapperクエリやRedisキャッシュヒットに差し替えることも可能です。プレゼンテーション層はその変更を意識する必要すらありません。

Share: