C# ASP.NET Web API 컨트롤러 액션의 다양한 반환 유형 완벽 정리

ASP.NET Web API의 액션 메서드는 목적에 따라 여러 가지 반환 유형을 사용할 수 있습니다. 상황에 맞는 반환 유형을 선택하면 코드의 가독성과 유지보수성, 테스트 용이성이 크게 향상됩니다.

Web API 액션의 주요 반환 유형

void - 반환값이 없는 경우
기본 타입(Primitive Type) / 복합 타입(Complex Type) - int, string, List 등
HttpResponseMessage - 응답을 세밀하게 제어해야 하는 경우
IHttpActionResult - Web API 2에서 권장하는 방식

1. void 반환 유형

모든 액션 메서드가 반드시 값을 반환해야 하는 것은 아닙니다. 특별히 클라이언트에게 데이터를 돌려줄 필요가 없다면 반환 유형을 void로 선언할 수 있습니다.

using DemoWebApplication.Models;
using System.Web.Http;

namespace DemoWebApplication.Controllers
{
    public class DemoController : ApiController
    {
        public void Get([FromBody] Student student)
        {
            // 일부 작업 수행
        }
    }
}

반환 유형이 void인 액션 메서드는 자동으로 204 No Content 응답을 반환합니다. 이는 요청이 성공적으로 처리되었지만 응답 본문에는 보낼 내용이 없다는 의미입니다.

2. 기본 타입 / 복합 타입

액션 메서드는 int, string 같은 기본 타입이나 List<T>, 사용자 정의 클래스 같은 복합 타입을 직접 반환할 수도 있습니다. Web API 프레임워크가 이를 자동으로 JSON 또는 XML로 직렬화하여 응답합니다.

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

namespace DemoWebApplication.Controllers
{
    public class DemoController : ApiController
    {
        public List<string> Get([FromBody] Student student)
        {
            return new List<string>
            {
                $"학생의 Id는 {student.Id}입니다.",
                $"학생의 이름은 {student.Name}입니다."
            };
        }
    }
}

이 방식은 간단하지만, HTTP 상태 코드나 응답 헤더를 세부적으로 제어하기는 어렵습니다.

3. HttpResponseMessage

HttpResponseMessage는 액션 메서드의 응답을 세밀하게 커스터마이징해야 할 때 사용합니다. 상태 코드, 콘텐츠 타입, 응답 본문에 담을 데이터를 직접 지정할 수 있습니다.

using DemoWebApplication.Models;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace DemoWebApplication.Controllers
{
    public class DemoController : ApiController
    {
        public HttpResponseMessage Get([FromBody] Student student)
        {
            if (student.Id > 0)
            {
                return Request.CreateResponse(HttpStatusCode.OK,
                    $"학생 Id는 {student.Id}이고 이름은 {student.Name}입니다.");
            }
            else
            {
                return Request.CreateResponse(HttpStatusCode.BadRequest,
                    "유효하지 않은 학생 Id입니다.");
            }
        }
    }
}

위 예제에서는 전달된 Id 값이 0이므로 else 블록이 실행되고, 지정된 오류 메시지와 함께 400 Bad Request 응답이 반환됩니다. 이처럼 조건에 따라 서로 다른 상태 코드를 유연하게 설정할 수 있다는 것이 HttpResponseMessage의 장점입니다.

4. IHttpActionResult

IHttpActionResult 인터페이스는 Web API 2에서 새롭게 도입되었습니다. 본질적으로 이 인터페이스는 HttpResponseMessage를 생성하는 팩토리 역할을 하며, System.Web.Http 네임스페이스에 포함되어 있습니다.

HttpResponseMessage 대신 IHttpActionResult를 사용하면 다음과 같은 장점이 있습니다.

컨트롤러의 단위 테스트(Unit Test)가 훨씬 간단해집니다.
HTTP 응답 생성에 필요한 공통 로직을 별도의 클래스로 분리할 수 있습니다.
응답 구성의 저수준 세부 사항을 숨겨 컨트롤러 액션의 의도를 더 명확하게 드러냅니다.

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

namespace DemoWebApplication.Controllers
{
    public class DemoController : ApiController
    {
        public IHttpActionResult Get([FromBody] Student student)
        {
            var result = new List<string>
            {
                $"학생의 Id는 {student.Id}입니다.",
                $"학생의 이름은 {student.Name}입니다."
            };

            return Ok(result);
        }
    }
}

위 예제처럼 Ok(), BadRequest(), NotFound() 등 미리 정의된 헬퍼 메서드를 활용하면 코드가 간결해지고 의미가 명확해집니다. 실무에서는 특별한 이유가 없는 한 IHttpActionResult 사용이 권장됩니다.