Skip to content

refactor: API 응답 포맷 통일 및 i18n 키 메시지 적용#17

Merged
buddle031 merged 5 commits intomainfrom
feat/response-contract-i18n-validation
Apr 18, 2026
Merged

refactor: API 응답 포맷 통일 및 i18n 키 메시지 적용#17
buddle031 merged 5 commits intomainfrom
feat/response-contract-i18n-validation

Conversation

@mike7643
Copy link
Copy Markdown
Collaborator

@mike7643 mike7643 commented Apr 15, 2026

✨ 작업 내용 한 줄 요약

  • 응답 코드와 포맷을 정리하고, 검증 에러 응답 메시지를 짐두고의 다국어 서비스에 맞게 프론트에서 쓰기 쉬운 형태로 통일했습니다.

🛠️ 작업 내용

  • SuccessCode, ErrorCode가 BaseCode를 구현하도록 정리했습니다.
  • RestResponse는 BaseCode만 받아서 code/message/status를 공통으로 채우도록 하였습니다.
  • 검증 에러 구조를 Map 방식에서 ValidationError(field, message) 리스트로 변경했습니다.
  • MethodArgumentNotValidException, ConstraintViolationException 모두 동일한 validationErrors 포맷으로 응답하도록 맞췄습니다.
  • 검증 메시지는 완성 문장 대신 validation.* 형태 키를 내려주도록 통일했습니다.

🧠 기술적 의사결정

이번 PR의 핵심이라고 할 수 있는 것은 메시지를 완성된 문장으로 내려주는 대신, i18n 키를 내려주는 방식으로 통일한 점입니다!

성공 응답 예시

{
  "code": "S001",
  "reason": "common.success",
  "status": 200,
  "timestamp": "2026-04-16T02:05:00Z",
  "data": {
    "id": 123,
    "name": "짐두고 보관소 A"
  }
}
{
  "code": "S001",
  "reason": "common.success",
  "status": 200,
  "timestamp": "2026-04-16T03:30:00Z",
  "data": [
    {
      "id": 123,
      "name": "짐두고 보관소 A"
    },
    {
      "id": 124,
      "name": "짐두고 보관소 B"
    }
  ]
}

에러 응답 예시

{
  "code": "L001",
  "reason": "locker.not_found",
  "status": 404,
  "timestamp": "2026-04-16T02:16:10Z"
}
{
  "code": "V001",
  "reason": "validation.invalid",
  "status": 400,
  "timestamp": "2026-04-16T02:07:05Z",
  "validationErrors": [
    {
      "field": "email",
      "message": "validation.email"
    },
    {
      "field": "global",
      "message": "validation.password_mismatch"
    }
  ]
}

백엔드에서 내려주는 message 키값을 바탕으로 클라이언트에서 각 언어별로 대응하는 예시입니다.

{
  "common.success": "リクエストが正常に処理されました。",
  "validation.invalid": "入力内容を確認してください。",
  "validation.email": "メールアドレスの形式가正しくありません。",
  "validation.password_mismatch": "パスワードが一致しません。"
}
{
  "common.success": "请求处理成功。",
  "validation.invalid": "请检查输入内容。",
  "validation.email": "邮箱格式不正确。",
  "validation.password_mismatch": "密码不匹配。"
}

이 방식을 선택한 이유는 아래와 같습니다.

  • 다국어 확장 비용이 줄어듭니다.
    백엔드는 validation.not_blank, auth.invalid_refresh_token 같은 의미 키만 내려주고, 실제 한국어/영어/일본어/중국어 는 프론트의 i18n을 채택할 수 있습니다.

  • 운영 대응이 유연해집니다.
    문구나 톤 조정이 필요할 때 서버 변경 없이 가능합니다.

@mike7643 mike7643 self-assigned this Apr 15, 2026
@mike7643 mike7643 requested a review from buddle031 as a code owner April 15, 2026 17:58
@mike7643 mike7643 changed the title refactor: API 응답 포맷 통일 및 i18n 키 기반 메시지 적용 refactor: API 응답 포맷 통일 및 i18n 키 메시지 적용 Apr 15, 2026
@buddle031
Copy link
Copy Markdown
Collaborator

응답 규약을 BaseCode 중심으로 통일하고, 검증 에러를 i18n 키 기반 구조로 정리해 운영 유연성까지 잘 챙기신거 같아요! 고생 많으셨습니다!

@buddle031 buddle031 merged commit d3c1a4a into main Apr 18, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants