ASP.NET Core Web API 中 HTTP状态码的分类及对应的返回方法

---

前言

在ASP.NET Core Web API中，HTTP状态码用于表示请求的处理结果。

一、HTTP状态码分类及常用方法

类别	常见状态码	内置辅助方法	使用场景
信息响应	100	StatusCode(100)	协议切换请求
成功响应	200	Ok() / Ok(object)	标准GET请求成功
	201	CreatedAtAction() / CreatedAtRoute	资源创建成功（POST）
	202	Accepted()	请求已接受但未完成处理
	204	NoContent()	成功但无返回内容（DELETE常用）
重定向	301	RedirectPermanent()	永久重定向
	302	Redirect()	临时重定向
客户端错误	400	BadRequest()	请求参数无效
	401	Unauthorized()	未授权访问（未登录）
	403	Forbid()	已登录但权限不足
	404	NotFound()	资源不存在
	409	Conflict()	资源冲突（如重复创建）
	422	UnprocessableEntity()	请求语义正确但验证失败（常用于REST API）
服务器错误	500	StatusCode(500) / Problem()	未处理的服务器错误
	503	StatusCode(503)	服务不可用（维护或过载）

二、具体返回方法示例

1） 2xx 成功类

1. 示例

   // 200 OK（带数据）
   [HttpGet("{id}")]
   public ActionResult<Item> GetItem(int id)
   {
       var item = _repository.GetItem(id);
       return Ok(item); // 自动序列化对象为JSON
   }
   
   // 201 Created（创建资源）
   [HttpPost]
   public IActionResult CreateItem(Item item)
   {
       _repository.Add(item);
       return CreatedAtAction(nameof(GetItem), new { id = item.Id }, item);
   }
   
   // 204 No Content（删除成功）
   [HttpDelete("{id}")]
   public IActionResult DeleteItem(int id)
   {
       _repository.Delete(id);
       return NoContent();
   }
   

2）4xx 客户端错误

1. 示例

   // 400 Bad Request（手动验证）
   [HttpPost]
   public IActionResult PostItem(Item item)
   {
       if (item.Price <= 0)
       {
           return BadRequest("价格必须大于0");
       }
       return Ok();
   }
   
   // 401 Unauthorized（未授权）
   [HttpGet("secret")]
   public IActionResult GetSecret()
   {
       if (!User.Identity.IsAuthenticated)
       {
           return Unauthorized();
       }
       return Ok("机密数据");
   }
   
   // 422 Unprocessable Entity（验证失败）
   [HttpPost("validate")]
   public IActionResult ValidateItem(Item item)
   {
       if (!ModelState.IsValid)
       {
           return UnprocessableEntity(ModelState); // 返回详细错误
       }
       return Ok();
   }
   

3）5xx 服务器错误

1. 示例

   // 500 Internal Server Error（自定义错误）
   [HttpGet("error")]
   public IActionResult ThrowError()
   {
       try
       {
           throw new Exception("测试异常");
       }
       catch (Exception ex)
       {
           return Problem(
               title: "服务器错误",
               detail: ex.Message,
               statusCode: 500
           );
       }
   }
   
   // 503 Service Unavailable（服务不可用）
   [HttpGet("maintenance")]
   public IActionResult Maintenance()
   {
       return StatusCode(503, new { Message = "系统维护中，请稍后重试" });
   }
   

4）其他特殊状态码

1. 示例

   // 418 I'm a teapot（彩蛋状态码）
   [HttpGet("teapot")]
   public IActionResult Teapot() => StatusCode(418);
   
   // 429 Too Many Requests（限流）
   [HttpGet("limited")]
   public IActionResult LimitedRequest()
   {
       Response.Headers.Add("Retry-After", "60"); // 添加响应头
       return StatusCode(429);
   }
   

三、高级返回方式

1）使用 IActionResult 与 ActionResult

1. 示例

   // 动态返回类型
   [HttpGet("dynamic/{id}")]
   public ActionResult<Item> GetDynamic(int id)
   {
       var item = _repository.GetItem(id);
       return item != null ? item : NotFound();
   }
   

2）统一错误处理（Problem Details）

1. 示例

   // 返回RFC 7807标准错误格式
   [HttpGet("problem")]
   public IActionResult GetProblem()
   {
       return Problem(
           detail: "余额不足",
           instance: HttpContext.Request.Path,
           statusCode: 400,
           title: "支付失败"
       );
   }
   

3）自定义状态码结果

1. 示例

   // 继承ActionResult自定义返回
   public class CustomResult : ActionResult
   {
       public override void ExecuteResult(ActionContext context)
       {
           context.HttpContext.Response.StatusCode = 299;
           context.HttpContext.Response.WriteAsync("自定义状态码");
       }
   }
   
   // 使用自定义结果
   [HttpGet("custom")]
   public IActionResult GetCustom() => new CustomResult();
   

四、最佳实践建议

优先使用内置方法

1. Ok()、NotFound() 等方法更易读且自动处理序列化。

POST创建资源时返回201

1. 必须包含Location头指向新资源（通过CreatedAtAction或CreatedAtRoute）。

模型验证统一处理

1. 使用 [ApiController] 特性时，无效模型自动返回400错误。

异步方法一致处理

1. 异步方法返回Task<IActionResult>，用法与同步方法一致。

生产环境隐藏敏感错误

1. 通过中间件（如UseExceptionHandler）统一处理500错误，避免泄露堆栈信息。

总结

通过适配的方法，可以清晰、规范地在ASP.NET Core Web API中返回各类HTTP状态码，满足RESTful API的设计要求