> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/dev-guide/dev-start/interactive-blocks/response.md).

# 응답값(Response) 공통 처리

다음은 X2BEE 응답값 Response 공통 처리에 대해 설명합니다.

공통처리 설명과 설정값 및 커스텀 어노테이션 사용 방법과 예제입니다.

***

## 공통처리 설명

응답값 공통 처리는 다음과 같습니다.

* String, int, List, Map, Model 객체 등 → 공통 모델인 Response의 payload에 Set → Response 객체를 ResponseEntity에 포함하여 반환
* Response → Response 객체를 ResponseEntity에 포함하여 반환
* ResponseEntity 객체인 경우 그대로 반환

## 설정값으로 사용

설정값으로 사용할 경우 application.yml 파일을 이용합니다.

응답값을 공통 모델인 Response 모델로 공통 처리하는 설정은 기본값이 true로 설정되어 있습니다.

해당 설정을 사용하지 않고 싶을 경우에는 application.yml 파일에서 global.response.advice 설정을 false로 줍니다.

{% hint style="warning" %}
해당 설정값이 없더라도 코드상 기본값이 true로 되어 있으므로, 공통 처리를 비활성화하려면 반드시 application.yml에 아래 값을 명시적으로 false로 설정해야 합니다. 설정을 삭제하는 것으로는 비활성화되지 않습니다.
{% endhint %}

예시 (application.yml):

```yaml
global:
  response:
    advice: true
```

## 커스텀 어노테이션 사용

아래 두 개의 커스텀 어노테이션을 사용하여 특정 컨트롤러/핸들러에서 공통 응답 처리 동작을 제어할 수 있습니다.

* @EnableResponseBodyAdvice — 해당 핸들러에 대해 응답값 공통 처리를 강제로 적용
* @DisableResponseBodyAdvice — 해당 핸들러에 대해 응답값 공통 처리를 비활성화

{% stepper %}
{% step %}

### Enable 예제

@EnableResponseBodyAdvice를 사용한 예제:

{% code title="SampleController - enable 예제" %}

```
```

{% endcode %}

```java
public class SampleController {

    @EnableResponseBodyAdvice
    @GetMapping("/search2")
    public ResponseEntity<List<SampleResponse>> searchSamples2(@RequestBody Optional<SampleRequest> sampleRequest) {
        // 데이터와 함께
        log.info("sampleRequest: {}", sampleRequest.isPresent() ? sampleRequest.get() : "");
        List<SampleResponse> data = sampleService.searchSamples();
        return ResponseEntity.ok().body(data);
    }
}
```

설명: @EnableResponseBodyAdvice을 사용할 경우 설정값이 false이더라도 어노테이션을 따라 응답값 공통 처리가 적용되어 최종적으로 Response 형태로 반환됩니다.
{% endstep %}

{% step %}

### Disable 예제

@DisableResponseBodyAdvice를 사용한 예제:

{% code title="SampleController - disable 예제" %}

```
```

{% endcode %}

```java
public class SampleController {

    @DisableResponseBodyAdvice
    @GetMapping("/search3")
    public ResponseEntity<List<SampleResponse>> searchSamples3(@RequestBody Optional<SampleRequest> sampleRequest) {
        // 데이터와 함께
        log.info("sampleRequest: {}", sampleRequest.isPresent() ? sampleRequest.get() : "");
        List<SampleResponse> data = sampleService.searchSamples();
        return ResponseEntity.ok().body(data);
    }
}
```

설명: @DisableResponseBodyAdvice을 사용할 경우 설정값이 없거나 true이더라도 어노테이션을 따라 응답값 공통 처리가 되지 않아 List 형태로 반환됩니다.
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://tech.x2bee.com/dev-guide/dev-start/interactive-blocks/response.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.