.NET Core Web API AuthorizationException返回500改401方案及最佳实践

实现方案：全局异常过滤器返回401 #

首先纠正认知误区：ActionExecutedContext 自带 HttpContext 属性，通过 context.HttpContext.Request 即可获取完整的请求信息，不存在只能拿响应的问题。你可以直接在现有过滤器中新增逻辑处理AuthorizationException：

public void OnActionExecuted(ActionExecutedContext context)
{
    if (context.Exception is ApiErrorException ex)
    {
        var bdo = new BaseReturnDataObject(ex.Message, ex.Type);
        context.Result = new JsonResult(bdo);
        context.ExceptionHandled = true;
    }
    // 新增AuthorizationException处理逻辑
    else if (context.Exception is AuthorizationException authEx)
    {
        var bdo = new BaseReturnDataObject(authEx.Message, "AuthorizationFailed");
        // 显式设置401状态码
        context.Result = new JsonResult(bdo)
        {
            StatusCode = StatusCodes.Status401Unauthorized
        };
        context.ExceptionHandled = true;
    }
}

关于返回401是否合理的说明 #

你之前看到的「不要把500改成401」的说法，仅针对不符合HTTP语义的状态码滥用场景，你的场景完全适用401：

• 401的标准定义是「请求缺乏访问目标资源的有效凭证」，自定义身份校验（是否为学生）属于接口的访问权限要求，校验失败返回401完全符合语义
• 500仅用于服务端不可预期的故障，比如数据库连接中断、空引用异常等，你的自定义校验是显式的业务逻辑判断，不属于服务故障
• 如果强行用500返回授权错误，会导致监控系统把正常的权限校验失败统计为服务故障，干扰服务可用性统计

客户端区分错误的最佳实践 #

无论选择哪种状态码，都建议遵循以下规则：

• 优先用符合语义的HTTP状态码做第一层区分：4xx对应客户端/权限类错误，5xx对应服务端故障类错误，客户端可以通过状态码快速做粗粒度处理，比如401统一跳转权限提示页，500统一提示「系统繁忙，请稍后重试」
• 返回结构化错误体做细粒度区分：所有错误返回都携带errorCode、message两个固定字段，比如学生校验失败的errorCode为USER_NOT_STUDENT，数据库故障的errorCode为SYSTEM_INTERNAL_ERROR，客户端通过errorCode做精确的业务逻辑处理，避免依赖易变的message文案

如果因团队规范必须保留500状态码，可以用结构化错误体区分场景：

else if (context.Exception is AuthorizationException authEx)
{
    var bdo = new BaseReturnDataObject(authEx.Message, "USER_NOT_STUDENT");
    context.Result = new JsonResult(bdo)
    {
        StatusCode = StatusCodes.Status500InternalServerError
    };
    context.ExceptionHandled = true;
}

该方案的缺点是不符合HTTP语义，不利于中间件自动识别错误类型。

本场景最优方案 #

该场景下的最佳实践是返回401状态码+结构化错误体，原因如下：

• 完全符合HTTP协议语义，不会造成认知歧义
• 网关、APM监控等中间件可以自动归类错误，统计数据更准确
• 客户端处理成本最低，不需要额外解析错误体就能先做第一层判断

内容的提问来源于stack exchange，提问作者Eric Brown - Cal