AutoWrapper：通过有意义的响应来美化您的ASP.NET Core API

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

    private readonly ILogger _logger;

    public WeatherForecastController(ILogger logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public IEnumerable Get()
    {
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

 运行应用程序时，将以JSON格式显示以下输出：

[
    {
        "date": "2019-09-16T13:08:39.5994786-05:00",
        "temperatureC": -8,
        "temperatureF": 18,
        "summary": "Bracing"
    },
    {
        "date": "2019-09-17T13:08:39.5995153-05:00",
        "temperatureC": 54,
        "temperatureF": 129,
        "summary": "Cool"
    },
    {
        "date": "2019-09-18T13:08:39.5995162-05:00",
        "temperatureC": 33,
        "temperatureF": 91,
        "summary": "Bracing"
    },
    {
        "date": "2019-09-19T13:08:39.5995166-05:00",
        "temperatureC": 38,
        "temperatureF": 100,
        "summary": "Balmy"
    },
    {
        "date": "2019-09-20T13:08:39.599517-05:00",
        "temperatureC": -3,
        "temperatureF": 27,
        "summary": "Sweltering"
    }
]

太好了，其API的工作与我们期望的一样，只是它没有给我们带来有意义的回应。我们知道数据是响应中非常重要的部分，但是，随便吐出数据是因为JSON响应实际上并没有太大帮助，尤其是当每个请求之间发生意外行为时。

//This is just an idiot example to trigger an error
int num = Convert.ToInt32("a");

上面的代码尝试将包含非数字值的string转换为integer类型，这将在运行时导致错误。响应输出看起来像这样：

using AutoWrapper;

3.在UseRouting()中间件“之前”的Startup.cs的Configure()方法中注册下面的中间件：

app.UseApiResponseAndExceptionWrapper();

默认的API版本格式设置为“ 1.0.0.0”。如果希望为API指定其他版本格式，则可以执行以下操作：

app.UseApiResponseAndExceptionWrapper(new ApiResponseOptions { ApiVersion = "2.0" });

很简单！现在，尝试再次构建并运行ASP.NET Core API默认应用程序。根据我们的示例，以下是“WeatherForecastController” API 响应的样子：

{
    "message": "Request successful.",
    "isError": false,
    "result": [
        {
            "date": "2019-09-16T23:37:51.5544349-05:00",
            "temperatureC": 21,
            "temperatureF": 69,
            "summary": "Mild"
        },
        {
            "date": "2019-09-17T23:37:51.554466-05:00",
            "temperatureC": 28,
            "temperatureF": 82,
            "summary": "Cool"
        },
        {
            "date": "2019-09-18T23:37:51.554467-05:00",
            "temperatureC": 21,
            "temperatureF": 69,
            "summary": "Sweltering"
        },
        {
            "date": "2019-09-19T23:37:51.5544676-05:00",
            "temperatureC": 53,
            "temperatureF": 127,
            "summary": "Chilly"
        },
        {
            "date": "2019-09-20T23:37:51.5544681-05:00",
            "temperatureC": 22,
            "temperatureF": 71,
            "summary": "Bracing"
        }
    ]
}

如果您注意到了，那么输出现在在响应中包含一些属性，例如message，isError以及在result属性中包含的实际数据。

{
    "isError": true,
    "responseException": {
        "exceptionMessage": "Request not found. The specified uri does not exist.",
        "details": null,
        "referenceErrorCode": null,
        "referenceDocumentLink": null,
        "validationErrors": null
    }
}

现在注意到响应对象是如何更改的。statusCode自动设置为404。当已经发生任何意外错误或异常时，result属性将自动省略，而显示responseException属性以显示错误消息和额外信息。

//This is just an idiot example to trigger an error
int num = Convert.ToInt32("a");

现在它将给您以下响应：

{
    "isError": true,
    "responseException": {
        "exceptionMessage": "Unhandled Exception occured. Unable to process the request.",
        "details": null,
        "referenceErrorCode": null,
        "referenceDocumentLink": null,
        "validationErrors": null
    }
}

控制台窗口将显示以下内容：

app.UseApiResponseAndExceptionWrapper( new AutoWrapperOptions { IsDebug = true });

现在，当您再次运行该应用程序以触发异常时，它将显示如下内容：

{
    "isError": true,
    "responseException": {
        "exceptionMessage": " Input string was not in a correct format.",
        "details": "   at System.Number.ThrowOverflowOrFormatException(ParsingStatus status, TypeCode type)\r\n   at System.Number.ParseInt32(ReadOnlySpan`1 value, NumberStyles styles, NumberFormatInfo info)\r\n   at System.Convert.ToInt32(String value)\r\n   at AutoWrapperDemo.Controllers.WeatherForecastController.Get() in . . . . . . .,
        "referenceErrorCode": null,
        "referenceDocumentLink": null,
        "validationErrors": null
    }
}

注意，现在显示了真正的异常消息及其详细信息。

[HttpPost]
public async Task Post([FromBody]CreateBandDTO band)
{
    //Call a method to add a new record to the database
    try
    {
        var result = await SampleData.AddNew(band);
        return new ApiResponse("New record has been created to the database", result, 201);
    }
    catch (Exception ex)
    {
        //TO DO: Log ex
        throw;
    }
}

成功运行代码将为您提供以下结果：

{
    "message": "New record has been created to the database",
    "isError": false,
    "result": 100
}

ApiResponse对象具有可以设置的以下参数：

ApiResponse(string message, object result = null, int statusCode = 200, string apiVersion = "1.0.0.0")

throw new ApiException(ModelState.AllErrors());

用于抛出您自己的异常消息

throw new ApiException($"Record with id: {id} does not exist.", 400);

例如，让我们使用ModelState验证来修改POST方法：

[HttpPost]
public async Task Post([FromBody]CreateBandDTO band)
{
    if (ModelState.IsValid)
    {
        //Call a method to add a new record to the database
        try
        {
            var result = await SampleData.AddNew(band);
            return new ApiResponse("New record has been created to the database", result, 201);
        }
        catch (Exception ex)
        {
            //TO DO: Log ex
            throw;
        }
    }
    else
        throw new ApiException(ModelState.AllErrors());
}

验证失败时，运行代码将导致如下所示：

{
    "isError": true,
    "responseException": {
        "exceptionMessage": "Request responded with validation error(s). Please correct the specified validation errors and try again.",
        "details": null,
        "referenceErrorCode": null,
        "referenceDocumentLink": null,
        "validationErrors": [
            {
                "field": "Name",
                "message": "The Name field is required."
            }
        ]
    }
}

查看如何使用模型中的违规字段自动填充validationErrors属性。

ApiException(string message, int statusCode = 500, string errorCode = "", string refLink = "")
ApiException(IEnumerable errors, int statusCode = 400)
ApiException(System.Exception ex, int statusCode = 500)

app.UseApiResponseAndExceptionWrapper(new AutoWrapperOptions { ShowApiVersion = true });

默认API 版本格式设置为“ 1.0.0.0” 

app.UseApiResponseAndExceptionWrapper(new AutoWrapperOptions { 
    ShowApiVersion = true, 
    ApiVersion = "2.0" 
});

ShowStatusCode

app.UseApiResponseAndExceptionWrapper(new AutoWrapperOptions { ShowStatusCode = true });

IsDebug

app.UseApiResponseAndExceptionWrapper(new AutoWrapperOptions { IsDebug = true }); 

IsApiOnly

app.UseApiResponseAndExceptionWrapper(new AutoWrapperOptions { IsApiOnly = false} );

WrapWhenApiPathStartsWith

app.UseApiResponseAndExceptionWrapper(new AutoWrapperOptions { 
    IsApiOnly = false, 
    WrapWhenApiPathStartsWith = "/myapi" 
});

当请求路径包含WrapWhenApiPathStartsWith值时，这将激活AutoWrapper 来拦截HTTP响应。