C# ASP.NET Web API에서 처리되지 않은 예외를 다루는 예외 필터(Exception Filter) 만드는 방법

ASP.NET Web API에서 예외 필터(Exception Filter)는 컨트롤러 메서드가 HttpResponseException이 아닌 처리되지 않은(unhandled) 예외를 던질 때 실행됩니다. HttpResponseException은 HTTP 응답을 반환하기 위해 특별히 설계된 타입이기 때문에 특수한 경우로 분류되며, 예외 필터의 대상이 되지 않습니다.

예외 필터 구현 방법

예외 필터는 System.Web.Http.Filters.IExceptionFilter 인터페이스를 구현하여 만들 수 있습니다. 가장 간단한 작성 방법은 System.Web.Http.Filters.ExceptionFilterAttribute 클래스를 상속받고 OnException 메서드를 재정의(override)하는 것입니다.

아래는 NotFiniteNumberException 예외를 HTTP 상태 코드 416(Requested Range Not Satisfiable)으로 변환하는 필터 예제입니다.

1. ExceptionFilterAttribute 작성

using System;
using System.Net;
using System.Net.Http;
using System.Web.Http.Filters;

namespace DemoWebApplication.Controllers
{
    public class ExceptionAttribute : ExceptionFilterAttribute
    {
        public override void OnException(HttpActionExecutedContext context)
        {
            if (context.Exception is NotFiniteNumberException)
            {
                context.Response = new HttpResponseMessage(HttpStatusCode.RequestedRangeNotSatisfiable);
            }
        }
    }
}

2. 컨트롤러 액션 메서드 작성

다음으로 위에서 만든 필터를 적용할 컨트롤러를 작성합니다. 이 컨트롤러는 유효하지 않은 id 값이 전달되면 NotFiniteNumberException을 발생시킵니다.

using DemoWebApplication.Models;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace DemoWebApplication.Controllers
{
    [Exception]
    public class StudentController : ApiController
    {
        List<Student> students = new List<Student>
        {
            new Student { Id = 1, Name = "Mark" },
            new Student { Id = 2, Name = "John" }
        };

        public Student Get(int id)
        {
            if (id <= 0)
            {
                throw new NotFiniteNumberException("The Id is not valid");
            }

            var studentForId = students.FirstOrDefault(x => x.Id == id);
            return studentForId;
        }
    }
}

동작 테스트

컨트롤러의 액션 메서드에 id = 0을 전달하여 요청을 보내면, NotFiniteNumberException이 발생하고 예외 필터가 이를 가로채어 HTTP 상태 코드 416 응답을 반환하는 것을 확인할 수 있습니다.

예외 필터 등록 방법

작성한 ExceptionAttribute는 아래 세 가지 방법 중 하나로 등록하여 사용할 수 있습니다.

방법 1: 액션 메서드에 직접 적용

특정 액션 메서드에만 필터를 적용하려면 해당 메서드 위에 특성(Attribute)을 선언합니다.

[Exception]
public IHttpActionResult Get(int id)
{
    return Ok();
}

방법 2: 컨트롤러에 적용

컨트롤러 클래스 수준에 적용하면 해당 컨트롤러의 모든 액션 메서드에 필터가 적용됩니다.

[Exception]
public class StudentController : ApiController
{
    public IHttpActionResult Get(int id)
    {
        return Ok();
    }
}

방법 3: WebApiConfig.cs에 전역 등록

애플리케이션 전체의 모든 컨트롤러에 필터를 적용하려면 WebApiConfig.cs에서 전역 필터로 등록합니다.

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Filters.Add(new ExceptionAttribute());
    }
}

정리

예외 필터를 활용하면 컨트롤러 곳곳에 try-catch 블록을 반복해서 작성하지 않아도 되므로 코드가 깔끔해지고, 예외 처리 로직을 한 곳에서 일관되게 관리할 수 있습니다. 적용 범위에 따라 액션 단위, 컨트롤러 단위, 전역 단위 중 프로젝트 상황에 맞는 등록 방식을 선택하면 됩니다.