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

前言

我們在使用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源碼👈]

public abstract class TextInputFormatter : InputFormatter
{
    public IList<Encoding> SupportedEncodings { get; } = new List<Encoding>();

    public override Task<InputFormatterResult> ReadRequestBodyAsync(InputFormatterContext context)
    {
        //判斷Encoding是否符合我們設置的SupportedEncodings中的值
        var selectedEncoding = SelectCharacterEncoding(context);
        if (selectedEncoding == null)
        {
            var exception = new UnsupportedContentTypeException(message);
            context.ModelState.AddModelError(context.ModelName, exception, context.Metadata);
            return InputFormatterResult.FailureAsync();
        }
         
        //這裏調用了ReadRequestBodyAsync方法
        return ReadRequestBodyAsync(context, selectedEncoding);
    }

    //這就是我們在YamlInputFormatter中實現的ReadRequestBodyAsync方法
    public abstract Task<InputFormatterResult> ReadRequestBodyAsync(
        InputFormatterContext context,
        Encoding encoding);

    protected Encoding? SelectCharacterEncoding(InputFormatterContext context)
    {
        var requestContentType = context.HttpContext.Request.ContentType;
        //解析ContentType
        var requestMediaType = string.IsNullOrEmpty(requestContentType) ? default : new MediaType(requestContentType);
        if (requestMediaType.Charset.HasValue)
        {
            var requestEncoding = requestMediaType.Encoding;
            if (requestEncoding != null)
            {
                //在我們設置SupportedEncodings的查找符合ContentType中包含值的
                for (int i = 0; i < SupportedEncodings.Count; i++)
                {
                    if (string.Equals(requestEncoding.WebName, SupportedEncodings[i].WebName, StringComparison.OrdinalIgnoreCase))
                    {
                        return SupportedEncodings[i];
                    }
                }
            }
            return null;
        }
        return SupportedEncodings[0];
    }
}

整體來說TextInputFormatter抽象類思路相對清晰，我們實現了ReadRequestBodyAsync抽象方法，這個抽象方法被當前類的重載方法ReadRequestBodyAsync(InputFormatterContext)方法中調用。果然熟悉設計模式之後會發現設計模式無處不在，這裏就是設計模式裏的模板方法模式。好了，我們繼續看源碼TextInputFormatter類又繼承了InputFormatter抽象類，我們繼續來看它的實現[點擊查看InputFormatter源碼👈]

public abstract class InputFormatter : IInputFormatter, IApiRequestFormatMetadataProvider
{
    //這裏定義了SupportedMediaTypes
    public MediaTypeCollection SupportedMediaTypes { get; } = new MediaTypeCollection();

    //根據ContentType判斷當前的值是否可以滿足調用當前InputFormatter
    public virtual bool CanRead(InputFormatterContext context)
    {
        if (SupportedMediaTypes.Count == 0)
        {
            throw new InvalidOperationException();
        }

        if (!CanReadType(context.ModelType))
        {
            return false;
        }
        
        //獲取ContentType的值
        var contentType = context.HttpContext.Request.ContentType;
        if (string.IsNullOrEmpty(contentType))
        {
            return false;
        }
        
        //判斷SupportedMediaTypes是否包含ContentType包含的值
        return IsSubsetOfAnySupportedContentType(contentType);
    }

    private bool IsSubsetOfAnySupportedContentType(string contentType)
    {
        var parsedContentType = new MediaType(contentType);
        //判斷設置的SupportedMediaTypes是否匹配ContentType的值
        for (var i = 0; i < SupportedMediaTypes.Count; i++)
        {
            var supportedMediaType = new MediaType(SupportedMediaTypes[i]);
            if (parsedContentType.IsSubsetOf(supportedMediaType))
            {
                return true;
            }
        }
        return false;
    }
  
    protected virtual bool CanReadType(Type type)
    {
        return true;
    }

    //核心方法
    public virtual Task<InputFormatterResult> ReadAsync(InputFormatterContext context)
    {
        return ReadRequestBodyAsync(context);
    }
    
    //抽象方法ReadRequestBodyAsync
    public abstract Task<InputFormatterResult> ReadRequestBodyAsync(InputFormatterContext context);

    //獲取當前InputFormatter支持的dContentType
    public virtual IReadOnlyList<string>? GetSupportedContentTypes(string contentType, Type objectType)
    {
        if (SupportedMediaTypes.Count == 0)
        {
            throw new InvalidOperationException();
        }

        if (!CanReadType(objectType))
        {
            return null;
        }

        if (contentType == null)
        {
            return SupportedMediaTypes;
        }
        else
        {
            var parsedContentType = new MediaType(contentType);
            List<string>? mediaTypes = null;

            foreach (var mediaType in SupportedMediaTypes)
            {
                var parsedMediaType = new MediaType(mediaType);
                if (parsedMediaType.IsSubsetOf(parsedContentType))
                {
                    if (mediaTypes == null)
                    {
                        mediaTypes = new List<string>(SupportedMediaTypes.Count);
                    }

                    mediaTypes.Add(mediaType);
                }
            }

            return mediaTypes;
        }
    }
}

這個類比較核心，我們來解析一下里面設計到的相關邏輯

先來看ReadAsync方法，這是被調用的根入口方法，這個方法調用了ReadRequestBodyAsync抽象方法，這也是模板方法模式。ReadRequestBodyAsync方法正是TextInputFormatter類中被實現的。
CanRead方法的功能是根據請求頭裏的Content-Type是否可以命中當前InputFormatter子類，所以它是決定我們上面YamlInputFormatter方法的校驗方法。
GetSupportedContentTypes方法則是在Content-Type裏解析出符合SupportedMediaTypes設置的MediaType。因爲在Http的Header裏，每一個鍵是可以設置多個值的，用;分割即可。

上面我們看到了InputFormatter類實現了IInputFormatter接口，看一下它的定義

public interface IInputFormatter
{
    bool CanRead(InputFormatterContext context);
    Task<InputFormatterResult> ReadAsync(InputFormatterContext context);
}

通過IInputFormatter接口的定義我們流看到了，它只包含兩個方法CanRead和ReadAsync。其中CanRead方法用來校驗當前請求是否滿足命中IInputFormatter實現類，ReadAsync方法來執行具體的策略完成請求數據到具體類型的轉換。接下來我們看一下重頭戲，在模型綁定中是如何調用IInputFormatter接口集合的

public class BodyModelBinderProvider : IModelBinderProvider
{
    private readonly IList<IInputFormatter> _formatters;
    private readonly MvcOptions? _options;

    public IModelBinder? GetBinder(ModelBinderProviderContext context)
    {
        ArgumentNullException.ThrowIfNull(context);
        //判斷當前Action參數是否可以滿足當前模型綁定類
        if (context.BindingInfo.BindingSource != null &&
            context.BindingInfo.BindingSource.CanAcceptDataFrom(BindingSource.Body))
        {
            if (_formatters.Count == 0)
            {
                throw new InvalidOperationException();
            }
 
            var treatEmptyInputAsDefaultValue = CalculateAllowEmptyBody(context.BindingInfo.EmptyBodyBehavior, _options);
 
            return new BodyModelBinder(_formatters, _readerFactory, _loggerFactory, _options)
            {
                AllowEmptyBody = treatEmptyInputAsDefaultValue,
            };
        }
 
        return null;
    }
}

通過BodyModelBinderProvider類我們可以看到，我們設置的IInputFormatter接口的實現類只能滿足綁定Body的場景，包含我們上面示例中演示的示例和[FromBody]這種形式。接下來我們來看BodyModelBinder類中的實現[點擊查看BodyModelBinder源碼👈]

public partial class BodyModelBinder : IModelBinder
{
    private readonly IList<IInputFormatter> _formatters;
    private readonly Func<Stream, Encoding, TextReader> _readerFactory;
    private readonly MvcOptions? _options;

    public BodyModelBinder(
        IList<IInputFormatter> formatters,
        IHttpRequestStreamReaderFactory readerFactory,
        MvcOptions? options)
    {
        _formatters = formatters;
        _readerFactory = readerFactory.CreateReader;
        _options = options;
    }

    internal bool AllowEmptyBody { get; set; }

    public async Task BindModelAsync(ModelBindingContext bindingContext)
    {
        //獲取Action綁定參數名稱
        string modelBindingKey;
        if (bindingContext.IsTopLevelObject)
        {
            modelBindingKey = bindingContext.BinderModelName ?? string.Empty;
        }
        else
        {
            modelBindingKey = bindingContext.ModelName;
        }

        var httpContext = bindingContext.HttpContext;
        //組裝InputFormatterContext
        var formatterContext = new InputFormatterContext(
            httpContext,
            modelBindingKey,
            bindingContext.ModelState,
            bindingContext.ModelMetadata,
            _readerFactory,
            AllowEmptyBody);

        var formatter = (IInputFormatter?)null;
        for (var i = 0; i < _formatters.Count; i++)
        {
            //通過IInputFormatter的CanRead方法來篩選IInputFormatter實例
            if (_formatters[i].CanRead(formatterContext))
            {
                formatter = _formatters[i];
                break;
            }
        }

        try
        {
            //調用IInputFormatter的ReadAsync方法，把請求的內容格式轉換成實際的模型對象
            var result = await formatter.ReadAsync(formatterContext);
            if (result.IsModelSet)
            {
                //將結果綁定到Action的相關參數上
                var model = result.Model;
                bindingContext.Result = ModelBindingResult.Success(model);
            }
        }
        catch (Exception exception) when (exception is InputFormatterException || ShouldHandleException(formatter))
        {
        }
    }
}

通過閱讀上面的源碼，相信大家已經可以明白了我們定義的YamlInputFormatter是如何工作起來的。YamlInputFormatter本質是IInputFormatter實例。模型綁定類中BodyModelBinder調用了ReadAsync方法本質是調用到了ReadRequestBodyAsync方法。在這個方法裏我們實現了請求yml格式到具體類型對象的轉換，然後把轉換後的對象綁定到了Action的參數上。

TextOutputFormatter如何工作

上面我們講解了輸入的格式化轉換程序，知道了ModelBinding通過獲取IInputFormatter實例來完成請求數據格式到對象的轉換。接下來我們來看一下控制輸出格式的OutputFormatter是如何工作的。通過上面自定義的YamlOutputFormatter我們可以看到它是繼承自TextOutputFormatter抽象類。整體來說它的這個判斷邏輯之類的和TextInputFormatter思路整體類似，所以咱們呢大致看一下關於工作過程的源碼即可還是從WriteResponseBodyAsync方法入手[點擊查看TextOutputFormatter源碼👈]

public abstract class TextOutputFormatter : OutputFormatter
{
    public override Task WriteAsync(OutputFormatterWriteContext context)
    {
        //獲取ContentType，需要注意的是這裏並非請求中設置的Content-Type的值，而是程序設置響應頭中的Content-Type值
        var selectedMediaType = context.ContentType;
        if (!selectedMediaType.HasValue)
        {
            if (SupportedEncodings.Count > 0)
            {
                selectedMediaType = new StringSegment(SupportedMediaTypes[0]);
            }
            else
            {
                throw new InvalidOperationException();
            }
        }
        
        //獲取AcceptCharset的值
        var selectedEncoding = SelectCharacterEncoding(context);
        if (selectedEncoding != null)
        {
            var mediaTypeWithCharset = GetMediaTypeWithCharset(selectedMediaType.Value!, selectedEncoding);
            selectedMediaType = new StringSegment(mediaTypeWithCharset);
        }
        else
        {
            //省略部分代碼
            return Task.CompletedTask;
        }

        context.ContentType = selectedMediaType;
        //寫輸出頭
        WriteResponseHeaders(context);
        return WriteResponseBodyAsync(context, selectedEncoding);
    }

    public abstract Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding);
}

需要注意的是我們省略了很多源碼，只關注我們關注的地方。這裏沒啥可說的和上面TextInputFormatter思路整體類似，也是基於模板方法模式入口方法其實是WriteAsync方法。不過這裏需要注意的是在WriteAsync方法中ContentType，這裏的ContentType並非我們在請求時設置的值，而是我們給響應頭中設置值。TextOutputFormatter繼承自OutputFormatter接下來我們繼續看一下它的實現[點擊查看OutputFormatter源碼👈]

public abstract class OutputFormatter : IOutputFormatter, IApiResponseTypeMetadataProvider
{
    protected virtual bool CanWriteType(Type? type)
    {
        return true;
    }

    //判斷當前請求是否滿足調用當前OutputFormatter實例
    public virtual bool CanWriteResult(OutputFormatterCanWriteContext context)
    {
        if (SupportedMediaTypes.Count == 0)
        {
            throw new InvalidOperationException();
        }
        //當前Action參數類型是否滿足設定
        if (!CanWriteType(context.ObjectType))
        {
            return false;
        }
        
        //這裏的ContentType依然是設置的響應頭而非請求頭
        if (!context.ContentType.HasValue)
        {
            context.ContentType = new StringSegment(SupportedMediaTypes[0]);
            return true;
        }
        else
        {
            //根據設置的輸出頭的ContentType判斷是否滿足自定義時設置的SupportedMediaTypes類型
            //比如YamlOutputFormatter中設置的SupportedMediaTypes和設置的響應ContentType是否滿足匹配關係
            var parsedContentType = new MediaType(context.ContentType);
            for (var i = 0; i < SupportedMediaTypes.Count; i++)
            {
                var supportedMediaType = new MediaType(SupportedMediaTypes[i]);
                if (supportedMediaType.HasWildcard)
                {
                    if (context.ContentTypeIsServerDefined
                        && parsedContentType.IsSubsetOf(supportedMediaType))
                    {
                        return true;
                    }
                }
                else
                {
                    if (supportedMediaType.IsSubsetOf(parsedContentType))
                    {
                        context.ContentType = new StringSegment(SupportedMediaTypes[i]);
                        return true;
                    }
                }
            }
        }

        return false;
    }

    //WriteAsync虛方法也就是TextOutputFormatter中從寫的方法
    public virtual Task WriteAsync(OutputFormatterWriteContext context)
    {
        WriteResponseHeaders(context);
        return WriteResponseBodyAsync(context);
    }

    public virtual void WriteResponseHeaders(OutputFormatterWriteContext context)
    {
        //這裏可以看出寫入的是輸出的ContentType
        var response = context.HttpContext.Response;
        response.ContentType = context.ContentType.Value ?? string.Empty;
    }
}

這裏我們只關注兩個核心方法CanWriteResult和WriteAsync方法，其中CanWriteResult方法判斷當前輸出是否滿足定義的OutputFormatter中設定的媒體類型，比如YamlOutputFormatter中設置的SupportedMediaTypes和設置的響應ContentType是否滿足匹配關係，如果顯示的指明瞭輸出頭是否滿足text/yaml或text/yml才能執行YamlOutputFormatter中的WriteResponseBodyAsync方法。一旦滿足CanWriteResult方法則會去調用WriteAsync方法。我們可以看到OutputFormatter類實現了IOutputFormatter接口，它的定義如下所示

public interface IOutputFormatter
{
    bool CanWriteResult(OutputFormatterCanWriteContext context);
    Task WriteAsync(OutputFormatterWriteContext context);
}

一目瞭然，IOutputFormatter接口暴露了CanWriteResult和WriteAsync兩個能力。咱們上面已經解釋了這兩個方法的用途，在這裏就不再贅述了。我們知道使用IOutputFormatter的地方，在ObjectResultExecutor類中，ObjectResultExecutor類則是在ObjectResult類中被調用，我們看一下ObjectResult調用ObjectResultExecutor的地方

public class ObjectResult : ActionResult, IStatusCodeActionResult
{
    public override Task ExecuteResultAsync(ActionContext context)
    {
        var executor = context.HttpContext.RequestServices.GetRequiredService<IActionResultExecutor<ObjectResult>>();
        return executor.ExecuteAsync(context, this);
    }
}

上面代碼中獲取的IActionResultExecutor<ObjectResult>實例正是ObjectResultExecutor實例，這個可以在MvcCoreServiceCollectionExtensions類中可以看到[點擊查看MvcCoreServiceCollectionExtensions源碼👈]

services.TryAddSingleton<IActionResultExecutor<ObjectResult>, ObjectResultExecutor>();

好了，回到整體，我們看一下ObjectResultExecutor的定義[點擊查看ObjectResultExecutor源碼👈]

public partial class ObjectResultExecutor : IActionResultExecutor<ObjectResult>
{
    public ObjectResultExecutor(OutputFormatterSelector formatterSelector)
    {
        FormatterSelector = formatterSelector;
    }

    //ObjectResult方法中調用的是該方法
    public virtual Task ExecuteAsync(ActionContext context, ObjectResult result)
    {
        var objectType = result.DeclaredType;
        //獲取返回對象類型
        if (objectType == null || objectType == typeof(object))
        {
            objectType = result.Value?.GetType();
        }

        var value = result.Value;
        return ExecuteAsyncCore(context, result, objectType, value);
    }

    private Task ExecuteAsyncCore(ActionContext context, ObjectResult result, Type? objectType, object? value)
    {
        //組裝OutputFormatterWriteContext，objectType爲當前返回對象類型，value爲返回對象的值
        var formatterContext = new OutputFormatterWriteContext(
            context.HttpContext,
            WriterFactory,
            objectType,
            value);
        
        //獲取符合當前請求輸出處理程序IOutputFormatter,並傳遞了ObjectResult的ContentTypes值
        var selectedFormatter = FormatterSelector.SelectFormatter(
            formatterContext,
            (IList<IOutputFormatter>)result.Formatters ?? Array.Empty<IOutputFormatter>(),
            result.ContentTypes);

        //省略部分代碼

        //調用IOutputFormatter的WriteAsync的方法
        return selectedFormatter.WriteAsync(formatterContext);
    }
}

上面的代碼我們可以看到在ObjectResultExecutor類中，通過OutputFormatterSelector的SelectFormatter方法來選擇使用哪個IOutputFormatter實例，需要注意的是調用SelectFormatter方法的時候傳遞的ContentTypes值是來自ObjectResult對象的ContentTypes屬性，也就是我們在設置ObjectResult對象的時候可以傳遞的輸出的Content-Type值。選擇完成之後在調用具體實例的WriteAsync方法。我們來看一下OutputFormatterSelector實現類的SelectFormatter方法如何實現的，在OutputFormatterSelector的默認實現類DefaultOutputFormatterSelector中[點擊查看DefaultOutputFormatterSelector源碼👈]

public partial class DefaultOutputFormatterSelector : OutputFormatterSelector
{
    public override IOutputFormatter? SelectFormatter(OutputFormatterCanWriteContext context, IList<IOutputFormatter> formatters, MediaTypeCollection contentTypes)
    {
        //省略部分代碼

        var request = context.HttpContext.Request;
        //獲取請求頭Accept的值
        var acceptableMediaTypes = GetAcceptableMediaTypes(request);
        var selectFormatterWithoutRegardingAcceptHeader = false;

        IOutputFormatter? selectedFormatter = null;
        if (acceptableMediaTypes.Count == 0)
        {
            //如果請求頭Accept沒設置值
            selectFormatterWithoutRegardingAcceptHeader = true;
        }
        else
        {
            if (contentTypes.Count == 0)
            {
                //如果ObjectResult沒設置ContentTypes則走這個邏輯
                selectedFormatter = SelectFormatterUsingSortedAcceptHeaders(
                    context,
                    formatters,
                    acceptableMediaTypes);
            }
            else
            {
                //如果ObjectResult設置了ContentTypes則走這個邏輯
                selectedFormatter = SelectFormatterUsingSortedAcceptHeadersAndContentTypes(
                    context,
                    formatters,
                    acceptableMediaTypes,
                    contentTypes);
            }

            //如果通過ObjectResult的ContentTypes沒選擇出來IOutputFormatter這設置該值
            if (selectedFormatter == null)
            {
                if (!_returnHttpNotAcceptable)
                {
                    selectFormatterWithoutRegardingAcceptHeader = true;
                }
            }
        }

        if (selectFormatterWithoutRegardingAcceptHeader)
        {
            if (contentTypes.Count == 0)
            {
                selectedFormatter = SelectFormatterNotUsingContentType(context, formatters);
            }
            else
            {
                selectedFormatter = SelectFormatterUsingAnyAcceptableContentType(context, formatters, contentTypes);
            }
        }

        return selectedFormatter;
    }

    private List<MediaTypeSegmentWithQuality> GetAcceptableMediaTypes(HttpRequest request)
    {
        var result = new List<MediaTypeSegmentWithQuality>();
        //獲取請求頭裏的Accept的值，因爲Accept的值可能有多個，也就是用;分割的情況
        AcceptHeaderParser.ParseAcceptHeader(request.Headers.Accept, result);
        for (var i = 0; i < result.Count; i++)
        {
            var mediaType = new MediaType(result[i].MediaType);
            if (!_respectBrowserAcceptHeader && mediaType.MatchesAllSubTypes && mediaType.MatchesAllTypes)
            {
                result.Clear();
                return result;
            }
        }

        result.Sort(_sortFunction);
        return result;
    }
}

上面的SelectFormatter方法就是通過各種條件判斷來選擇符合要求的IOutputFormatter實例，這裏依次出現了幾個方法，用來可以根據不同條件選擇IOutputFormatter，接下來我們根據出現的順序來解釋一下這幾個方法的邏輯，首先是SelectFormatterUsingSortedAcceptHeaders方法

private static IOutputFormatter? SelectFormatterUsingSortedAcceptHeaders(
        OutputFormatterCanWriteContext formatterContext,
        IList<IOutputFormatter> formatters,
        IList<MediaTypeSegmentWithQuality> sortedAcceptHeaders)
{
    for (var i = 0; i < sortedAcceptHeaders.Count; i++)
    {
        var mediaType = sortedAcceptHeaders[i];
        //把Request的Accept值設置給Response的ContentT-ype
        formatterContext.ContentType = mediaType.MediaType;
        formatterContext.ContentTypeIsServerDefined = false;

        for (var j = 0; j < formatters.Count; j++)
        {
            var formatter = formatters[j];
            if (formatter.CanWriteResult(formatterContext))
            {
                return formatter;
            }
        }
    }

    return null;
}

這個方法是通過請求頭的Accept值來選擇滿足條件的IOutputFormatter實例。還記得上面的OutputFormatter類中的CanWriteResult方法嗎就是根據ContentType判斷是否符合條件，使用的就是這裏的Request的Accept值。第二個出現的選擇方法則是SelectFormatterUsingSortedAcceptHeadersAndContentTypes方法

private static IOutputFormatter? SelectFormatterUsingSortedAcceptHeadersAndContentTypes(
    OutputFormatterCanWriteContext formatterContext,
    IList<IOutputFormatter> formatters,
    IList<MediaTypeSegmentWithQuality> sortedAcceptableContentTypes,
    MediaTypeCollection possibleOutputContentTypes)
{
    for (var i = 0; i < sortedAcceptableContentTypes.Count; i++)
    {
        var acceptableContentType = new MediaType(sortedAcceptableContentTypes[i].MediaType);
        for (var j = 0; j < possibleOutputContentTypes.Count; j++)
        {
            var candidateContentType = new MediaType(possibleOutputContentTypes[j]);
            if (candidateContentType.IsSubsetOf(acceptableContentType))
            {
                for (var k = 0; k < formatters.Count; k++)
                {
                    var formatter = formatters[k];
                    formatterContext.ContentType = new StringSegment(possibleOutputContentTypes[j]);
                    formatterContext.ContentTypeIsServerDefined = true;
                    if (formatter.CanWriteResult(formatterContext))
                    {
                        return formatter;
                    }
                }
            }
        }
    }

    return null;
}

這個方法是通過ObjectResult設置了ContentTypes去匹配選擇滿足條件請求頭的Accept值來選擇IOutputFormatter實例。第三個出現的則是SelectFormatterNotUsingContentType方法

private IOutputFormatter? SelectFormatterNotUsingContentType(
    OutputFormatterCanWriteContext formatterContext,
    IList<IOutputFormatter> formatters)
{
    foreach (var formatter in formatters)
    {
        formatterContext.ContentType = new StringSegment();
        formatterContext.ContentTypeIsServerDefined = false;

        if (formatter.CanWriteResult(formatterContext))
        {
            return formatter;
        }
    }

    return null;
}

這個方法是選擇第一個滿足條件的IOutputFormatter實例。還記得上面定義YamlOutputFormatter類的時候重寫了CanWriteResult方法嗎？就是爲了杜絕被默認選中的情況，重寫了CanWriteResult方法，裏面添加了驗證邏輯就不會被默認選中。

private static IOutputFormatter? SelectFormatterUsingAnyAcceptableContentType(
        OutputFormatterCanWriteContext formatterContext,
        IList<IOutputFormatter> formatters,
        MediaTypeCollection acceptableContentTypes)
{
    foreach (var formatter in formatters)
    {
        foreach (var contentType in acceptableContentTypes)
        {
            formatterContext.ContentType = new StringSegment(contentType);
            formatterContext.ContentTypeIsServerDefined = true;

            if (formatter.CanWriteResult(formatterContext))
            {
                return formatter;
            }
        }
    }

    return null;
}

這個方法說的比較簡單，就是通過ObjectResult設置了ContentTypes去匹配選擇滿足條件的IOutputFormatter實例。

到這裏相信大家對關於TextOutputFormatter是如何工作的有了大致的瞭解，本質就是在ObjectResultExecutor類中選擇合適的滿足條件的IOutputFormatter實例。我們在Action中返回POCO對象、ActionResult<Type>、OkObjectResult等本質都是返回的ObjectResult類型。

小結

相信通過這一小節對TextInputFormatter和TextOutputFormatter源碼的分析，和它們是如何工作的進行了大致的講解。其實如果理解了源碼，總結起來也很簡單

模型綁定類中BodyModelBinder調用了InputFormatter實例來進行對指定請求的內容進行格式轉換，綁定到模型參數上的，
ObjectResult類的執行類ObjectResultExecutor類中通過調用滿足條件OutputFormatter實例，來決定把模型輸出成那種類型的數據格式，但是需要注意重寫CanWriteResult方法防止被作爲默認程序輸出。

控制了模型綁定和輸出對象轉換，我們也就可以直接控制請求數據和輸出數據的格式控制了。當然想更好的瞭解更多的細節，解惑心中疑問，還是得閱讀和調試具體的源碼。

總結

本篇文章我們通過演示示例和講解源碼的方式瞭解了ASP.NET Core WebAPI中的格式化程序，知道結構的話瞭解它其實並不難，只是其中的細節比較多，需要慢慢梳理。涉及到的源碼比較多，可以把本文當做一個簡單的教程來看。寫文章既是把自己對事物的看法分享出來，也是把自己的感悟記錄下來方便翻閱。我個人很喜歡閱讀源碼，通過開始閱讀源碼感覺自己的水平有了很大的提升，閱讀源碼與其說是一個行爲不如說是一種意識。明顯的好處，一個是爲了讓自己對這些理解更透徹，閱讀過程中可以引發很多的思考。二是通過源碼可以解決很多實際的問題，畢竟大家都這麼說源碼之下無祕密。

👇歡迎掃碼關注我的公衆號👇

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

前言

自定義開始

YamlInputFormatter

YamlOutputFormatter

小結

探究工作方式

TextInputFormatter如何工作

TextOutputFormatter如何工作

小結

相關資料

總結

體驗Semantic Kernel圖片內容識別

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

基於C# Socket實現的簡單的Redis客戶端

細聊C# AsyncLocal如何在異步間進行數據流轉

由C# yield return引發的思考

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結