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的设计要求

相关推荐
网络研究院10 小时前
新的“MadeYouReset”方法利用 HTTP/2 进行隐秘的 DoS 攻击
网络·网络协议·安全·http·攻击·漏洞
玩转以太网20 小时前
基于W55MH32Q-EVB 实现 HTTP 服务器配置 OLED 滚动显示信息
服务器·网络协议·http
清源妙木真菌21 小时前
应用层协议——HTTP
网络·网络协议·http
一枚小小程序员哈1 天前
基于微信小程序的家教服务平台的设计与实现/基于asp.net/c#的家教服务平台/基于asp.net/c#的家教管理系统
后端·c#·asp.net
AliciaIr1 天前
深入理解HTTP:从协议基础到版本演进(上)
前端·http
今禾1 天前
深入解析HTTP协议:从OSI模型到HTTP/3.0的演进与实战优化
前端·http·面试
FreeBuf_2 天前
CERT/CC警告:新型HTTP/2漏洞“MadeYouReset“恐致全球服务器遭DDoS攻击瘫痪
服务器·http·ddos
做一位快乐的码农2 天前
基于.net、C#、asp.net、vs的保护大自然网站的设计与实现
c#·asp.net·.net
Mr_Xuhhh2 天前
传输层协议TCP(3)
运维·服务器·网络·网络协议·tcp/ip·http·https
lsnm2 天前
【LINUX网络】HTTP协议基本结构、搭建自己的HTTP简单服务器
linux·运维·服务器·c语言·网络·c++·http