백엔드 스터디 Day 12: 프론트엔드 개발자를 위한 협업 지도

화면: 게시글 상세 페이지
필요한 요청:
1. 게시글 상세 조회
2. 댓글 목록 조회
3. 댓글 작성
4. 댓글 삭제
5. 좋아요 토글

GET /api/posts/{postId}
성공: 200, PostDetailResponse
실패:
- 404 POST_NOT_FOUND
- 403 PRIVATE_POST
인증: 비공개 글이면 필요

1. endpoint: URL과 method
2. auth: 인증 필요 여부
3. request: path/query/body/header
4. response: 성공 응답 구조
5. error: 실패 응답 구조와 code
6. state: 요청 후 프론트엔드 상태가 어떻게 바뀌는지

POST /api/comments
인증: 필요
request body:
{
  "postId": 10,
  "content": "댓글 내용"
}

success 201:
{
  "id": 100,
  "postId": 10,
  "authorNickname": "seojing",
  "content": "댓글 내용",
  "createdAt": "2026-06-12T09:30:00Z"
}

errors:
- 400 INVALID_COMMENT_CONTENT
- 401 UNAUTHENTICATED
- 404 POST_NOT_FOUND

post: {
  id: number;
  title: string;
  content: string;
  authorName: string;
  liked: boolean;
  likeCount: number;
}

Post table
Member table
Like table
Comment table

이 화면을 그리기 위해 프론트엔드가 어떤 응답을 받아야 하는가?

{
  "id": 10,
  "title": "스터디 후기",
  "summary": "이번 주에 배운 내용은...",
  "authorNickname": "seojing",
  "commentCount": 3,
  "createdAt": "2026-06-12T09:30:00Z"
}

{
  "id": 10,
  "title": "스터디 후기",
  "content": "...",
  "authorNickname": "seojing",
  "editable": true,
  "deletable": true,
  "createdAt": "2026-06-12T09:30:00Z"
}

1. Authorization header에 Bearer token을 붙이는 방식
2. HttpOnly cookie로 세션/토큰을 주고받는 방식

Authorization: Bearer ***

Set-Cookie
HttpOnly
Secure
SameSite
CORS credentials

fetch("/api/me", {
  credentials: "include",
});

로그인 성공 시 인증 정보는 header로 오나, cookie로 오나?
다음 요청에서 프론트엔드는 무엇을 붙여야 하나?
로그아웃은 서버 상태를 지우나, 클라이언트 저장소만 지우나?
토큰 만료 시 응답 code는 무엇인가?
새로고침 후 로그인 상태 복원 API가 있는가?

이메일 형식 오류 → 이메일 input 아래에 메시지
이미 가입된 이메일 → 이메일 input 아래에 중복 메시지
비밀번호 너무 짧음 → 비밀번호 input 아래에 메시지
서버 장애 → 상단 toast 또는 안내 문구

{
  "code": "VALIDATION_FAILED",
  "message": "입력값을 확인해주세요.",
  "fieldErrors": [
    {
      "field": "email",
      "message": "이메일 형식이 올바르지 않습니다."
    }
  ]
}

{
  "message": "error"
}

프론트엔드가 이 에러 응답만 보고 사용자에게 어떤 메시지를 보여줄지 결정할 수 있는가?
필드 에러와 전역 에러가 구분되는가?
재시도 가능한 오류와 사용자가 고쳐야 하는 오류가 구분되는가?

API 문서가 실제 코드와 가까운 곳에서 유지되는가?
성공/실패 예시가 둘 다 있는가?
인증 필요 여부가 표시되어 있는가?
프론트엔드가 헷갈리는 enum/date/null 규칙이 적혀 있는가?
변경 시 누가 어떤 방식으로 알리는가?

각 API마다 request, success response, error response, auth requirement, frontend state update note를 포함해서 문서화해줘. 특히 400/401/403/404/409 에러 code 예시를 넣어줘.

로컬에서는 쿠키가 되는데 배포에서는 안 됨
CORS 에러가 남
API base URL이 환경별로 다름
파일 업로드 제한이 운영에서 다름
서버 시간대 때문에 날짜가 하루 밀림
응답이 느려서 로딩/타임아웃 처리가 필요함

dev/staging/prod API URL은 무엇인가?
CORS 허용 origin은 무엇인가?
인증 쿠키의 Secure/SameSite 설정은 배포 도메인에서 맞는가?
날짜는 UTC로 내려오는가, 로컬 시간으로 내려오는가?
파일 크기 제한과 timeout 기준은 무엇인가?
장애 시 프론트엔드는 어떤 메시지를 보여줘야 하는가?

[1. 요청 흐름]
화면에서 어떤 요청이 나가고, Controller → Service → Repository → Response로 어떻게 돌아오는가?

[2. API 계약]
URL, method, request, response, error, auth requirement가 명확한가?

[3. 입력 검증]
형식 오류는 DTO/Bean Validation에서 막고, 비즈니스 규칙은 Service에서 확인하는가?

[4. 데이터 경계]
Entity는 내부 저장 구조로 숨기고, 외부에는 DTO를 내려주는가?

[5. 비즈니스 흐름]
Service가 유스케이스를 설명하고, 트랜잭션이 필요한 단위를 안전하게 묶는가?

[6. 인증/권한]
로그인 여부와 리소스 접근 권한이 분리되어 있고, 사용자 입력 ID를 신뢰하지 않는가?

[7. 테스트]
성공 케이스뿐 아니라 실패/권한/검증/중복 케이스가 API 응답까지 검증되는가?

[8. 문서]
프론트엔드가 구현을 시작할 수 있을 정도의 최신 계약 문서가 있는가?

[9. 배포/환경]
로컬, staging, production 설정이 분리되어 있고 비밀값이 코드에 들어가지 않는가?

[10. 관측 가능성]
문제가 났을 때 로그, requestId, 헬스체크, 메트릭으로 추적할 수 있는가?

이 API 언제 돼요?
에러가 나요.
로그인이 이상해요.
응답이 이상한데요?

POST /api/login에 email/password를 보내면 200은 오는데 Set-Cookie가 없습니다.
우리 프론트는 cookie 인증으로 구현해도 될까요, 아니면 Authorization header 방식인가요?

GET /api/posts/{postId} 응답에 editable 여부가 없어서 수정 버튼 노출을 프론트에서 authorId 비교로 처리해야 합니다.
권한 판단을 백엔드에서 해서 editable/deletable을 내려줄 수 있을까요?

회원가입 실패 시 모든 오류가 400 + message로만 옵니다.
필드별 오류를 input 아래에 보여주려면 fieldErrors 구조가 필요합니다.
VALIDATION_FAILED 응답 형식을 맞출 수 있을까요?

1. 화면/기능에서 필요한 API 목록 작성
2. API 계약 초안 작성
3. Entity/DTO/Service/Repository 구조 생성
4. 검증/에러/권한 기준 보강
5. 테스트 생성
6. 문서와 예시 응답 생성
7. 로그/환경/배포 설정 점검
8. 프론트엔드에서 실제 호출해보며 계약 수정

AI가 만든 결과물의 경계를 읽고,
부족한 품질 기준을 발견하고,
다음 수정 요청을 정확히 쓰는 능력.

1. HTTP와 브라우저 네트워크 탭 깊게 보기
2. 인증 방식 비교: session, JWT, OAuth
3. DB 모델링과 인덱스 기본
4. 트랜잭션 격리 수준과 동시성 문제
5. Spring Security 구조
6. 테스트 전략: unit, slice, integration, contract test
7. 배포 파이프라인과 observability

API 계약을 읽고,
요청/응답을 디버깅하고,
인증/에러/상태 흐름을 설명하고,
AI가 만든 백엔드 코드의 위험한 부분을 리뷰할 수 있는 것.

프론트엔드 개발자가 백엔드를 배운다는 것은 Spring 문법을 모두 외우는 일이 아니라,
사용자 행동이 API 요청이 되고, 그 요청이 검증·권한·데이터·응답·운영 흐름을 거쳐 다시 UI 상태로 돌아오는 과정을 읽는 일이다.

나는 API 요청 하나를 끝까지 따라갈 수 있는가?
나는 성공/실패 응답 계약을 보고 UI 상태를 설계할 수 있는가?
나는 입력 검증, 권한, 트랜잭션, 테스트의 위험 신호를 알아볼 수 있는가?
나는 인증 방식과 배포 환경 때문에 생기는 프론트 이슈를 질문할 수 있는가?
나는 AI에게 “돌아가는 코드”가 아니라 “협업 가능한 백엔드”를 요청할 수 있는가?