【ASP.NET Core】從向 Web API 提交純文本內容談起

前些時日，老周在升級“華南閑腎回收登記平臺”時，為了擴展業務，尤其是允許其他開發人員在其他平臺向本系統提交有關腎的介紹資料，於是就為該系統增加了幾個 Web API。其中，有關腎的介紹採用純文本方式提交，大概的代碼是這樣的。這個 Action 很簡單（主要為了方便別人看懂），參數接受一個字元串實 ...

前些時日，老周在升級“華南閑腎回收登記平臺”時，為了擴展業務，尤其是允許其他開發人員在其他平臺向本系統提交有關腎的介紹資料，於是就為該系統增加了幾個 Web API。

其中，有關腎的介紹採用純文本方式提交，大概的代碼是這樣的。

    [Route("api/[controller]/[action]")]
    public class PigController : Controller
    {
        [HttpPost]
        public string KidneyRemarks([FromBody]string remarks)
        {
            return $"根據你的描述，貴腎的當前狀態為：{remarks}";
        }
    }

這個 Action 很簡單（主要為了方便別人看懂），參數接受一個字元串實例，返回的也是字元串。哦，重點要記住，對參數要加上 FromBody 特性。嗯，為啥呢。因為我們要得到的數據是從客戶端發來的 HTTP 正文提取的，應用這個特性就是說參數的值來自於提交的正文，而不是 Header，也不是 url 參數。

隨後老周興高采烈地用 Postman 進行測試。

幻想總是很美麗的，現實總是很骨感的。結果……

沒成功，這時候，按照常規思路，會產生各種懷疑。懷疑地址錯了嗎？哪個配置沒寫上？是不是路由不正確？……

別急，看看伺服器返回的狀態碼：415 Unsupported Media Type。啥意思呢，其實，這就是問題所在了。我們提交純文本類型的數據，用的 Content-Type 是 text/plain，可是，不受支持！

不信？現在把提交的內容改為 JSON 看看。

看看，我沒說錯吧。

這就很明瞭啦，JSON 預設是被支持的，但是純文本不行。有辦法讓它支持 text / plain 類型的數據嗎？答案是：能的。

在 Startup 中使用 ConfigureServices 方法配置服務時，我們一般就是簡單地寫上。

   services.AddMvc();

然後，各個 MVC 選項保持預設。

在 MVC 選項中，可以控制輸入和輸出的格式，分別由兩個屬性來管理：

InputFormatters 屬性：是一個集合，裡面的每個對象都要實現 IInputFormatter 介面，預設提供對 JSON 和 XML 的支持。

OutputFormatters 屬性：也是一個集合，裡面的元素都要實現 IOutputFormatter 介面，預設支持 JSON 和 XML，也支持文本類型。

也就是說，輸出是支持純文本的，所以 Action 可以返回 string 類型的值，但輸入是不支持文本格式的，所以，用 text / plain 格式提交，就會得到 415 代碼了。

明白了這個原理，解決起問題來就好辦了，咱們自己實現一個支持純文本格式的 InputFormatter 就行了。不過呢，我們也不必直接實現 IInputFormatter 介面，因為，有個抽象類挺好使的—— TextInputFormatter，處理文本直接實現它就好了。

於是乎，老周就寫了這個類。

    public sealed class PlainTextInputFormatter : TextInputFormatter
    {
        public override async Task<InputFormatterResult> ReadRequestBodyAsync(InputFormatterContext context, Encoding encoding)
        {
            string content;
            using(var reader = context.ReaderFactory(context.HttpContext.Request.Body, encoding))
            {
                content = await reader.ReadToEndAsync();
            }
            // 最後一步別忘了
            return await InputFormatterResult.SuccessAsync(content);
        }
    }

TextInputFormatter 類只有 ReadRequestBodyAsync 方法是抽象的，所以，如果沒其他活要乾的話，只實現這個方法就夠了。這個方法的功能就是讀取 HTTP 請求的正文，然後把你讀取到的內容填充給 InputFormatterResult 對象。

InputFormatterResult 類很有意思的，沒有公共構造函數，你無法 new 對象，只能靠媒人介紹對象，通過 Failure、Success 這些方法直接返回對象實例。這些方法你看名字就知道什麼用途了，不用多解釋。

在上面代碼中，ReaderFactory 屬性其實是個委托，通過構造函數創建的，不過，這個委托實例在傳進 ReadRequestBodyAsync 方法時已經創建，你只需要像調用方法一樣調用它就行了，第一個參數是一個流，哪裡的流？當然是 HTTP 請求的正文了，這裡可以透過 HttpContext 的 Request 的 Body 來獲得；第二個參數嘛，呵呵，是文本編碼，這個好辦，直接把傳進 ReadRequestBodyAsync 方法的 encoding 傳過去就行了。

ReaderFactory 委托調用後返回一個 TextReader，是了，我們就是用它來讀取請求正文的。最後把讀出來的字元串填充給 InputFormatterResult 就行了。

不過呢，這個類現在還不能用，因為預設情況下，SupportedMediaTypes 集合是空的，你得添加一下，它支持哪些 Content-Type，我們這裡只要 text / plain 就行了。

        public PlainTextInputFormatter()
        {
            SupportedMediaTypes.Add("text/plain");
            SupportedEncodings.Add(System.Text.Encoding.UTF8);
        }

這些寫在構造函數里就 OK 了。註意 SupportedEncodings 集合，是配置字元編碼，一般嘛，UTF-8 最合適了。你也可以從 TextInputFormatter 類的兩個只讀的靜態欄位中獲取。

protected static readonly Encoding UTF8EncodingWithoutBOM;
protected static readonly Encoding UTF16EncodingLittleEndian;

現在基本可以用了。因為我們上面寫的那個 Action 是帶字元串類型參數的，如果你覺得不放心，可以覆寫一下 CanReadType 方法，這個方法有個 type 參數，指的是 Model Type，說白了就是 Action 要接收的參數的類型，咱們這裡是 string，所以，實現這個方法很簡單，如果是字元串類型就返回 true，表示能讀取，否則返回 false，表示不能讀。

回到 Startup 類，找到 ConfigureServices 方法，我們在 AddMvc 的時候要對 Options 配置一下，把咱們剛剛寫好的 InputFormatter 加進去。

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc(opt =>
            {
                opt.InputFormatters.Add(new PlainTextInputFormatter());
            });
        }

好了，現在再請 Postman 大叔，重新測試一下。

嗯，皆大歡喜，又解決一個問題了。

我們不妨繼續擴展一下，如果提交的是 text / plain 數據內容，而 Action 想讓其賦值給 DateTime 或者 int 類型的參數呢。其實也一樣，就是自己實現一下輸入格式。這一次我們不繼承 TextInputFormatter 類了，而是繼承抽象程度更高的 InputFormatter 類。

    public sealed class CustInputFormatter : InputFormatter
    {
        public CustInputFormatter()
        {
            SupportedMediaTypes.Add("text/plain");
        }

        protected override bool CanReadType(Type type)
        {
            return (type == typeof(DateTime)) || (type == typeof(int));
        }

        public override async Task<InputFormatterResult> ReadRequestBodyAsync(InputFormatterContext context)
        {
            string val;
            using (var reader = context.ReaderFactory(context.HttpContext.Request.Body, Encoding.UTF8))
            {
                val = await reader.ReadToEndAsync();
            }
            InputFormatterResult result = null;
            if(context.ModelType == typeof(DateTime))
            {
                result = InputFormatterResult.Success(DateTime.Parse(val));
            }
            else
            {
                result = InputFormatterResult.Success(int.Parse(val));
            }
            return result;
        }
    }

這一次應該不用我解釋，你都能看懂了。不過註意一點，因為要應用的目標參數可能是 int 和 DateTime 類型，所以，在填充 InputFormatterResult 對象時，你要先檢查一下 ModelType 屬性。

            if(context.ModelType == typeof(DateTime))
            {
                result = InputFormatterResult.Success(DateTime.Parse(val));
            }
            else
            {
                result = InputFormatterResult.Success(int.Parse(val));
            }

現在應用一下這個輸入格式類。

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc(o =>
            {
                o.InputFormatters.Add(new CustInputFormatter());
            });
        }

下麵來試試吧，建一個 Controller，然後定義兩個 Action，一個接收 int 類型的參數，一個接收 DateTime 類型的參數。

    [Route("[controller]/[action]")]
    public class TestController : Controller
    {
        [HttpPost]
        public string Upload([FromBody]DateTime dt)
        {
            return $"你提交的時間是：{dt}";
        }

        [HttpPost]
        public string UploadInt([FromBody]int val)
        {
            return $"你提交的整數值是：{val}";
        }
    }