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 루트에 둔 오류 코드 열거형 하나로 표현해요.
@Getter@RequiredArgsConstructorpublic 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()로 예외를 만들어 던져요.
if (upload == null || !upload.uploadedBy(uploaderId) || upload.expired(now)) throw FileErrorCode.FILE_UPLOAD_MISSING.raise();오류 응답의 모양
섹션 제목: “오류 응답의 모양”오류 응답은 application/problem+json이에요. 공통 예외 처리기(GlobalExceptionHandler)가 예외를 ProblemDetail로 바꾸면서 오류 코드와 추적 번호를 더해요.
@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 하나로 뭉치지 않고, 부재·권한·충돌을 코드로 나눠 둬요.