細聊ASP.NET Core WebAPI格式化程式

前言我們在使用ASP.NET Core WebApi時它支持使用指定的輸入和輸出格式來交換數據。輸入數據靠模型綁定的機制處理，輸出數據則需要用格式化的方式進行處理。ASP.NET Core框架已經內置了處理JSON和XML的輸入和輸出方式，預設的情況我們提交JSON格式的內容，它可以自行進行模型綁 ...

前言

我們在使用ASP.NET Core WebApi時它支持使用指定的輸入和輸出格式來交換數據。輸入數據靠模型綁定的機制處理，輸出數據則需要用格式化的方式進行處理。ASP.NET Core框架已經內置了處理JSON和XML的輸入和輸出方式，預設的情況我們提交JSON格式的內容，它可以自行進行模型綁定，也可以把對象類型的返回值輸出成JSON格式，這都歸功於內置的JSON格式化程式。本篇文章我們將通過自定義一個YAML格式的轉換器開始，逐步瞭解它到底是如何工作的。以及通過自帶的JSON格式化輸入輸出源碼，加深對Formatter程式的瞭解。

自定義開始

要想先瞭解Formatter的工作原理，當然需要從自定義開始。因為一般自定義的時候我們一般會選用自己最簡單最擅長的方式去擴展，然後逐步完善加深理解。格式化器分為兩種，一種是用來處理輸入數據格式的InputFormatter，另一種是用來處理返回數據格式的OutputFormatter。本篇文章示例，我們從自定義YAML格式的轉換器開始。因為目前YAML格式確實比較流行，得益於它簡單明瞭的格式，目前也有很多中間件都是用YAML格式。這裡我們使用的是YamlDotNet這款組件，具體的引入信息如下所示

<PackageReference Include="YamlDotNet" Version="15.1.0" />

YamlInputFormatter

首先我們來看一下自定義請求數據的格式化也就是InputFormatter，它用來處理了請求數據的格式，也就是我們在Http請求體里的數據格式如何處理，手下我們需要定義個YamlInputFormatter類，繼承自TextInputFormatter抽象類

public class YamlInputFormatter : TextInputFormatter
{
    private readonly IDeserializer _deserializer;

    public YamlInputFormatter(DeserializerBuilder deserializerBuilder)
    {
        _deserializer = deserializerBuilder.Build();

        //添加與之綁定的MediaType，這裡其實綁定的提交的ContentType的值
        //如果請求ContentType:text/yaml或ContentType:text/yml才能命中該YamlInputFormatter
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/yaml"));
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/yml"));
        
        //添加編碼類型比如application/json;charset=UTF-8後面的這種charset
        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }

    public override async Task<InputFormatterResult> ReadRequestBodyAsync(InputFormatterContext context, Encoding encoding)
    {
        ArgumentNullException.ThrowIfNull(context);
        ArgumentNullException.ThrowIfNull(encoding);

        //獲取請求Body
        var readStream = context.HttpContext.Request.Body;
        
        object? model;
        try
        {
            TextReader textReader = new StreamReader(readStream);
            //獲取Action參數類型
            var type = context.ModelType;
            //把yaml字元串轉換成具體的對象
            model = _deserializer.Deserialize(textReader, type);
        }
        catch (YamlException ex) 
        {
            context.ModelState.TryAddModelError(context.ModelName, ex.Message);
            throw new InputFormatterException("反序列化輸入數據時出錯\n\n", ex.InnerException!);
        }

        if (model == null && !context.TreatEmptyInputAsDefaultValue)
        {
            return InputFormatterResult.NoValue();
        }
        else
        {
            return InputFormatterResult.Success(model);
        }
    }
}

這裡需要註意的是配置SupportedMediaTypes，也就是添加與YamlInputFormatter綁定的MediaType，也就是我們請求時設置的Content-Type的值，這個配置是必須要的，否則沒辦法判斷當前YamlInputFormatter與哪種Content-Type進行綁定。接下來定義完了之後如何把它接入程式使用它呢？也很簡單在MvcOptions中配置即可，如下所示

builder.Services.AddControllers(options => {
    options.InputFormatters.Add(new YamlInputFormatter(new DeserializerBuilder()));
});

接下來我們定義一個簡單類型和Action來演示一下，類和代碼不具備任何實際意義，只是為了演示

[HttpPost("AddAddress")]
public Address AddAddress(Address address)
{
    return address;
}

public class Address
{
    public string City { get; set; }
    public string Country { get; set; }
    public string Phone { get; set; }
    public string ZipCode { get; set; }
    public List<string> Tags { get; set; }
}

我們用Postman測試一下，提交一個yaml類型的格式，效果如下所示
這裡需要註意的是我們需要在Postman中設置Content-Type為text/yml或text/yaml

YamlOutputFormatter

上面我們演示瞭如何定義InputFormatter它的作用是將請求的數據格式化成具體類型。無獨有偶，既然請求數據格式可以定義，那麼輸出的數據格式同樣可以定義，這裡就需要用到OutputFormatter。接下來我們定義一個YamlOutputFormatter繼承自TextOutputFormatter抽象類，代碼如下所示

public class YamlOutputFormatter : TextOutputFormatter
{
    private readonly ISerializer _serializer;

    public YamlOutputFormatter(SerializerBuilder serializerBuilder)
    {
        //添加與之綁定的MediaType，這裡其實綁定的提交的Accept的值
        //如果請求Accept:text/yaml或Accept:text/yml才能命中該YamlOutputFormatter
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/yaml"));
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/yml"));

        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);

        _serializer = serializerBuilder.Build();
    }

    public override bool CanWriteResult(OutputFormatterCanWriteContext context)
    {
        //什麼條件可以使用yaml結果輸出，至於為什麼要重寫CanWriteResult方法，我們在後面分析源碼的時候會解釋
        string accept = context.HttpContext.Request.Headers.Accept.ToString() ?? "";
        if (string.IsNullOrWhiteSpace(accept))
        {
            return false;
        }

        var parsedContentType = new MediaType(accept);
        for (var i = 0; i < SupportedMediaTypes.Count; i++)
        {
            var supportedMediaType = new MediaType(SupportedMediaTypes[i]);
            if (parsedContentType.IsSubsetOf(supportedMediaType))
            {
                return true;
            }
        }
        return false;
    }

    public override async Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        ArgumentNullException.ThrowIfNull(context);
        ArgumentNullException.ThrowIfNull(selectedEncoding);

        try
        {
            var httpContext = context.HttpContext;
            //獲取輸出的對象，轉成成yaml字元串並輸出
            string respContent = _serializer.Serialize(context.Object);
            await httpContext.Response.WriteAsync(respContent);
        }
        catch (YamlException ex)
        {
            throw new InputFormatterException("序列化輸入數據時出錯\n\n", ex.InnerException!);
        }
    }
}

同樣的這裡我們也添加了SupportedMediaTypes的值，它的作用是我們請求時設置的Accept的值，這個配置也是必須要的，也就是請求的頭中為Accept:text/yaml或Accept:text/yml才能命中該YamlOutputFormatter。配置的時候同樣也在MvcOptions中配置即可

builder.Services.AddControllers(options => {
    options.OutputFormatters.Add(new YamlOutputFormatter(new SerializerBuilder()));
});

接下來我們同樣還是使用上面的代碼進行演示，只是我們這裡更換一下重新設置一下相關Header即可，這次我們直接提交json類型的數據，它會輸出yaml格式，代碼什麼的完全不用變，結果如下所示
這裡需要註意的請求頭的設置發生了變化

小結

上面我們講解了控制請求數據格式的TextInputFormatter和控制輸出格式的TextOutputFormatter。其中InputFormatter負責給ModelBinding輸送類型對象，OutputFormatter負責給ObjectResult輸出值，這我們可以看到它們只能控制WebAPI中Controller/Action的且返回ObjectResult的這種情況才生效，其它的比如MinimalApi、GRPC是起不到效果的。通過上面的示例，有同學心裡可能會存在疑問，上面在AddControllers方法中註冊TextInputFormatter和TextOutputFormatter的時候，沒辦法完成註入的服務，比如如果YamlInputFormatter或YamlOutputFormatter構造實例的時候無法獲取DI容器中的實例。確實，如果使用上面的方式我們確實沒辦法完成這個需求，不過我們可以通過其它方法實現，那就是去擴展MvcOptions選項，實現如下所示

public class YamlMvcOptionsSetup : IConfigureOptions<MvcOptions>
{
    private readonly ILoggerFactory _loggerFactory;

    public YamlMvcOptionsSetup(ILoggerFactory loggerFactory)
    {
        _loggerFactory = loggerFactory;
    }

    public void Configure(MvcOptions options)
    {
        var yamlInputLogger = _loggerFactory.CreateLogger<YamlInputFormatter>();
        options.InputFormatters.Add(new YamlInputFormatter(new DeserializerBuilder()));

        var yamlOutputLogger = _loggerFactory.CreateLogger<YamlOutputFormatter>();
        options.OutputFormatters.Add(new YamlOutputFormatter(new SerializerBuilder()));
    }
}

我們定義了YamlMvcOptionsSetup去擴展MvcOptions選項，然後我們將YamlMvcOptionsSetup註冊到容器即可

builder.Services.TryAddEnumerable(ServiceDescriptor.Transient<IConfigureOptions<MvcOptions>, YamlMvcOptionsSetup>());

探究工作方式

上面我們演示瞭如何自定義InputFormatter和OutputFormatter，也講解了InputFormatter負責給ModelBinding輸送類型對象，OutputFormatter負責給ObjectResult輸出值。接下來我們就通過閱讀其中的源碼來看一下InputFormatter和OutputFormatter是如何工作來影響模型綁定和ObjectResult的結果。

需要註意的是！我們展示的源碼是刪減過的，只關註我們需要關註的地方，因為源碼中涉及的內容太多，不方便觀看，所以只保留我們關註的地方，還望諒解。

TextInputFormatter如何工作

上面我們看到了YamlInputFormatter是繼承了TextInputFormatter抽象類，並重寫了ReadRequestBodyAsync方法。接下來我們就從TextInputFormatter的ReadRequestBodyAsync方法來入手，我們來看一下源碼定義[點擊查看TextInputFormatter源碼