C# ASP.NET Web API에서 [FromBody]와 [FromUri] 특성의 차이점 완벽 정리

ASP.NET Web API가 컨트롤러의 메서드를 호출할 때는 해당 메서드의 매개변수에 값을 할당해야 하며, 이 과정을 매개변수 바인딩(Parameter Binding)이라고 부릅니다. 매개변수가 어디에서 값을 가져올지는 특성(Attribute)을 통해 명시적으로 지정할 수 있으며, 그 대표적인 것이 [FromUri]와 [FromBody]입니다.

[FromUri] 특성이란?

기본적으로 복합 형식(complex type) 모델은 요청 본문(body)에서 값을 읽어 포매터(formatter)를 통해 바인딩됩니다. 만약 URI(쿼리 문자열 또는 경로 데이터)에서 모델을 바인딩하고 싶다면 매개변수에 [FromUri] 특성을 적용해야 합니다.

FromUriAttribute는 내부적으로 ModelBinderAttribute를 상속하며, Web API에게 IUriValueProviderFactory에 정의된 ValueProvider들을 사용하여 특정 매개변수를 URI에서 가져오도록 지시하는 단축 지시자 역할을 합니다. 이 특성 자체는 sealed로 선언되어 더 이상 확장할 수 없지만, 필요하다면 원하는 만큼 커스텀 IUriValueProviderFactory를 추가하는 것은 가능합니다.

[FromBody] 특성이란?

ParameterBindingAttribute 클래스를 상속받는 [FromBody] 특성은 HTTP 요청 본문(request body)으로부터 매개변수와 그 속성들을 채우는 데 사용됩니다. ASP.NET 런타임은 본문을 실제로 읽는 작업을 입력 포매터(input formatter)에 위임합니다.

주의할 점은 [FromBody]가 복합 형식 매개변수에 적용되면, 해당 속성들에 부여된 다른 바인딩 소스 특성들은 모두 무시된다는 것입니다.

[FromUri] 특성 예제

아래 예제는 Get 메서드의 id와 name 매개변수에 [FromUri] 특성을 적용한 코드입니다.

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

namespace DemoWebApplication.Controllers{
    public class DemoController : ApiController{
        public IEnumerable<string> Get([FromUri] string id, [FromUri] string name){
            return new string[]{
                $"The Id of the Student is {id}",
                $"The Name of the Student is {name}"
            };
        }
    }
}

위 예제에서는 URI를 통해 id와 name 값을 전달하여 Get 메서드의 각 변수에 매핑합니다.

https://localhost:58174/api/demo?id=1&name=Mark

실행 결과

위 코드의 실행 결과는 다음과 같습니다.

[FromBody] 특성 예제

먼저 아래와 같은 속성들을 가진 Student 모델을 생성합니다.

namespace DemoWebApplication.Models{
    public class Student{
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

컨트롤러 코드

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

namespace DemoWebApplication.Controllers{
    public class DemoController : ApiController{
        public IEnumerable<string> Get([FromBody] Student student){
            return new string[]{
                $"The Id of the Student is {student.Id}",
                $"The Name of the Student is {student.Name}"
            };
        }
    }
}

위 예제에서는 student 값을 요청 본문(body)을 통해 전달하며, 전달된 데이터는 Student 객체의 각 속성에 자동으로 매핑됩니다. 아래는 Postman을 사용한 요청 및 응답 예시입니다.

정리: [FromUri] vs [FromBody]

두 특성의 핵심적인 차이를 정리하면 다음과 같습니다.

• [FromUri]: 쿼리 문자열이나 경로 데이터 등 URI에서 값을 바인딩합니다. 단순 형식 매개변수나 GET 요청의 검색 조건 처리에 적합합니다.
• [FromBody]: HTTP 요청 본문에서 값을 바인딩합니다. POST나 PUT 요청처럼 복잡한 데이터를 전송할 때 사용되며, 하나의 액션 메서드에는 최대 하나의 [FromBody] 매개변수만 허용됩니다.