콘텐츠로 이동

API 계약과 오류

서버가 API 계약의 원본이에요. API를 바꾸면 OpenAPI 문서, 생성한 화면 타입, 그 API를 부르는 화면 코드를 같은 변경에서 맞춰요. 생성 순서는 화면과 서버 사이의 계약에 있어요. 이 장은 엔드포인트를 만들 때 지키는 규칙과 오류를 돌려주는 방식을 설명해요.

  • 자원 경로는 복수 명사로 써요(/api/v1/workspace/projects). 업무 상태를 바꾸는 일은 의미 있는 하위 자원으로 표현해요(…/projects/{key}/archive).
  • 화면 주소와 API 경로의 첫 마디는 같은 영역 이름으로 맞춰요(/workspace/…와 /api/v1/workspace/…).
  • 응답을 success·data 같은 공통 껍데기로 감싸지 않고 HTTP 상태 코드를 써요.
요청 성공 응답
조회 200과 본문
생성 201과 Location 헤더
변경·삭제 204

바로 필요한 결과가 있으면 응답 모델을 명시해요. 예를 들어 파일 올리기 준비(POST /api/v1/files/uploads)는 브라우저가 곧바로 쓸 주소와 헤더를 201 본문으로 돌려줘요.

  • PATCH에서는 값을 빼는 것, null을 보내는 것, 값을 보내는 것의 뜻을 나눠요.
  • 업무 날짜, 지역 시각, 절대 시각을 구별하고 절대 시각은 UTC로 보내요.
  • 목록은 서버가 필터·정렬·페이지(또는 커서)를 처리해요. 건수와 목록이 같은 조건을 쓰는지 확인해요.
  • 변경은 버전 충돌과, 같은 명령이 다시 왔을 때의 중복 효과를 검토해요. cowork는 화면이 읽은 판본(expectedVersion)을 함께 보내고, 그사이 누가 먼저 저장했으면 409로 답해요.

로그인한 사용자와 그 사용자의 자원 접근 권한을 서버에서 검사해요. 접근 판정은 모듈의 판정자 한 곳이 맡고, REST·MCP·다운로드·알림·실시간 신호가 모두 같은 판정자에게 물어요. 조건이 여러 곳에 흩어지면 한 경로만 고쳐져서, 화면에는 안 보이는 대상이 알림으로 새어 나가요.

판정 응답
볼 수 없음 404. 있다는 사실도 알리지 않아요
볼 수는 있지만 이 동작의 권한이 모자람 403
닫히거나 보관된 대상을 고치려 함 409

같은 판정자가 대상 응답에 지금 사용자가 할 수 있는 일(can: { view, edit, manage })을 실어요. 화면은 권한을 다시 계산하지 않고 이 값으로 버튼을 보이거나 숨겨요.

  • 임시 업로드와, 그것을 업무 자원에 연결한 파일의 소유권·만료·권한을 나눠요.
  • 파일 이름과 확장자를 믿지 않고 크기·형식·경로를 검사해요.
  • 파일을 읽는 경로에서도 권한을 확인해요.

cowork는 브라우저가 사전 서명 주소로 저장소에 바로 올리고, 그 업로드를 소유 모듈의 명령이 자기 트랜잭션 안에서 연결해요(FileFacade.attach).

누가 무엇을 판정 표현
도메인 자기 업무 규칙 위반 메시지를 담은 순수 Java DomainRuleViolation
서비스 부재, 권한, 충돌 같은 유스케이스 오류 모듈 오류 코드를 가진 BusinessException
HTTP 경계 예외를 응답으로 바꾸기 공통 예외 처리기가 ProblemDetail과 상태 코드로

도메인은 HTTP 상태나 Spring 예외를 모르고, 공통 처리기가 도메인 규칙 위반을 400으로 바꿔요. 서비스의 오류는 모듈마다 application 루트에 둔 오류 코드 열거형 하나로 표현해요.

server/src/main/java/xyz/goraebap/cowork/module/file/application/FileErrorCode.java
@Getter
@RequiredArgsConstructor
public enum FileErrorCode implements ErrorCode {
FILE_UPLOAD_MISSING(HttpStatus.BAD_REQUEST, "올린 파일을 찾을 수 없습니다. 파일을 다시 올려 주세요"),
FILE_NOT_STORED(HttpStatus.BAD_REQUEST, "파일 업로드가 끝나지 않았습니다. 파일을 다시 올려 주세요"),
FILE_PICTURE_INVALID(HttpStatus.BAD_REQUEST, "사진을 읽을 수 없습니다. 다른 사진을 골라 주세요"),
FILE_TOTAL_EXCEEDED(HttpStatus.BAD_REQUEST, "파일은 모두 합쳐 10MB까지 올릴 수 있습니다");
private final HttpStatus status;
private final String message;
}

서비스는 판정한 자리에서 코드의 raise()로 예외를 만들어 던져요.

server/src/main/java/xyz/goraebap/cowork/module/file/application/FileService.java
if (upload == null || !upload.uploadedBy(uploaderId) || upload.expired(now))
throw FileErrorCode.FILE_UPLOAD_MISSING.raise();

오류 응답은 application/problem+json이에요. 공통 예외 처리기(GlobalExceptionHandler)가 예외를 ProblemDetail로 바꾸면서 오류 코드와 추적 번호를 더해요.

server/src/main/java/xyz/goraebap/cowork/shared/web/GlobalExceptionHandler.java
@ExceptionHandler(BusinessException.class)
ProblemDetail handleBusiness(BusinessException businessException, HttpServletRequest httpServletRequest) {
return toProblemDetail(businessException.errorCode(), businessException.getMessage(), httpServletRequest);
}
@ExceptionHandler(DomainRuleViolation.class)
ProblemDetail handleDomainRule(DomainRuleViolation domainRuleViolation, HttpServletRequest httpServletRequest) {
return toProblemDetail(
CommonErrorCode.COMMON_INVALID_REQUEST, domainRuleViolation.getMessage(), httpServletRequest);
}
// …
private static ProblemDetail toProblemDetail(
ErrorCode errorCode, String detail, HttpServletRequest httpServletRequest) {
ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(errorCode.status(), detail);
problemDetail.setInstance(URI.create(httpServletRequest.getRequestURI()));
problemDetail.setProperty("code", errorCode.code());
problemDetail.setProperty("traceId", MDC.get(TraceIdFilter.MDC_KEY));
return problemDetail;
}
필드 내용
status, title HTTP 상태와 그 이름
detail 사람이 읽을 설명. 업무 오류면 오류 코드의 문장이나 서비스가 넘긴 문장
instance 요청한 경로
code 안정된 오류 코드(FILE_UPLOAD_MISSING, COMMON_INVALID_REQUEST 등)
traceId 서버 로그에서 이 요청을 찾는 번호
errors 형식 검증에 실패한 필드 목록(field, message). 검증 실패일 때만

스택 추적과 비밀값은 응답에 넣지 않아요. 모든 예외를 400 하나로 뭉치지 않고, 부재·권한·충돌을 코드로 나눠 둬요.