使用 ASP.NET Core MVC 创建 Web API（四） - 好文

使用 ASP.NET Core MVC 创建 Web API

使用 ASP.NET Core MVC 创建 Web API（一）
<https://www.cnblogs.com/chillsrc/p/10614598.html>

使用 ASP.NET Core MVC 创建 Web API（二）
<https://www.cnblogs.com/chillsrc/p/10649898.html>

使用 ASP.NET Core MVC 创建 Web API（三）
<https://www.cnblogs.com/chillsrc/p/10697463.html>

十三、返回值

      在上一篇文章（使用 ASP.NET Core MVC 创建 Web API（二）
<https://www.cnblogs.com/chillsrc/p/10649898.html>）中我们创建了GetBookItems和
GetBookItem两个方法，这两个方法的返回类型是 ActionResult<T> 类型。 ASP.NET Core 自动将对象序列化为 JSON，并将
JSON 写入响应消息的正文中。 GetBookItems和
GetBookItem方法正确执行，没有未经处理的异常的情况下，返回类型的响应代码为200。如果有未经处理的异常返回的响应代码为5xx。

    一些操作方法的结果返回类型会是特殊格式，例如 JsonResult 和 ContentResult
。操作可以返回始终以特定方式进行格式设置的特定结果。例如，返回JsonResult 将返回 JSON 格式的数据，而不考虑客户端首选项。同样，返回
ContentResult 将返回纯文本格式的字符串数据（仅返回字符串也是如此）。

    ActionResult 返回类型可以表示大范围的 HTTP状态代码。例如，   在上一篇文章（使用 ASP.NET Core MVC 创建 Web
API（二） <https://www.cnblogs.com/chillsrc/p/10649898.html>）
我们创建的GetBookItem方法可以返回两个不同的状态值，如下：

    1) 如果没有数据库中没有存在与请求 ID相匹配的书籍信息，则该方法将返回 404 NotFound 错误代码。如下图。

    2)如果数据库中存在与请求ID相匹配的书籍信息，则此方法将返回 JSON格式数据的响应正文，并且产生 HTTP 200 响应。如下图。

一）特定类型

    在应用程序中我们对于操作方法的返回值最简单做法是返回.NET简单类型或复杂数据类型（如 string
或自定义对象类型）。请参考以下代码，该操作方法返回自定义Book 对象的集合：

public Book GetBook(int id) { var bookItem = _context.Book.Find(id); return
bookItem; }
    1）在执行操作方法期间无需考虑已知条件时，返回特定类型即可满足要求。

     2）当在操作方法执行期间需要考虑已知条件时，可能会有多个结果类型需要返回。在这种情况下，通常会将返回类型设为ActionResult或
ActionResult<T>，这样就可以返回基本简单类型或复杂返类型。

    二)IActionResult 类型

    当操作方法存在多个 ActionResult 需要返回时，适合使用 IActionResult 返回类型。 ActionResult 类型表示多种
HTTP 状态代码。属于此类别的一些常见返回类型包括：BadRequestResult (400)、NotFoundResult (404) 和
OkObjectResult (200)。

    由于操作中有多个返回类型和路径，因此可以使用 [ProducesResponseType] 特性。此特性方便 Swagger 等工具生成的 API
帮助页生成更多描述性响应详细信息。[ProducesResponseType] 指示操作将返回的已知类型和 HTTP 状态代码。如下面的示例：
[HttpGet("{id}")] [ProducesResponseType(typeof(Book),
StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status404NotFound)]
public async IActionResult GetBookById(int id) { var bookItem = await
_context.Book.FindAsync(id);if (bookItem == null) { return NotFound(); } return
Ok(bookItem); }
    在上面的代码中，当与id相匹配的书籍不存在数据库中时，则返回 404 状态代码。调用 NotFound 帮助程序方法作为 return new
NotFoundResult(); 的快捷方式。如果书籍信息存在数据库中，则返回代表有效负载的 bookItem对象和状态代码 200。调用 Ok
帮助程序方法作为return new OkObjectResult(bookItem); 的快捷方式。

三）ActionResult<T> 类型

      ASP.NET Core 2.1 引入了面向 Web API 控制器操作的 ActionResult<T> 返回类型。它支持返回从
ActionResult 派生的类型或返回特定类型。ActionResult<T> 通过 IActionResult 类型可提供以下优势：

    1) 可排除 [ProducesResponseType] 特性的 Type 属性。例如，[ProducesResponseType(200,
Type = typeof(Book))] 可简化为 [ProducesResponseType(200)]。此操作的预期返回类型改为根据
ActionResult<T> 中的 T 进行推断。

    2) 隐式强制转换运算符支持将 T 和 ActionResult 均转换为 ActionResult<T>。将 T 转换为
ObjectResult，也就是将return new ObjectResult(T); 简化为 return T;。

     C# 不支持对接口使用隐式强制转换运算符。因此，必须使用 ActionResult<T>，才能将接口转换为具体类型。例如，在下面的示例中，使用
IEnumerable 返回全部书籍信息：

[HttpGet] public async Task<ActionResult<IEnumerable<Book>>> GetBookItems() {
return await _context.Book.ToListAsync(); }


     大多数操作具有特定返回类型。执行操作期间可能出现意外情况，不返回特定类型就是其中之一。例如，操作的输入参数可能无法通过模型验证。
在此情况下，通常会返回相应的ActionResult 类型，而不是特定类型。

十四、添加新增方法

      接下来我们来实现一个新增方法，在WEB API中使用什么来实现新增方法呢？

      特性[HttpPost]指示这个方法接收HTTP POST方法请求传过来的数据，并从 HTTP 请求正文中获取书籍信息的值。

       在Visual Studio 2017中打开BookController.cs文件，在文件中添加以下 PostBookItem 方法：

// POST: api/Book [HttpPost] public async Task<ActionResult<Book>>
PostBookItem(Book item) { _context.Book.Add(item);await
_context.SaveChangesAsync();return CreatedAtAction(nameof(GetBookItem), new {
id = item.ID }, item); }
对于CreatedAtAction 方法的说明：

* 如果成功，则返回 HTTP 201 状态代码。 HTTP 201 是在服务器上创建新资源的 HTTP POST 方法的标准响应。
* 将 Location 标头添加到响应。 Location 标头指定新建的书籍信息的 URI。
* 引用 GetBookItem操作以创建 Location 标头的 URI。 C# nameof 关键字用于避免在 CreatedAtAction
调用中硬编码操作名称。

一）测试 PostBookItem 方法

    1) 在Visual Studio 2017中按F5，启动BookApi应用程序。

   2) 打开Firefox浏览器，并打开 Rester，在Reseter中，将 HTTP 方法设置为 POST。

     3) 选择“Headers”选项卡，选择“Content-Type”选项，并将值设置为 JSON (application/json)，如下图。

     4) 然后选择“BODY”选项卡，在请求正文中，输入我们想新增的书籍信息的 JSON，如下图：

    JSON字符串：

{"name":"Python编程实践","releaseDate":"2018-02-12","price":55.49,"author":"马瑟斯","publishing":"机械工业出版社"}
    5) 使用鼠标左键，单击“SEND”按钮。成功创建了一条新的书籍信息，返回响应为201。如下图。

      如果收到 500内部服务器错误，则检查代码与数据是否符合数据库要求，405 不允许的方法错误，则可能是由于未在添加 PostBookItem
方法之后编译项目。

二）测试位置标头 URI

      6) 在前文我们对代码进行过解释，成功创建新的书籍信息之后，响应返回中的Location 标头指向新建的书籍信息的
URI。接下来我们来测试一下，在“Response”窗格中复制“位置”标头值，如下图。

    7) 在Rester中把方法设置为“GET”。

    8) 在URL输入框中，粘贴刚才复制的 URI（例如，https://localhost:5000/api/Book/24），如下图。

     9) 选择“SEND”，我们会获取ID=24的书籍信息，就是我们刚才新增的书籍信息。如下图。

热门工具换一换