2024-10-22 012_學寫API_HTTP 響應

2024-10-22 012_學寫API_HTTP 響應

在 ASP.NET Core 中，控制器類（通常繼承自 ControllerBase 或 Controller）提供了許多輔助方法來生成各種 HTTP 響應。這些響應方法幫助開發者更方便地處理客戶端請求並返回合適的 HTTP 狀態碼和數據。以下是 ASP.NET Core 中常用的響應方法：

1. 成功響應方法

這些方法用於表示請求成功，返回相應的數據或狀態。

• **Ok()**：

  • 返回狀態碼 200 OK，表示請求成功。
  • 用法：

    return Ok(); // 返回 200 OK
    return Ok(data); // 返回 200 OK 並附帶 data 作為響應體

• **Created()**：

  • 返回狀態碼 201 Created，表示創建資源成功。
  • 需要提供資源的 URI 和新創建的對象。
  • 用法：

    return Created("/api/packages/123", newPackage);

• **CreatedAtAction()**：

  • 返回狀態碼 201 Created，並指定創建的資源的 URI，這個 URI 由控制器中的某個操作生成。
  • 用法：

    return CreatedAtAction(nameof(GetPackageById), new { id = newPackage.Id }, newPackage);

• **CreatedAtRoute()**：

  • 返回狀態碼 201 Created，並基於指定的路由創建資源的 URI。
  • 用法：

    return CreatedAtRoute("GetPackageRoute", new { id = newPackage.Id }, newPackage);

• **NoContent()**：

  • 返回狀態碼 204 No Content，表示請求成功，但沒有內容需要返回，通常用於 PUT 或 DELETE 請求。
  • 用法：

    return NoContent();

2. 重定向響應方法

這些方法用於將請求重定向到其他 URL。

• **Redirect()**：

  • 返回狀態碼 302 Found，並重定向到指定的 URL。
  • 用法：

    return Redirect("https://example.com");

• **RedirectPermanent()**：

  • 返回狀態碼 301 Moved Permanently，並永久重定向到指定的 URL。
  • 用法：

    return RedirectPermanent("https://example.com");

• **RedirectToAction()**：

  • 重定向到控制器中的指定操作。
  • 用法：

    return RedirectToAction("ActionName", "ControllerName");

• **RedirectToRoute()**：

  • 重定向到指定的路由。
  • 用法：

    return RedirectToRoute("RouteName");

3. 客戶端錯誤響應方法

這些方法用於表示客戶端的請求不正確。

• **BadRequest()**：

  • 返回狀態碼 400 Bad Request，表示客戶端的請求有誤。
  • 用法：

    return BadRequest(); // 返回 400
    return BadRequest("請求格式錯誤"); // 返回 400 並附帶錯誤消息

• **Unauthorized()**：

  • 返回狀態碼 401 Unauthorized，表示請求需要授權，但客戶端未提供有效憑證。
  • 用法：

    return Unauthorized();

• **Forbidden()**：

  • 返回狀態碼 403 Forbidden，表示客戶端已經認證，但沒有訪問資源的權限。
  • 用法：

    return Forbid();

• **NotFound()**：

  • 返回狀態碼 404 Not Found，表示找不到請求的資源。
  • 用法：

    return NotFound();
    return NotFound("找不到這個包裹");

4. 服務端錯誤響應方法

這些方法用於表示服務端發生錯誤。

• **StatusCode()**：

  • 返回指定的 HTTP 狀態碼，這可以用來返回一些自定義的狀態碼。
  • 用法：

    return StatusCode(500, "服務器內部錯誤");

• **Problem()**：

  • 返回一個標準化的錯誤響應，通常用於表示服務器錯誤，並可選擇提供詳細錯誤信息。
  • 用法：

    return Problem("服務器遇到問題，請稍後重試");

5. JSON 和文件響應方法

• **Json()**：

  • 返回 JSON 格式的數據。
  • 用法：

    return Json(new { name = "Alice", age = 25 });

• **File()**：

  • 返回文件作為響應。
  • 用法：

    return File(fileBytes, "application/pdf", "document.pdf");

6. 其他響應方法

• **Content()**：

  • 返回一個包含文本的 HTTP 響應，通常用於返回簡單的文本或 HTML。
  • 用法：

    return Content("這是一個簡單的響應內容");

• **PhysicalFile()**：

  • 返回一個物理文件作為響應。
  • 用法：

    return PhysicalFile(@"C:\files\document.pdf", "application/pdf");

• **LocalRedirect()**：

  • 返回一個本地重定向。
  • 用法：

    return LocalRedirect("/home/index");

小結

ASP.NET Core 提供了豐富的響應方法來生成各種 HTTP 響應，這些方法可以使開發者更加方便地構建 API，處理不同的客戶端請求情況，並返回合適的狀態碼和數據。

• 成功響應（如 Ok()、Created()、NoContent()）通常用於表示操作成功。
• 錯誤響應（如 BadRequest()、NotFound()、Unauthorized()）用於告知客戶端請求有問題。
• 重定向響應（如 Redirect()、RedirectToAction()）用於將請求重定向到其他資源。

如果您有其他想了解的響應方法或對某些方法有疑問，隨時告訴我！