时间戳

首页 > 解决方案 > ASP.NET Core 在 Web API 中处理自定义响应/输出格式的方法

c# - ASP.NET Core 在 Web API 中处理自定义响应/输出格式的方法

问题描述

我想创建自定义 JSON 格式，它将响应包装在数据中并返回 Content-Type

vnd.myapi+json

目前我已经创建了一个包装类，我在我的控制器中返回，但如果可以在后台处理它会更好：

public class ApiResult<TValue>
{
    [JsonProperty("data")]
    public TValue Value { get; set; }

    [JsonExtensionData]
    public Dictionary<string, object> Metadata { get; } = new Dictionary<string, object>();

    public ApiResult(TValue value)
    {
        Value = value;
    }
}

[HttpGet("{id}")]
public async Task<ActionResult<ApiResult<Bike>>> GetByIdAsync(int id)
{
    var bike = _dbContext.Bikes.AsNoTracking().SingleOrDefault(e => e.Id == id);
    if (bike == null)
    {
        return NotFound();
    }
    return new ApiResult(bike);
}

public static class ApiResultExtensions
{
    public static ApiResult<T> AddMetadata<T>(this ApiResult<T> result, string key, object value)
    {
        result.Metadata[key] = value;
        return result;
    }
}

我想返回如下响应：

{
    "data": { ... },
    "pagination": { ... },
    "someothermetadata": { ... }
}

但是必须以某种方式将分页添加到我的控制器操作中的元数据中，当然这里有一些关于内容协商的文章：https ://docs.microsoft.com/en-us/aspnet/core/web-api/advanced /formatting?view=aspnetcore-2.1但我仍然想确保我走在正确的轨道上。

如果这将使用我的自定义格式化程序在后台处理，那么我将如何向它添加像分页这样的元数据，以便在“数据”之外而不是在其中？

当有一个自定义格式化程序时，我仍然希望有一些方法可以从我的控制器或通过某种机制向它添加元数据，以便格式可以扩展。

上述方法的一个优点或缺点是它适用于所有序列化程序 xml、json、yaml 等。通过使用自定义格式化程序，它可能仅适用于 json，我需要创建几个不同的格式化程序来支持我的所有格式想。

标签： c#asp.net-coreasp.net-core-mvcasp.net-core-webapi

解决方案

好的，在使用 ASP.NET Core 花了一些时间之后，我基本上可以想到 4 种方法来解决这个问题。这个话题本身非常复杂和广泛，老实说，我认为没有灵丹妙药或最佳实践。

对于自定义 Content-Type（假设您要实现application/hal+json），官方方式可能也是最优雅的方式是创建自定义输出格式化程序。通过这种方式，您的操作将不知道任何关于输出格式的信息，但由于依赖注入机制和作用域生命周期，您仍然可以控制控制器内部的格式化行为。

1.自定义输出格式化程序

这是OData 官方 C# 库和ASP.Net Core 的 json:api 框架使用的最流行的方式。可能是实现超媒体格式的最佳方式。

要从控制器控制自定义输出格式化程序，您必须创建自己的“上下文”以在控制器和自定义格式化程序之间传递数据，并将其添加到具有作用域生命周期的 DI 容器：

services.AddScoped<ApiContext>();

这样，ApiContext每个请求只有一个实例。您可以将它注入到您的控制器和输出格式化程序中，并在它们之间传递数据。

您还可以在自定义输出格式化程序中使用ActionContextAccessor和HttpContextAccessor访问您的控制器和操作。要访问控制器，您必须强制ActionContextAccessor.ActionContext.ActionDescriptor转换为ControllerActionDescriptor. 然后，您可以使用IUrlHelper和操作名称在输出格式化程序中生成链接，以便控制器不受此逻辑的影响。

IActionContextAccessor是可选的，默认情况下不添加到容器中，要在项目中使用它，您必须将其添加到 IoC 容器中。

services.AddSingleton<IActionContextAccessor, ActionContextAccessor>()

在自定义输出格式化程序中使用服务：

您不能在格式化程序类中进行构造函数依赖注入。例如，您无法通过向构造函数添加记录器参数来获取记录器。要访问服务，您必须使用传递给您的方法的上下文对象。

https://docs.microsoft.com/en-us/aspnet/core/web-api/advanced/custom-formatters?view=aspnetcore-2.0#read-write

花饰扣支持：

Swashbuckle 显然不会使用这种方法和使用过滤器的方法生成正确的响应示例。您可能必须创建自定义文档过滤器。

示例：如何添加分页链接：

通常分页、过滤是通过规范模式来解决的，您通常会在您的[Get]操作中为规范提供一些通用模型。然后，您可以在格式化程序中识别当前执行的操作是否通过其参数类型或其他内容返回元素列表：

var specificationParameter = actionContextAccessor.ActionContext.ActionDescriptor.Parameters.SingleOrDefault(p => p.ParameterType == typeof(ISpecification<>));
if (specificationParameter != null)
{
   // add pagination links or whatever
   var urlHelper = new UrlHelper(actionContextAccessor.ActionContext);
   var link = urlHelper.Action(new UrlActionContext()
   {
       Protocol = httpContext.Request.Scheme,
       Host = httpContext.Request.Host.ToUriComponent(),
       Values = yourspecification
   })
}

优点（或没有）：

  • 您的操作没有定义格式，他们对格式或如何生成链接以及将它们放在哪里一无所知。他们只知道结果类型，而不知道描述结果的元数据。

  • 可重复使用，您可以轻松地将格式添加到其他项目中，而无需担心如何在您的操作中处理它。与链接、格式相关的所有内容都在后台处理。你的行动不需要任何逻辑。

  • 序列化实现取决于您，您不必使用 Newtonsoft.JSON，例如可以使用Jil 。

缺点：

  • 这种方法的一个缺点是它只适用于特定的 Content-Type。因此，为了支持 XML，我们需要创建另一个自定义输出格式化程序，使用 Content-Typevnd.myapi+xml代替vnd.myapi+json.

  • 我们不直接处理操作结果

  • 实现起来可能更复杂

2.结果过滤器

结果过滤器允许我们定义某种行为，这些行为将在我们的操作返回之前执行。我认为它是某种形式的后钩。我不认为这是包装我们的回应的正确位置。

它们可以应用于每个操作或全局应用于所有操作。

就个人而言，我不会将它用于这种事情，而是将其用作第三个选项的补充。

包装输出的示例结果过滤器：

public class ResultFilter : IResultFilter
{
    public void OnResultExecuting(ResultExecutingContext context)
    {
        if (context.Result is ObjectResult objectResult)
        {
            objectResult.Value = new ApiResult { Data = objectResult.Value };
        }
    }

    public void OnResultExecuted(ResultExecutedContext context)
    {
    }
}

您可以输入相同的逻辑IActionFilter，它应该也可以工作：

public class ActionFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    {
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        if (context.Result is ObjectResult objectResult)
        {
            objectResult.Value = new ApiResult { Data = objectResult.Value };
        }
    }
}

这是包装响应的最简单方法，特别是如果您已经拥有带有控制器的现有项目。所以如果你在乎时间，就选这个吧。

3. 在您的操作中明确格式化/包装您的结果

（我在问题中的做法）

这也在这里使用：https ://github.com/nbarbettini/BeautifulRestApi/tree/master/src来实现https://github.com/ionwg/ion-doc/blob/master/index.adoc我个人认为这个将更适合自定义输出格式化程序。

这可能是最简单的方法，但它也将您的 API “密封”为该特定格式。这种方法有优点，但也有一些缺点。例如，如果您想更改 API 的格式，则不能轻易做到，因为您的操作与特定的响应模型相结合，并且如果您的操作中有一些关于该模型的逻辑，例如，您为下一个和上一个重新添加分页链接。您实际上必须重写所有操作和格式化逻辑以支持该新格式。使用自定义输出格式化程序，您甚至可以根据 Content-Type 标头支持这两种格式。

优点：

  • 适用于所有内容类型，格式是 API 的组成部分。
  • Swashbuckle 开箱即用，使用ActionResult<T>(2.1+) 时，您还可以为[ProducesResponseType]您的操作添加属性。

缺点：

  • 您无法使用Content-Type标题控制格式。application/json和始终保持不变application/xml。（也许是优势？）
  • 您的操作负责返回格式正确的响应。类似：return new ApiResponse(obj);或者您可以创建扩展方法并调用它，obj.ToResponse()但您始终必须考虑正确的响应格式。
  • 从理论上讲，自定义 Content-Type likevnd.myapi+json不会带来任何好处，并且仅为名称实现自定义输出格式化程序没有意义，因为格式化仍然是控制器操作的责任。

我认为这更像是正确处理输出格式的捷径。我认为遵循单一责任原则，它应该是输出格式化程序的工作，顾名思义它格式化输出。

4.自定义中间件

您可以做的最后一件事是自定义中间件，您可以IActionResultExecutor从那里解析并返回，IActionResult就像您在 MVC 控制器中所做的那样。

https://github.com/aspnet/Mvc/issues/7238#issuecomment-357391426

如果您需要访问控制器信息，您还可以解决IActionContextAccessor访问 MVC 的操作上下文并强制ActionDescriptor转换为。ControllerActionDescriptor

文档说：

资源过滤器像中间件一样工作，因为它们围绕管道中稍后出现的所有内容的执行。但是过滤器与中间件的不同之处在于它们是 MVC 的一部分，这意味着它们可以访问 MVC 上下文和构造。

但这并不完全正确，因为您可以访问操作上下文，并且可以从中间件返回操作结果，这是 MVC 的一部分。

如果您有什么要补充的，请分享您自己的经验和优缺点，请随时发表评论。

推荐阅读