ASP.NET Core 3.x APIバージョン管理

4838 ワード
AS.NET CORE

前言


一般的には、私たちのAPIを変更する必要がありますが、バージョン管理を考慮する必要はありません.しかし、私たちはその時までそれを実現するべきではありません.私たちはアプリケーション開発時からバージョンポリシーを制定しなければなりません.私たちはずっとこのポリシーに従って開発しています.
私たちは実際に多くの方法で私たちのAPIバージョンの制御を実現することができますが、実際にはバージョン制御には最善の方法はありません.これは私たちが向いているユーザーにかかっています.

APIバージョン管理タイプ


バージョン管理パッケージのインストール
Install-Package Microsoft.AspNetCore.Mvc.Versioning

バージョン設定は、Startup.csのConfigureServicesメソッドで行い、コントローラが特性によってバージョンを設定することで、バージョン制御を実現することができる.
services.AddApiVersioning(options => {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});
  • options.DefaultApiVersion = new ApiVersion(1,0):この設定は必須ではありません.デフォルトでは1.0を設定していますが、明示的な宣言は良い習慣です.もちろん、DefaultApiVersionはデフォルトの[ApiVersion("1.0")]をコントローラに追加します.つまり、APIバージョンを暗黙的にバインドしますが、後で明示的な設定を開発したり、便利にしたりします.
  • options.AssumeDefaultVersionWhenUnspecified = true:デフォルトのAPIバージョン管理では、
    • を開くには、プロパティをtrueに設定する必要があります.
  • options.ReportApiVersions = true:デフォルトでは無効です.このオプションを有効にすると、APIエンドポイントからの応答にヘッダーが付き、クライアントがどのバージョンをサポートするか、推奨しないかを示します(api-supported-versions:1.1,2.0、api-deprecated-versions:1.0)
    • .
    デフォルトでは、4つのバージョン管理方法が用意されています.
  • 文字列パラメータ
  • HTTPリクエストヘッダ
    • を通過する.
  • URL方式
  • メディアタイプ(Media Type)
    • デフォルトの方法は、api-versionという名前のクエリー文字列パラメータを使用します.また、バージョン管理ルールを自分で定義することもできます.

    APIバージョン制約方式

  • 文字列パラメータ形式
    • services.AddApiVersioning(options => 
    options.ApiVersionReader = new QueryStringApiVersionReader("v"));
  • HTTPリクエストヘッダ
    • services.AddApiVersioning(options => 
    options.ApiVersionReader = new HeaderApiVersionReader("api-version"));
  • 組合せ方式
    • services.AddApiVersioning(options => {
    options.ApiVersionReader = ApiVersionReader.Combine(
        new QueryStringApiVersionReader("v"),
        new HeaderApiVersionReader("v"));});
  • URL方式
    • services.AddApiVersioning(options => options.ApiVersionReader = 
    new UrlSegmentApiVersionReader());

    バージョンを表すパラメータ名を変更できます(たとえば、上記のクエリー文字列メソッドでは、デフォルトのvの代わりにアルファベットapi-versionを使用します).

    コントローラとメソッドにバージョン情報を追加


    バージョン管理ポリシーを選択し、コンフィギュレーション・サービス・メソッドで構成した後、APIエンド・ポイントのバージョン管理を開始できます.これらのプロパティをコントローラおよびメソッドに適用できます.
  • コントローラのデフォルトでは、APIバージョンのプロパティがなく、暗黙的に構成されたデフォルトのAPIバージョンがない場合があります.既定の設定では1.0を使用します.
  • [ApiVersion("1.0")]プロパティを使用してコントローラにコメントします.これは、APIバージョン1.0
    • をサポートしていることを意味します.
  • コントローラは、複数のAPIバージョンをサポートすることができる.[ApiVersion(...)]コントローラに複数の属性を適用するだけで
  • コントローラでサポートされている複数のバージョンを区別するために、[MapToApiVersion()]プロパティアノテーションコントローラメソッドを使用します.

    • URLパスを使用する場合は、次のコードクリップを参照してください.
    [Route("api/v{version:apiVersion}/[controller]")]

    APIコントローラが廃棄されました.設定するだけです.
    [ApiVersion("1.0", Deprecated = true)]

    すべてのAPIバージョン情報は、次の方法で取得できます.
    var apiVersion = HttpContext.GetRequestedApiVersion();

    もちろん彼はモデルバインドもサポートしており、モデル形式で取得することもできます.
      [HttpGet]
   public string Get(ApiVersion apiVersion) => $"Controller = {GetType().Name}
    Version = {apiVersion}";
    }

    APIバージョン制約


    メソッドとコントローラでバージョンを指定するだけでなく、別の方法を採用することもできます.
    services.AddApiVersioning( options =>
{
    options.Conventions.Controller().HasApiVersion(1, 0);
});

    上記のコードを見ると、HomeControllerの構成バージョンが表示されます.これにより、バージョンを集中的に管理することができます.
    services.AddApiVersioning( options =>
{
    options.Conventions.Controller()	   
                       .HasDeprecatedApiVersion(1, 0)
                       .HasApiVersion(1, 1)
                       .HasApiVersion(2, 0)
                       .Action(c => c.Get1_0()).MapToApiVersion(1, 0)
                       .Action(c => c.Get1_1()).MapToApiVersion(1, 1)
                       .Action(c => c.Get2_0()).MapToApiVersion(2, 0);
});

    APIバージョン制約とバージョン管理属性を同時に使用できます.
    もちろん、コンストレイントをカスタマイズすることもできます.NET Core 3.0から、この目的のためのIControllerConventionのインタフェースがあります.
    options.Conventions.Add(new MyCustomConvention());

    もちろん、異なるネーミングスペースのインタフェースで制約することもできます.
    options.Conventions.Add(new VersionByNamespaceConvention());

    例えば次のようなファイル形式です
    api/v1/UsersController
api/v2/UsersController
api/v2_1/UsersController

    マッピングされたパスは次のとおりです.
    api/1.0/users
api/2.0/users
api/2.1/users
    Redis Sorted Setタイプの説明
    Redisラーニングおよびアプリケーションレコード(2)--共通データ型およびコマンド