252 lines
9.7 KiB
Markdown
252 lines
9.7 KiB
Markdown
# Response Format 기준
|
|
|
|
## 1. 목적
|
|
|
|
이 문서는 API 응답 본문의 형식과 공통 규약을 정의한다.
|
|
|
|
이 문서의 목표는 다음과 같다.
|
|
|
|
- 성공/실패 응답의 구조를 일관되게 만든다
|
|
- controller마다 제각각인 응답 body 형식을 막는다
|
|
- HTTP status와 응답 body의 역할을 구분한다
|
|
- 공통 응답 envelope와 실제 business payload의 책임을 분리한다
|
|
|
|
## 2. 근거 수준
|
|
|
|
- Official: Spring Framework 공식 문서에서 직접 확인되는 내용
|
|
- Official + Practice: 공식 문서의 확장 지점 위에 일반적인 실무 API 설계 원칙을 결합한 내용
|
|
- Project Recommendation: 이 프로젝트 구조와 운영 방식에 맞춘 규칙
|
|
|
|
## 3. 기본 원칙
|
|
|
|
### 3.1 이 프로젝트의 JSON API 기본 응답 형식은 ApiResult<T>다
|
|
|
|
Spring은 응답 body를 @ResponseBody/ResponseEntity로 직렬화하고, 필요하면 ResponseBodyAdvice로 body를 공통 가공할 수 있게 한다. 따라서 프로젝트는 Spring의 공식 응답 처리 지점을 그대로 사용하되, 실제 JSON 응답 본문 형식은 custom envelope인 ApiResult<T>로 표준화한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 일반 JSON API 응답의 기본 형식은 ApiResult<T>
|
|
- controller마다 서로 다른 임의 JSON 구조를 만들지 않는다
|
|
- ApiResult는 transport-level envelope이고, 실제 payload는 T가 담당한다
|
|
|
|
### 3.2 응답 형식은 “공통 envelope”와 “실제 data”를 분리한다
|
|
|
|
Spring 공식 문서가 ResponseEntity와 body object를 분리해서 다루는 구조를 제공하는 것처럼, 이 프로젝트도 응답의 공통 필드와 business payload를 분리한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 공통 응답 정보는 ApiResult가 담당
|
|
- 실제 비즈니스 데이터는 data가 담당
|
|
- business DTO 안에 다시 success, code, message를 중복으로 넣지 않는다
|
|
|
|
### 3.3 응답 형식은 전역 규약이어야 한다
|
|
|
|
Spring은 ResponseBodyAdvice를 통해 @ResponseBody나 ResponseEntity 응답을 전역적으로 가공할 수 있다. 즉, 응답 형식 통일은 controller 개별 구현이 아니라 프레임워크 확장 지점에서 중앙 관리할 수 있다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 응답 형식 표준화는 controller마다 수동으로 맞추는 것보다 공통 규약으로 관리한다
|
|
- 같은 API 군 안에서는 성공/실패 응답 형식이 일관되어야 한다
|
|
- endpoint마다 envelope 유무가 달라지는 surprise를 만들지 않는다
|
|
|
|
## 4. 표준 응답 구조
|
|
|
|
### 4.1 성공 응답
|
|
|
|
프로젝트 기본 형식 예시:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"code": "SUCCESS",
|
|
"message": "Success",
|
|
"data": {
|
|
"userId": "u_123",
|
|
"email": "user@example.com"
|
|
},
|
|
"meta": null
|
|
}
|
|
```
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 성공 응답은 success=true
|
|
- 성공 응답의 표준 code는 기본적으로 SUCCESS
|
|
- 실제 payload는 data
|
|
- 부가 정보가 필요하면 meta 사용 가능
|
|
- 단순 성공이더라도 응답 구조를 임의로 바꾸지 않는다
|
|
|
|
이 항목은 Project Recommendation 이다.
|
|
|
|
### 4.2 실패 응답
|
|
|
|
Spring은 예외를 HTTP 응답으로 렌더링하는 공식 지점으로 @ExceptionHandler, @ControllerAdvice, ResponseEntityExceptionHandler를 제공한다. 이 프로젝트는 그 지점을 사용해 실패 응답도 ApiResult 형식으로 통일한다.
|
|
|
|
프로젝트 기본 형식 예시:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"code": "REQUEST_VALIDATION_FAILED",
|
|
"message": "Request validation failed",
|
|
"data": {
|
|
"email": "must not be blank"
|
|
},
|
|
"meta": {
|
|
"requestId": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 실패 응답은 success=false
|
|
- 실패 원인 식별자는 반드시 code에 둔다
|
|
- 외부 노출 메시지는 message
|
|
- 상세 오류 정보가 필요하면 data 또는 별도 표준 필드에 둔다
|
|
- 내부 예외 스택트레이스, 클래스명, 민감정보를 응답 body에 넣지 않는다
|
|
|
|
## 5. ApiResult 설계 규칙
|
|
|
|
### 5.1 envelope는 얇고 안정적이어야 한다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- ApiResult 필드는 최소한으로 유지한다
|
|
- envelope 구조는 쉽게 자주 바꾸지 않는다
|
|
- 응답 본문 규약은 business DTO보다 더 안정적인 계약으로 다룬다
|
|
|
|
권장 기본 필드:
|
|
|
|
- success
|
|
- code
|
|
- message
|
|
- data
|
|
- meta (선택)
|
|
|
|
### 5.2 공통 필드와 business 필드를 섞지 않는다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- ApiResult 바깥과 data 안의 의미를 섞지 않는다
|
|
- pagination, cursor, totalCount 같은 응답 보조 정보는 규칙적으로 meta 또는 명시적 pagination DTO에 둔다
|
|
- business payload 안에 공통 상태 필드를 섞어 넣지 않는다
|
|
|
|
### 5.3 code는 문자열이지만 정책적으로 중앙 관리한다
|
|
|
|
이 문서는 응답 형식 문서이므로 code 체계 자체의 상세 규칙은 다음 문서인 Error Code/HTTP Status Separation Standard에서 다룬다. 다만 응답 형식 관점에서 code는 항상 존재하는 공통 식별자여야 한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 성공/실패 모두 code 필드를 가진다
|
|
- code는 advice/controller에서 임의 문자열로 흩뿌리지 않는다
|
|
- ErrorCode 같은 중앙 정책 타입을 통해 관리한다
|
|
|
|
## 6. ResponseEntity 사용 규칙
|
|
|
|
Spring 공식 문서 기준으로 ResponseEntity는 headers, body, status를 함께 지정하는 반환형이다. 따라서 전체 HTTP 응답을 제어할 필요가 있을 때 의미가 있다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 단순 200 JSON 응답이면 꼭 ResponseEntity를 강제하지 않는다
|
|
- 다음 경우에는 ResponseEntity를 사용한다
|
|
- 201 Created
|
|
- 204 No Content
|
|
- custom header
|
|
- 캐시/조건부 응답
|
|
- 다운로드/streaming
|
|
- endpoint별 status 제어가 중요한 경우
|
|
|
|
### 6.1 body 표준화와 ResponseEntity는 충돌하지 않아야 한다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- ResponseEntity<ApiResult<T>>는 허용된다
|
|
- 다만 ResponseEntity는 HTTP 제어용이고, ApiResult는 body 규약용이라는 역할 분리를 유지한다
|
|
- controller가 HTTP 제어도 없는데 습관적으로 ResponseEntity<ApiResult<T>>를 남발하지 않는다
|
|
|
|
## 7. ResponseBodyAdvice 사용 규칙
|
|
|
|
Spring의 ResponseBodyAdvice는 @ResponseBody 또는 ResponseEntity controller method 실행 후, HttpMessageConverter가 body를 쓰기 전에 응답을 커스터마이징하는 확장 지점이다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 전역 envelope 적용이 필요하면 ResponseBodyAdvice를 사용할 수 있다
|
|
- 이미 ApiResult인 응답은 다시 감싸지 않는다
|
|
- file response, streaming response, SSE, 이미 형식이 고정된 외부 계약 응답은 전역 래핑 대상에서 제외한다
|
|
- supports(...) 조건은 넓게 열기보다 명시적으로 제어한다
|
|
|
|
### 7.1 전역 래핑은 “마법”이 아니라 명시적 규약이어야 한다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 팀이 “모든 JSON 성공 응답을 자동으로 ApiResult.success(...)로 감싼다”는 규칙을 합의한 경우에만 전역 래핑을 쓴다
|
|
- 그렇지 않으면 controller가 명시적으로 ApiResult를 반환하게 한다
|
|
- 두 방식이 혼재되면 응답 규약 이해 비용이 커지므로 기본 전략 하나를 정한다
|
|
|
|
## 8. 예외 응답 형식 규칙
|
|
|
|
Spring은 @ControllerAdvice/@ExceptionHandler, ResponseEntityExceptionHandler, DefaultHandlerExceptionResolver 등을 통해 예외를 HTTP 응답으로 연결할 수 있다. 이 프로젝트는 그 공식 메커니즘 위에서 예외 응답도 ApiResult 형식으로 통일한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 공통 예외 응답은 @RestControllerAdvice에서 생성한다
|
|
- controller 안에서 실패 응답 body를 직접 조립하는 것을 기본 금지한다
|
|
- framework 예외와 business 예외가 서로 다른 JSON 구조를 가지지 않게 한다
|
|
|
|
### 8.1 실패 응답의 message는 외부 노출용이어야 한다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- message는 클라이언트에 보여줄 수 있는 수준으로 제한한다
|
|
- ex.getMessage()를 그대로 외부에 노출하는 것을 기본값으로 두지 않는다
|
|
- 내부 로그 메시지와 외부 응답 메시지를 분리한다
|
|
|
|
## 9. 예외적 응답 형식
|
|
|
|
### 9.1 envelope를 적용하지 않는 응답
|
|
|
|
Spring MVC는 body object뿐 아니라 HttpHeaders, file/streaming 관련 반환형 등도 지원한다. 모든 응답이 JSON envelope여야 하는 것은 아니다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
다음은 ApiResult envelope 적용 대상에서 제외할 수 있다.
|
|
|
|
- 파일 다운로드
|
|
- binary response
|
|
- streaming/SSE
|
|
- redirect
|
|
- 204 No Content
|
|
- 외부 표준 계약이 별도 형식을 강제하는 응답
|
|
|
|
### 9.2 HTML/view 응답과 JSON API 응답을 섞지 않는다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- JSON API는 ApiResult 또는 명시적 API 응답 규약을 따른다
|
|
- view rendering 응답은 별도 controller/경계로 분리한다
|
|
- 한 controller 안에서 HTML 응답 규약과 JSON envelope 규약을 섞지 않는다
|
|
|
|
## 10. 금지 규칙
|
|
|
|
다음은 기본 금지다.
|
|
|
|
- endpoint마다 제각각 다른 성공/실패 JSON 형식 사용
|
|
- controller 안에서 임시 Map<String, Object>로 응답 구조 조립
|
|
- ApiResult 바깥과 data 안에 공통 필드 중복
|
|
- ResponseBodyAdvice에서 무조건 이중 래핑
|
|
- 예외 메시지를 그대로 외부 응답에 노출
|
|
- HTTP status와 응답 body code/message 역할을 뒤섞기
|
|
- 파일/스트리밍 응답까지 무리하게 JSON envelope로 감싸기
|
|
|
|
## 11. 체크리스트
|
|
|
|
다음 질문에 “예”로 답할 수 있어야 한다.
|
|
|
|
- 이 응답은 프로젝트 표준 envelope(ApiResult)를 따르는가?
|
|
- ApiResult와 business payload의 역할이 분리되어 있는가?
|
|
- ResponseEntity를 쓰는 이유가 status/header 제어 때문인가?
|
|
- 전역 응답 래핑이 있다면 이중 래핑을 막고 있는가?
|
|
- 실패 응답도 성공 응답과 같은 큰 형식을 유지하는가?
|
|
- envelope 예외 대상(파일, 스트리밍 등)을 따로 처리하고 있는가?
|