Work Documentation

Appearance

WebAPI編：現代的な API 開発 ​

ASP.NET Core における Web API 開発の基本と、.NET Framework 時代からの移行ポイントを解説します。

従来の Web API と ASP.NET Core Web API の違い ​

.NET Framework 4.8.1 では、HTML 画面を返す ASP.NET MVC と、JSON などを返す ASP.NET Web API 2 は異なる仕組みで動いていました。継承するベースクラスや、ルーティングの仕組みも別々でした。

ASP.NET Core では、これらが統合されました。画面を返す場合も API を提供する場合も、同じコントローラーの仕組みを使用します。これにより、コードの共通化やテストが非常に簡単になりました。

また、IIS (Internet Information Services) への依存がなくなり、Kestrel という軽量で超高速な Web サーバーが内蔵されました。

コントローラーベース API と Minimal API ​

ASP.NET Core では、Web API を作成する方法として「コントローラーベース」と「Minimal API」の 2 つから選択できます。

  • コントローラーベース API

    従来の開発スタイルに近く、コントローラークラスを作成してその中にアクションメソッドを記述します。機能ごとにファイルを分割しやすいため、大規模な開発に適しています。

  • Minimal API

    Program.cs の中に直接ルートと処理を記述する、非常にシンプルな開発スタイルです。クラスの定義やコントローラーのセットアップといった余分なコードが必要ありません。

csharp
// Minimal API の記述例 (.NET 10)
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello", () => "Hello, World!");

app.Run();

少ない行数で動作し、実行速度もコントローラーベースより高速です。小規模なサービスやマイクロサービスに向いています。

依存性の注入 (DI) とミドルウェアパイプライン ​

ASP.NET Core の Web API は、DI (依存性の注入) とミドルウェアという 2 つの概念で成り立っています。

  • 依存性の注入 (DI)

    オブジェクトの生成と依存関係の解決をフレームワークが自動で行う仕組みです。サービスの有効期間には以下の 3 つがあり、用途に応じて登録します。

    • Transient: 要求されるたびに新しいインスタンスを作成します。
    • Scoped: 1 回の HTTP リクエストの間、同じインスタンスを使い回します。
    • Singleton: アプリケーションが起動してから終了するまで、単一のインスタンスを使い回します。

  • ミドルウェアパイプライン

    HTTP リクエストが届いてからレスポンスを返すまでに実行される処理の鎖 (チェーン) です。認証、ログ記録、例外処理などの機能を、呼び出したい順番に並べて設定します。

シリアライズとエラーハンドリング ​

データのやり取りやエラーの返し方も、現代的な標準仕様に合わせて洗練されました。

  • System.Text.Json による高速な JSON 処理

    .NET Framework でよく使われていた Newtonsoft.Json に代わり、標準の System.Text.Json が使われます。メモリ消費量が非常に少なく、動作が高速です。

  • RFC 7807 (Problem Details) による統一的なエラー応答

    API でエラーが発生した際、エラー内容を標準的な形式でクライアントに返します。ステータスコードやエラーの詳細情報が一貫した JSON フォーマットで出力されるため、クライアント側でのエラー処理が容易になります。

json
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "指定されたユーザーが見つかりませんでした。"
}