Update API: PUT vs PATCH & Read 트랜잭션 분리(CQRS) 도입 논의

[GyunHeee]

배경

현재 API 설계/구현 과정에서 아래 2가지 의사결정이 필요합니다.

1. 리소스 수정 API를 PUT으로 할지, PATCH로 할지
2. "읽기(Read) 트랜잭션"을 분리(CQRS) 할지, 기존처럼 한 흐름으로 처리할지

팀 차원의 기준을 정해두면 이후 일관된 설계에 도움이 될 것 같아 Discussion을 남깁니다.

1. 수정 API: PUT vs PATCH

✅ 제안: 기본은 PATCH 사용, 전체 교체가 필요한 경우에만 PUT 허용

이유

실제 수정은 대부분 “일부 필드만 변경”하는 경우가 많음

PUT은 리소스 전체 교체 의미이기 때문에
→ 누락된 필드를 어떻게 처리할지 명확한 규칙이 필요

PATCH는 “요청에 포함된 필드만 변경”이라는 의미가 명확하여
부분 수정이 많은 현재 구조에 더 적합하다고 판단됩니다.

권장 설계 규칙

PATCH /resource/{id}
→ 부분 수정 (기본 update 방식)

PUT /resource/{id}
→ 전체 리소스 교체가 명확한 경우에만 사용

PATCH 설계 시 고려사항

• 요청 DTO에 포함된 필드만 업데이트
• null 허용 여부 정책 정의 필요
• null = null로 변경인지?
• null은 무시할 것인지?
• Validation은 “변경되는 필드에 대해서만” 적용

최종 제안

Update API는 기본적으로 PATCH로 통일
정말 “전체 교체 의미”가 필요한 도메인에서만 PUT 허용

2. 읽기 트랜잭션 분리 여부 (CQRS 도입)

✅ 제안: CQRS-lite 형태로 읽기/쓰기 분리 도입
(완전한 CQRS가 아닌, 서비스 레벨에서의 책임 분리)

이유

조회 로직이 점점 복잡해질 경우:

읽기

• DTO projection
• join 최적화
• 검색/정렬/필터
• 캐싱 등 성능 중심 설계

쓰기

• 도메인 규칙
• 트랜잭션 일관성
• 엔티티 중심 로직

요구사항이 서로 달라지기 때문에
하나의 서비스에서 모두 처리하면 빠르게 복잡해질 가능성이 높습니다.

적용 방식 제안

초기부터 거창하게 분리하기보다는:
CommandService → 쓰기 전용
QueryService → 조회 전용 (DTO Projection 기반)
형태로 시작하는 CQRS-lite 전략 제안

적용 전략

조회 요구사항이 복잡하거나, 성능 고려가 필요한 도메인부터 우선 적용
단순 조회 도메인은 굳이 분리하지 않아도 됨
점진적 확장 전략이 좋은 거 같습니다.

결론

Update API는 기본 PATCH 채택 제안
읽기/쓰기 분리(CQRS-lite) 도입 제안

팀 논의 요청

PATCH 기본 통일에 동의하는지
CQRS를 전체 도메인에 즉시 적용 vs 점진적 적용 중 어떤 전략이 좋은지
null 처리 정책은 어떻게 가져갈지

의견 부탁드립니다 🙏

[milk-stone]

1. PATCH 기본 통일에 동의합니다!
2. CQRS-lite 제안 너무 좋습니다! 방향성에 적극 동의합니다.
   우선은 '읽기용 서비스(Query)와 쓰기용 서비스(Command)를 클래스 레벨에서 분리한다'는 구조적 규칙 정도만 팀 컨벤션으로 정하는 것을 제안합니다.
   처음부터 DTO Projection이나 캐싱을 강제하기보다는, 일단 분리된 구조로 빠르게 기능을 구현해 보고, 추후 테스트나 실제 운영 과정에서 병목이 발견될 때 점진적으로 성능 최적화를 적용해 나가는 방향이 어떨까요?

(추가)

• https://github.com/knu-80/knu-server/pull/38/changes
  두현님 PR의 BoothReader - BoothService 로 분리한게 CQRS 패턴의 일종이라고 이해해도 되는걸까요? 클래스 네이밍 규칙도 정하면 좋을 것 같아 여쭤봅니다.

[hyun7586]

좋은 제안 감사합니다.

1. 저도 PATCH 통일에 동의합니다. 글에 남겨주신 것처럼 전체 교체가 필요한 경우에만 PUT을 허용하는 게 좋을 것 같습니다.

2. 말씀해 주신 CQRS-lite 제안도 동의합니다. 우석님이 남겨주신 것처럼 제가 올렸던 PR에도 조회용 service 객체 분리를 반영하긴 했습니다. 전 단순히 조회+예외처리 코드의 중복을 줄이고 다른 도메인에서의 재사용을 위해 Reader Service 객체만 만들어서 사용했었습니다.

하지만 견희님이 말씀해 주신 것처럼 CQRS-lite 전략으로 모든 도메인에 대해 QueryService, CommandService로 분리하도록 컨벤션을 정하는 게 좋을 것 같습니다.