文章目录
- 前言
- 一、HTTP状态码分类及常用方法
- 二、具体返回方法示例
- [1) 2xx 成功类](#1) 2xx 成功类)
-
- [2)4xx 客户端错误](#2)4xx 客户端错误)
- [3)5xx 服务器错误](#3)5xx 服务器错误)
- 4)其他特殊状态码
- 三、高级返回方式
-
- [1)使用 IActionResult 与 ActionResult<T>](#1)使用 IActionResult 与 ActionResult<T>)
- [2)统一错误处理(Problem Details)](#2)统一错误处理(Problem Details))
- 3)自定义状态码结果
- 四、最佳实践建议
- 总结
前言
在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 成功类
-
示例
csharp// 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 客户端错误
-
示例
csharp// 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 服务器错误
-
示例
csharp// 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)其他特殊状态码
-
示例
csharp// 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
-
示例
csharp// 动态返回类型 [HttpGet("dynamic/{id}")] public ActionResult<Item> GetDynamic(int id) { var item = _repository.GetItem(id); return item != null ? item : NotFound(); }
2)统一错误处理(Problem Details)
-
示例
csharp// 返回RFC 7807标准错误格式 [HttpGet("problem")] public IActionResult GetProblem() { return Problem( detail: "余额不足", instance: HttpContext.Request.Path, statusCode: 400, title: "支付失败" ); }
3)自定义状态码结果
-
示例
csharp// 继承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();
四、最佳实践建议
优先使用内置方法
- Ok()、NotFound() 等方法更易读且自动处理序列化。
POST创建资源时返回201
- 必须包含Location 头指向新资源(通过CreatedAtAction 或CreatedAtRoute)。
模型验证统一处理
- 使用 [ApiController] 特性时,无效模型自动返回400错误。
异步方法一致处理
- 异步方法返回Task <IActionResult>,用法与同步方法一致。
生产环境隐藏敏感错误
- 通过中间件(如UseExceptionHandler )统一处理500错误,避免泄露堆栈信息。
总结
通过适配的方法,可以清晰、规范地在ASP.NET Core Web API 中返回各类HTTP 状态码,满足RESTful API的设计要求