如何在ASP.NET Core ApiController中返回404状态码及JSON格式错误信息

要实现你想要的效果，直接通过ApiController结合自定义错误模型就能搞定，步骤如下：

1. 定义自定义错误模型 #

先创建一个类来封装友好提示和业务错误码：

public class MyError
{
    public string Message { get; set; }
    public int Code { get; set; }
}

2. 在控制器中直接返回带错误模型的状态码结果 #

ApiController继承的ControllerBase提供了一系列状态码方法（比如NotFound、BadRequest、Unauthorized等），这些方法都支持传入自定义对象作为响应体，框架会自动把它序列化为JSON返回，同时带上对应的HTTP状态码：

[ApiController]
[Route("api/users")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        // 模拟用户过期的业务场景
        bool isUserExpired = true;
        if (isUserExpired)
        {
            var myError = new MyError
            {
                Message = "用户不存在，因为已过期",
                Code = 3
            };
            // 返回HTTP 404状态码，同时带上自定义错误信息
            return NotFound(myError);
        }

        // 正常业务逻辑，返回用户数据
        return Ok(new { Id = id, Name = "张三" });
    }
}

3. 可选：全局统一处理异常 #

如果想把未捕获的异常也转换成统一的错误格式，可以用ASP.NET Core的异常处理中间件：

第一步：定义自定义业务异常 #

public class UserExpiredException : Exception
{
    public int ErrorCode { get; }

    public UserExpiredException(string message, int errorCode) : base(message)
    {
        ErrorCode = errorCode;
    }
}

第二步：实现自定义异常处理器 #

public class CustomExceptionHandler : IExceptionHandler
{
    private readonly ILogger<CustomExceptionHandler> _logger;

    public CustomExceptionHandler(ILogger<CustomExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        // 处理用户过期异常
        if (exception is UserExpiredException userExpiredEx)
        {
            _logger.LogError(exception, "触发用户过期错误");
            var myError = new MyError
            {
                Message = userExpiredEx.Message,
                Code = userExpiredEx.ErrorCode
            };

            httpContext.Response.StatusCode = StatusCodes.Status404NotFound;
            await httpContext.Response.WriteAsJsonAsync(myError, cancellationToken);
            return true;
        }

        // 处理其他未捕获异常，返回通用服务器错误
        _logger.LogError(exception, "发生未处理的服务器异常");
        var serverError = new MyError
        {
            Message = "服务器内部错误，请稍后重试",
            Code = 999
        };
        httpContext.Response.StatusCode = StatusCodes.Status500InternalServerError;
        await httpContext.Response.WriteAsJsonAsync(serverError, cancellationToken);
        return true;
    }
}

第三步：在Program.cs中注册异常处理服务 #

var builder = WebApplication.CreateBuilder(args);

// 添加控制器服务
builder.Services.AddControllers();

// 注册自定义异常处理器
builder.Services.AddExceptionHandler<CustomExceptionHandler>();
builder.Services.AddProblemDetails();

var app = builder.Build();

// 启用异常处理中间件
app.UseExceptionHandler();

app.UseAuthorization();

app.MapControllers();

app.Run();

最终效果 #

当触发用户过期场景时，接口会返回HTTP 404状态码，响应体格式如下：

{
  "message": "用户不存在，因为已过期",
  "code": 3
}

内容的提问来源于stack exchange，提问作者AlgoRythm