1

ASP.NET Web APIコントローラーによってスローされたHttpResponseException例外のドキュメントコメントを作成する方法を知りたいですか？通常、ケースごとに異なる種類の例外をスローするため、例外の種類ごとにドキュメントコメントを記述します/// <exception cref="ResourceNotFound">Resource not found</exception>。ただし、HttpResponseExceptionを使用するStatusCodeと、例外のプロパティがエラーケースを識別します。

例外タイプごとにコメントHttpResponseExceptionを書き込む方法に対応して、スローされる可能性のある各ケースをどのように文書化する必要がありますか？それぞれがステータスコードで識別されますか？/// <exception></exception>

4

2 に答える 2

1

TL;DR バージョン: 主に、クライアントが対応できるコードと情報を使用して例外応答を設計します。標準の HTTP ステータス コードを可能な限り活用します。クライアント アプリの動作をガイドするために、HTTP 仕様にあるものを超えて提供するものを文書化します。次に、可能であれば、クライアント開発者が開発とトラブルシューティングに使用できる情報を提供します。

HTTP ベースの API のエラー応答を設計する際に、エラー応答に基づいてクライアント側でどのような期待と対応する動作がトリガーされるかを自問します。クライアントが HTTP ステータス コード 500 を受信した場合、サーバーで何らかの「誤動作」が発生したため、リクエストを適切に処理できなかったと見なすことができます。ステータス コード 500のHTTP 仕様によると、これは別のコードを適切に割り当てることができない場合の包括的なステータス コードの一種です。サーバーがちょうど「ブーム」になったことを知っていることを除けば、クライアントにとってはあまり役に立ちません。ただし、HTTP ステータス コード 503 Service Unavailable があり、Retry-AfterHTTP ヘッダーを介して、停止が続く可能性がある情報をクライアントに提供します。

コメントの特定の例では、データベース例外があったことをクライアントに伝えることはあまり役に立ちません。クライアントがそれに対してできることはおそらくないからです。運用担当者や開発者が使用できるように、サーバー側の例外に関する詳細情報をログに記録し、HTTP ステータス コードでクライアントに問題を通知します。

唯一の例外は、リクエストの解析に失敗したときに、予期しない要素や不足している要素 (など) に関する詳細情報を提供することです。これは、400 Bad Request の HTTP ステータス コードを含む応答の一部として送信します。クライアント アプリはおそらくその情報を使って何もできませんが、クライアント開発者はそれを高く評価します。

于 2012-11-19T16:27:34.023 に答える
0

通常の C# 例外の場合と同様に、Web API コントローラー メソッドでエラー ケースを文書化できるソリューションを見つけました。エラーのフラグ付けに使用する各 HTTP ステータス コードを のサブクラスにマップしますHttpResponseException。これは、Web API コントローラー メソッドのドキュメント コメントでエラー ケースを説明することだけにかかっていた、私の特定の問題を解決します。

例として、次のコードを検討してください。

public class HttpNotFoundException : HttpResponseException
{
    public HttpNotFoundException(string reason)
        : base(new HttpResponseMessage { StatusCode = HttpStatusCode.NotFound, ReasonPhrase = reason })
    { }
}

public class HttpInternalServerError : HttpResponseException
{
    public HttpInternalServerError(string reason)
        : base(new HttpResponseMessage { StatusCode = HttpStatusCode.InternalServerError, ReasonPhrase = reason })
    { }
}

public class ResourceApiController : ApiController
{
    IRepository Repository { get; set; }

    /// <summary>
    /// Delete a resource.
    /// </summary>
    /// <param name="id">Resource ID.</param>
    /// <exception cref="HttpNotFoundException">Resource not found.</exception>
    /// <exception cref="HttpInternalServerError">An internal error was detected, for instance in database service.</exception>
    public void DeleteResourceById(string id)
    {
        try
        {
            Repository.Delete(id);
        }
        catch (WebResourceNotFoundError)
        {
            throw new HttpNotFoundException(string.Format("Build '{0}' not found", id));
        }
        catch (DatabaseServiceException)
        {
            throw new HttpInternalServerError("Database service operation failed");
        }
    }
}
于 2012-11-20T08:30:48.650 に答える