콘텐츠로 이동

코드 구조

서버는 모듈형 모놀리스예요. 프로그램은 하나로 배포하지만, 안쪽은 업무 단위의 모듈로 나누고 모듈 사이에는 공개 계약으로만 이야기해요. 서비스·큐·캐시를 따로 두는 일은 구체적인 요구와 운영 비용을 보고 정해요.

cowork의 기본 패키지는 xyz.goraebap.cowork이고, 그 아래를 기술 기반 shared와 업무 모듈 module로 나눠요.

  • 디렉터리server/src/main/java/xyz/goraebap/cowork/
    • ServerApplication.java
    • 디렉터리shared/ 업무를 모르는 기술 기반
      • 디렉터리config/
        • …
      • 디렉터리domain/
        • …
      • 디렉터리error/ 오류 코드와 예외
        • …
      • 디렉터리persistence/ DB 연결, jOOQ 바인딩
        • …
      • 디렉터리storage/ 파일 저장소
        • …
      • 디렉터리text/
        • …
      • 디렉터리web/ 예외 처리기, 현재 사용자, 목록 인자
        • …
    • 디렉터리module/
      • 디렉터리user/
        • …
      • 디렉터리file/
        • …
      • 디렉터리notification/
        • …
      • 디렉터리system/
        • …
      • 디렉터리seed/
        • …
      • 디렉터리realtime/
        • …
      • 디렉터리search/
        • …
      • 디렉터리mcp/
        • …
      • 디렉터리workspace/
        • 디렉터리project/
          • …
        • 디렉터리issue/
          • …
        • 디렉터리document/
          • …
        • 디렉터리richbody/
          • …
        • 디렉터리activity/
          • …

모듈은 단수 이름으로 두고, 안을 application · domain · infrastructure로 나눠요. 모듈 루트에는 다른 모듈이 쓰는 공개 계약(…Facade, …Spi, 이벤트)과 공개 값 타입만 둬요. 아래는 파일 모듈이에요.

  • 디렉터리module/file/
    • FileFacade.java 다른 모듈이 쓰는 공개 계약
    • AttachedFile.java 계약이 돌려주는 값
    • …
    • 디렉터리application/
      • FileController.java 요청 형식 검증, HTTP 변환
      • FileService.java 읽기·쓰기 유스케이스, 트랜잭션
      • FileQuery.java 화면 조회 포트
      • FileRequests.java HTTP 요청 타입
      • FileViews.java HTTP 응답 타입
      • FileErrorCode.java 이 모듈의 오류 코드
      • …
    • 디렉터리domain/
      • 디렉터리attachment/
        • Attachment.java
        • AttachmentRepository.java
      • 디렉터리upload/
        • PendingUpload.java
        • PendingUploadRepository.java
        • …
    • 디렉터리infrastructure/
      • JooqAttachmentRepository.java
      • JooqFileQuery.java
      • JooqPendingUploadRepository.java
      • …
역할 맡는 일
Controller 요청 형식 검증과 HTTP 변환
Service 피처의 읽기·쓰기 유스케이스, 트랜잭션, 도메인 조율
Domain 업무 불변식과 의미 있는 상태 바꾸기. 프레임워크에 기대지 않는 순수 Java
Infrastructure jOOQ 영속성, 조회, 외부 연동
flowchart LR
  controller["Controller<br/>FileController"]
  service["Service<br/>FileService"]
  domain["Domain<br/>PendingUpload"]
  repo["Infrastructure<br/>JooqPendingUploadRepository"]
  query["Infrastructure<br/>JooqFileQuery"]
  db["DB"]
  controller --> service
  service -- "쓰기: 업무 메서드" --> domain
  service -- "쓰기: save" --> repo
  service -- "읽기" --> query
  repo --> db
  query --> db

피처마다 …Service 하나에 읽기와 쓰기 메서드를 함께 둬요. 읽기와 쓰기는 서비스 클래스를 나누지 않고 처리 경로로 나눠요.

메서드 처리 경로
읽기 같은 피처의 조회 포트(FileQuery) → jOOQ 구현(JooqFileQuery) → 화면 응답 타입
쓰기 도메인 저장소에서 복원 → 업무 메서드와 불변식 검증 → 명시적으로 save

jOOQ에는 변경 감지가 없어서, 쓰기 메서드는 save를 빠뜨리지 않아요. 아래는 업로드를 준비하는 쓰기 메서드예요. 도메인 객체를 만들고(PendingUpload.create), 저장소에 저장하고, 응답 타입으로 돌려줘요.

server/src/main/java/xyz/goraebap/cowork/module/file/application/FileService.java
/** Records the upload and hands out where to send it; nothing is stored until the browser sends the bytes. */
@Transactional
public FileViews.UploadTicket prepare(CurrentUser user, FileRequests.Upload request) {
var upload = PendingUpload.create(
request.filename(),
request.size(),
user.id(),
clock.instant(),
request.purpose(),
ImageTraits.of(request.dominantColor(), request.width(), request.height()));
pendingUploadRepository.save(upload);
var presigned = objectStorage.presignUpload(
upload.storageKey(), upload.format().contentType(), upload.size(), UPLOAD_TTL);
return new FileViews.UploadTicket(
upload.id(), presigned.url(), presigned.method(), presigned.headers(), presigned.expiresAt());
}

현재 시각은 주입한 Clock에서 받아요(clock.instant()).

  • 읽기만 있는 서비스는 클래스에 @Transactional(readOnly = true)를 달아요.
  • 읽기와 쓰기가 함께 있으면 클래스에 달지 않고, public 메서드마다 읽기는 @Transactional(readOnly = true), 쓰기는 @Transactional을 달아요.
  • 함께 성공해야 하는 변경은 같은 트랜잭션에서 처리해요. 외부 호출, 파일, 메시지 전송은 DB 트랜잭션으로 되돌릴 수 없다는 점을 따로 다뤄요.
필요한 것 하는 방법
다른 모듈의 기능 그 모듈 루트의 …Facade를 불러요. 내부 application·domain·infrastructure 타입은 참조하지 않아요
다른 모듈에 구현을 요구 소유 모듈 루트에 …Spi를 두고 밖에서 구현해요. 인자로 넘겨받을 수 있으면 Spi를 만들지 않아요
다른 모듈의 표시 정보 부모 페이지를 정한 뒤 Facade로 묶어서 읽어요
다른 모듈의 값으로 검색·정렬·건수 그 화면의 SQL 조회에서 직접 읽어도 돼요. 조회 구현 안으로만 한정해요