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. 示例

    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 客户端错误

  1. 示例

    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 服务器错误

  1. 示例

    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)其他特殊状态码

  1. 示例

    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

  1. 示例

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

2)统一错误处理(Problem Details)

  1. 示例

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

3)自定义状态码结果

  1. 示例

    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();

四、最佳实践建议

优先使用内置方法

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

POST创建资源时返回201

  1. 必须包含Location 头指向新资源(通过CreatedAtActionCreatedAtRoute)。

模型验证统一处理

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

异步方法一致处理

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

生产环境隐藏敏感错误

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

总结

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

相关推荐
橘猫云计算机设计7 小时前
ASP.NET图书馆借阅系统(源码+lw+部署文档+讲解),源码可白嫖!
java·数据库·后端·爬虫·小程序·毕业设计·asp.net
xzkyd outpaper11 小时前
HTTPS和HTTP有哪些区别?
网络·网络协议·计算机网络·http·计算机八股
星星跌入梦境*11 小时前
前端面试题(六):HTTP和HTTPS的区别以及他们如何保障数据安全
网络协议·http·https
星星跌入梦境*15 小时前
HTTP GET 和 POST 请求有什么区别
网络·网络协议·http
写bug写bug17 小时前
掌握 HTTP 状态码
前端·后端·http
BillKu19 小时前
本地项目HTTPS访问问题解决方案
网络协议·http·https
时光追逐者21 小时前
C#/.NET/.NET Core技术前沿周刊 | 第 33 期(2025年4.1-4.6)
c#·.net·.netcore
菜鸟康21 小时前
Linux网络编程——https的协议及其加密解密方式
网络·网络协议·http
Aa美少女战士2 天前
多域名 SSL 证书能保护多少个域名?
网络协议·http·https
栩栩云生2 天前
📥 x-cmd install | Slumber - 告别繁琐,拥抱高效的终端 HTTP 客户端
前端·后端·http