C# WebAPI控制器层异常/错误处理规范咨询

针对你遇到的控制器层异常返回格式不统一的问题，可以通过以下几种方式彻底规范：

1. 提前拦截参数异常，统一抛出全局过滤器可识别的异常 #

在控制器方法执行业务逻辑前，手动校验所有输入参数，一旦发现null或非法值，直接抛出ArgumentNullException（或自定义的参数异常类），让全局过滤器统一处理。这样就能避免后续代码因null触发NullReferenceException这类未被全局过滤器适配的异常。

示例代码：

[HttpGet("{dataId}")]
public IActionResult GetData(string dataId)
{
    // 提前校验参数，避免后续Split触发空引用异常
    if (string.IsNullOrWhiteSpace(dataId))
    {
        throw new ArgumentNullException(nameof(dataId), "数据ID不能为空");
    }
    
    var parts = dataId.Split('-');
    // 后续业务逻辑处理
    return Ok(parts);
}

2. 扩展全局异常过滤器，覆盖控制器层可能出现的常见异常 #

修改HttpGlobalExceptionFilter.cs，添加对控制器层高频异常（比如NullReferenceException、FormatException等）的处理逻辑，统一返回格式。注意生产环境不要暴露具体异常堆栈，只返回用户友好的提示，详细异常信息写入日志即可。

示例代码：

public class HttpGlobalExceptionFilter : IExceptionFilter
{
    private readonly ILogger<HttpGlobalExceptionFilter> _logger;

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

    public void OnException(ExceptionContext context)
    {
        var errorResponse = new ErrorResponse // 你的统一错误格式类
        {
            TraceId = Activity.Current?.Id ?? context.HttpContext.TraceIdentifier
        };

        switch (context.Exception)
        {
            case ArgumentNullException ex:
                errorResponse.StatusCode = StatusCodes.Status400BadRequest;
                errorResponse.Message = $"参数错误：{ex.ParamName}不能为空";
                break;
            case NullReferenceException ex:
                errorResponse.StatusCode = StatusCodes.Status400BadRequest;
                errorResponse.Message = "请求参数不合法，请检查输入";
                _logger.LogError(ex, "控制器层空引用异常：{Message}", ex.Message); // 日志记录详细信息
                break;
            default:
                errorResponse.StatusCode = StatusCodes.Status500InternalServerError;
                errorResponse.Message = "服务器内部错误，请稍后重试";
                _logger.LogError(context.Exception, "未处理异常");
                break;
        }

        context.Result = new JsonResult(errorResponse)
        {
            StatusCode = errorResponse.StatusCode
        };
        context.ExceptionHandled = true;
    }
}

3. 利用ModelState自动校验，统一参数错误返回 #

借助ASP.NET Core的数据注解特性，给参数添加[Required]、[StringLength]等校验属性，然后在控制器中统一检查ModelState.IsValid，将校验失败的结果转换成和全局过滤器一致的错误格式。

你可以把这个校验逻辑抽成基类控制器，让所有业务控制器继承，减少重复代码：

// 基类控制器
public class BaseApiController : ControllerBase
{
    protected IActionResult ValidateModel()
    {
        if (!ModelState.IsValid)
        {
            var errorMessages = ModelState.Values
                .SelectMany(v => v.Errors)
                .Select(e => e.ErrorMessage)
                .ToList();

            var errorResponse = new ErrorResponse
            {
                StatusCode = StatusCodes.Status400BadRequest,
                Message = string.Join("; ", errorMessages),
                TraceId = Activity.Current?.Id ?? HttpContext.TraceIdentifier
            };

            return new JsonResult(errorResponse) { StatusCode = errorResponse.StatusCode };
        }
        return null;
    }
}

// 业务控制器
public class DataController : BaseApiController
{
    [HttpGet("{dataId}")]
    public IActionResult GetData([Required(ErrorMessage = "数据ID不能为空")] string dataId)
    {
        var validateResult = ValidateModel();
        if (validateResult != null)
        {
            return validateResult;
        }
        
        var parts = dataId.Split('-');
        return Ok(parts);
    }
}

4. 下沉业务逻辑到服务层，减少控制器层异常 #

控制器的职责应该是接收请求、校验参数、调用服务、返回响应，尽量避免在控制器层处理业务逻辑（比如字符串拆分、数据转换等）。把这类逻辑放到服务层，由服务层负责参数校验和业务处理，抛出的异常会被全局过滤器统一处理，从根源上减少控制器层的异常。

示例代码：

// 控制器
[HttpGet("{dataId}")]
public IActionResult GetData(string dataId)
{
    var result = _dataService.SplitDataId(dataId);
    return Ok(result);
}

// 服务层
public class DataService
{
    public string[] SplitDataId(string dataId)
    {
        if (string.IsNullOrWhiteSpace(dataId))
        {
            throw new ArgumentNullException(nameof(dataId), "数据ID不能为空");
        }
        
        if (!dataId.Contains('-'))
        {
            throw new FormatException("数据ID格式不正确，需包含'-'分隔符");
        }
        
        return dataId.Split('-');
    }
}

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