[나의 무지] 🤯 Spring RequestBody와 Static Inner Class: 오해와 진실

실무 코드를 보다가 Controller의 RequestBody 클래스 안에 static inner class가 정의되어 있는 것을 봤다.

처음에는 “이 static 클래스 안의 프로퍼티들도 HTTP 요청에서 그대로 받을 수 있겠구나”라고 생각했다... (그래서 특정 api의 mandatory 요청 값들이 static 클래스 안의 프로퍼티들도 포함한다는 크나큰 오해를 하게 되었다.)

 

하지만 실제로는 그렇지 않았던 것이다..

왜 그렇게 오해했을까?

public class OuterRequest {
    private String outerField;

    public static class Inner {
        private String innerField;
    }
}

• OuterRequest 안에 Inner라는 static 클래스가 정의되어 있었는데, 이름만 보고 “요청 JSON에서 innerField도 바로 매핑되겠지?”라고 쉽게 생각했던 것이다.

실제 동작

• Spring MVC의 @RequestBody는 OuterRequest 클래스의 프로퍼티만 매핑한다.
• Inner 클래스의 필드는 OuterRequest 안에 해당 타입의 프로퍼티가 선언되어 있어야만 매핑된다.

public class OuterRequest {
    private String outerField;
    private Inner inner; // 여기에 선언해야 요청에서 매핑 가능

    public static class Inner {
        private String innerField;
        // getter, setter
    }
}

// 요청 바디
{
  "outerField": "value",
  "inner": {
    "innerField": "value2"
  }
}

• static class Inner 는 Outer 클래스의 인스턴스와 독립적으로 존재하는 것으로 Outer 객체 안에 자동으로 포함되는 게 아님 → 단순히 "이름 공간(namespace)을 Outer 밑으로 둔 것"일 뿐이다.
• 만약 OuterRequest에 private Inner inner; 가 없으면, JSON 안에 innerField가 있더라도 Spring은 매핑하지 않는다!!

---

스프링의 @RequestBody 바인딩

@RestController
public class MyController {
    @PostMapping("/test")
    public String test(@RequestBody Outer body) {
        return "ok";
    }
}

• 스프링이 JSON → Java 객체 매핑할 때는 Jackson 같은 JSON 파서를 씀
• 매핑 대상은 @RequestBody에 지정한 그 클래스의 프로퍼티들
• Outer 클래스 안에 Inner가 있어도, JSON에 innerField가 있다고 해서 자동으로 Inner에 매핑되는 건 아님

---

✅ 정리

• static inner class는 단지 독립적인 클래스일 뿐, 자동으로 부모의 RequestBody 매핑에 포함되지 않는다.
• 매핑하려면 부모 클래스에 해당 inner class 타입 프로퍼티를 정의해야 한다. 그 후 JSON 구조를 맞춰야 바인딩이 된다.

깨달은 점

Static inner 클래스를 외부 클래스에서 실제로 사용하지 않을 거라면, 굳이 이렇게 코딩하면 안 된다는 것을 깨달았다. 누군가는 코드를 슥 보고 저처럼 “이 안의 프로퍼티들도 요청으로 들어오는구나” 하고 오해할 수 있을 것 같다는 생각이 들었다...
유지보수와 협업에서 혼동이 생길 수 있으므로, 실제로 외부에서 참조하거나 DTO 구조로 명확히 사용할 때만 static inner class를 정의하는 것이 안전하다.

추가로, Java record나 독립 DTO 클래스를 사용하면 JSON 매핑도 직관적이고 오해의 여지도 줄일 수 있을 것이다.