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

前些時日，老周在升級“華南閑腎回收登記平台”時，為了擴充業務，尤其是允許其他開發人員在其他平台向本系統提交有關腎的介紹資料，於是就為該系統增加了幾個 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}";        }    }

FromBody 特性千萬要記得用上，不然待會讀不了你又要到處 Debug 了。

 

好，測試開始了，首先試一下 DateTime 類型的。

 

再試一下 int 類型的。

 

感覺如何，好刺激吧。好啦，今天的高大上技巧就分享到這兒了。

樣本原始碼下載：請用洪荒之力猛點這裡