Man vs Ai

[Spotify Web API 7편] 배포 방법 구상

MvA — Mon, 15 Jun 2026 06:42:43 +0900

(글 오른쪽 하단 화이트/다크모드 전환 버튼을 통한 화이트모드 사용 권장합니다.)

BandFeed 서비스에서 제공하는 기능 및 배포 시 사용할 인프라 설계 의사결정 과정을 정리했습니다.

제공하는 기능

아래 더보기 토글은 지금까지 구현된 기능입니다.

(변경사항이 있을 때마다 업데이트할 예정)

( 26.06.15 기준 )

인증/공통 (Gateway)

JWT 기반 인증 필터 — /api/users/signup, /api/users/login 제외 모든 요청 토큰 검증
인증된 사용자 ID를 X-User-Id 헤더로 다운스트림 서비스에 전파
서비스별 라우팅 (user/band/wiki/chat)

User Service — 회원/팔로우

회원가입, 로그인(access/refresh 토큰 발급)
내 프로필 조회/수정, 비밀번호 변경, 회원 탈퇴
타 사용자 프로필 조회
팔로우 / 언팔로우, 팔로워·팔로잉 목록 조회

Band Service — 밴드 & 타임라인

밴드 생성/조회(목록·페이지네이션)/수정/삭제 (리더 권한 검증)
밴드 멤버 초대/조회/추방, 리더 권한 위임
밴드 타임라인 게시글 CRUD + 페이지네이션
내가 속한 밴드들의 게시글을 모은 피드(/feed)
게시글 댓글 작성/조회/삭제 (작성자 권한 검증)

Wiki Service — 곡/악기 위키

Spotify 검색을 통한 곡 검색 및 등록
곡 상세 조회
곡별 악기 구성(난이도, 노트) 추가/조회/삭제
곡에 대한 위키 게시글 CRUD + 페이지네이션(최신/오래된 순)
Spotify API 실패 시 502 예외 처리

Chat Service — 1:1 채팅

채팅방 생성(또는 기존 방 재사용)/목록/상세/멤버 조회
메시지 전송/조회(페이지네이션), 읽음 처리
WebSocket(STOMP, /ws)을 통한 실시간 메시지 송수신

⚙️ 공통 인프라

Eureka(서비스 디스커버리), Config Server(중앙 설정 관리, GitHub 기반)
공통 에러 처리(BusinessException/ErrorCode 패턴), Soft delete(created/updated/deleted 감사 칼럼)
Flyway 기반 DB 스키마 마이그레이션 (이번에 추가)
Kafka, Redis, 모니터링(Prometheus/Grafana/Loki/Zipkin, monitoring profile)

배포 방식 의사결정 과정

초기 인프라 설계도

아래 더보기 토글은 Claude가 초기 인프라 설계도를 지적한 내용입니다.

원래 다이어그램에서 ECS EC2 launch type임을 알아보기 어려웠던 핵심 이유는 3가지입니다.

1. "EC2 instance contents" 박스가 ECS와 무관한 독립된 호스트처럼 보임

private subnet 안의 EC2 박스가 ECS와 연결되어 있다는 표시 없이 그냥 단독으로 컨테이너들을 담고 있는 박스로 그려져 있었음
이러면 "이 EC2는 누가 관리하는가? docker-compose로 사람이 직접 띄운 건가, ECS가 관리하는 건가"가 그림만으로는 구분 안 됨

2. ECS↔EC2 사이의 양방향 화살표에 라벨이 없음

화살표만 있고 "이게 무슨 관계냐"(스케줄링 명령? 이미지 전달? 데이터 흐름?)가 안 적혀있어서, 처음에 사용자분이 "ECS가 EC2로 이미지를 push 한다"라고 오해하신 것처럼 데이터 흐름으로 잘못 읽힐 여지가 컸음

3. ECS와 ECR이 나란히, 같은 톤의 박스로 그려져서 "EC2가 의존하는 외부 리소스" 묶음처럼 보임

RDS/ElastiCache 같은 "EC2가 사용하는 데이터 저장소"와 시각적으로 동급으로 배치되어, ECS도 그런 "리소스"처럼 인식되기 쉬움
실제로는 ECS는 EC2를 관리하는 컨트롤 플레인이라 위계가 다름 (EC2가 ECS에 등록된 "일원"이라는 포함 관계)

어떻게 표현했어야 했나 (제가 v2에서 수정한 방식)

EC2 박스를 **"Private subnet — EC2 (ECS 컨테이너 인스턴스)"**처럼 라벨링해서, 이 EC2가 ECS 클러스터의 멤버임을 명시
ECS↔EC2 화살표에 "스케줄링·에이전트" 같은 라벨을 붙여서 컨트롤 플레인 관계임을 명확히
ECR pull은 "ECS가 직접 pull"이 아니라 **"EC2 위 ECS 에이전트가 pull"**이라는 점이 드러나도록, 가능하면 화살표 출발점을 EC2 박스 쪽에 두는 것이 더 정확함 (지금 v2는 ECS→ECR로 그려서 약간 단순화되어 있음 - 더 엄밀하게는 EC2 박스에서 ECR로 화살표를 그리는 게 맞음)

요약하면: "포함 관계(EC2가 ECS 클러스터의 일원)"와 "컨트롤 플레인 vs 데이터 플레인"을 구분해서 표현했어야 오해가 없었을 것입니다.

이때 컨트롤 플레인, 데이터 플레인이란?

일반적인 네트워크/시스템 설계에서 쓰이는 개념인데, ECS 맥락에 맞춰 설명하면:

Control plane (제어 영역)

"무엇을 어떻게 할지 결정하고 지시하는" 부분
실제 트래픽이나 데이터가 흐르는 경로가 아니라, 설정/명령/상태 관리가 오가는 경로
ECS 예시: "이 task definition대로 컨테이너 2개를 이 EC2에 띄워라", "이 컨테이너가 죽었으니 재시작해라" 같은 결정과 지시를 내리는 AWS ECS 서비스 자체

Data plane (데이터 영역)

"실제로 일이 일어나는" 부분
사용자 요청, 이미지 파일, DB 쿼리 등 실질적인 데이터/트래픽이 오가는 경로
ECS 예시: 사용자 HTTP 요청이 ALB→Gateway→각 서비스로 흐르는 것, EC2의 ECS 에이전트가 ECR에서 실제 이미지 바이너리를 다운로드하는 것

다이어그램 맥락에서 왜 중요한가

"ECS → EC2" 화살표: control plane (ECS가 "이 컨테이너 띄워"라고 명령만 내림, 바이트 자체가 ECS를 거쳐가는 건 아님)
"EC2 → ECR" 화살표: data plane (실제 이미지 데이터가 이 경로로 다운로드됨)

이 둘을 같은 종류의 화살표/같은 톤의 박스로 그리면, 보는 사람은 "ECS가 이미지를 받아서 EC2에 전달해 주는 하나의 파이프라인"처럼 오해하기 쉽습니다. 실제로는:

ECS는 "누가, 언제, 어디서 실행될지"만 결정하고
실제 이미지 다운로드(데이터 이동)는 EC2의 에이전트가 ECR과 직접 수행

그래서 둘을 분리해서 그리면(예: control plane은 점선+회색, data plane은 실선+컬러), "ECS가 직접 이미지를 옮긴다"는 오해를 막을 수 있습니다.

인프라 설계도 수정 방안

: 1개의 개발계와 3개의 운영계(v1, v2, v3)로 나눠서 구성 및 마이그레이션 예정

1. 개발계

빠른 개발 및 테스팅을 위해 도커 컴포즈 네트워크를 사용한다.
로컬환경에서 각 서비스를 띄운다.

2. 운영계 - v1

도커 컴포즈 스택이 EC2에서 그대로 실행된다.

장점: 단일 EC2 구조로 배포비용이 적고, 테스트가 용이하다.

- t3.small 기준 월 15$ ~ 20$

- 배포환경에서 기능 테스트 쉬움.

단점: 향후 서비스 확장 시 구조적 한계로 관리하기 어렵다.
- SPOF, 스케일링 한계, EC2 한 개에 트래픽 집중 -> 부담, 무중단 배포 어려움.

3. 운영계 - v2

ECS는 컨테이너를 어디서 실행할지 스케쥴링하는 오 케스트레이터이다.
동작 방식은 2가지가 있다.

EC2 launch type
1. EC2 인스턴스 위에 ECS 컨테이너 에이전트를 설치
2. EC2를 ECS 클러스터 인스턴스로 등록
3. ECS가 도커 컨테이너를 이 EC2에 띄우라고 명령
4. ECS 에이전트가 ECR(내부적으론 S3)에서 도커 이미지를 다운로드 및 실행
Fargate : 서버리스 구조, EC2 자체가 없음.

위 사진은 그중 EC2 launch type 방식이다.

배포 단위는 ECS task definition이다.

ECS가 새 이미지로 task를 교체하여 배포한다.

참고로 ECR은 실제 도커 이미지는 내부적으로 S3에 저장하고 관리한다.
따라서 EC2에서 ECR로부터 이미지를 다운로드하려고 하면
사실 S3에서 도커 이미지를 다운로드한다.

ECS는 스케줄링만 함. (제어 plane)
실제 이미지 pull은 EC2가 함. (데이터 plane)

ECS Agent → ECR → S3(레이어 실제 저장)

4. 운영계 - v3

ECS Fargate 방식을 적용하는 설계도이다.

- 트레이드오프

비교 항목	v2 — EC2 Launch Type	v3 — ECS Fargate
인프라 관리	개발자가 OS/Docker 직접 관리 (높은 공수)	AWS가 관리형으로 대행 (공수 제로)
네트워크 모드	Bridge 또는 호스트 포트 공유 방식 중심	`awsvpc` 모드 강제 (Task별 고유 IP 부여)
보안 그룹 범위	EC2 인스턴스 단위 (컨테이너간 공유)	개별 컨테이너(Task) 단위 격리 가능
스케일링 구조	EC2 ASG + ECS Task 이중 설계 필요	ECS Task 단일 오토스케일링으로 단순화
비용 효율성	자원을 꽉 채워 쓰는 대규모 상시 운영에 유리	트래픽 변동이 크거나 인프라 자동화에 유리
구성 난이도	높음 (EC2·Task 이중 스케일링 및 초기 에이전트 설정 필요 / SSH 트러블슈팅은 용이)	낮음 (서버 관리 생략 및 Task 단일 스케일링으로 단순함 / 모니터링 시스템 구축 필요)

프런트 배포 방식

백엔드를 운영계 v1으로 배포한다고 가정.

옵션 1. Nginx 컨테이너 방식

- 기존 EC2의 docker-compose에 Nginx를 추가해 React 빌드 파일을 서빙하는 방식

장점: 관리가 하나로 끝나 단순, 도메인이 같아 CORS 설정 필요 x
단점: 안 그래도 무거운 v1 EC2 자원(Spring, DB 등)을 공유하므로 부하 커짐.
서버가 터지면 프런트도 같이 죽음.

옵션 2. S3 + CloudFront 방식

- React 빌드 파일을 S3에 올리고, 글로벌 CDN인 CloudFront를 전면에 세워 배포하는 방식

장점: EC2 자원을 전혀 쓰지 않아 API 연산에 집중 O
백엔드가 다운되어도 프런트 화면은 정상적으로 유지.
프리티어 범위 내에서 비용도 거의 무료.
단점: 도메인이 찢어져 CORS 설정 필요
배포 파이프라인(CI/CD)을 프런트/백엔드 각각 따로 구축해야 함.

따라서 옵션 1로 사용하다가 옵션 2로 마이그레이션 할 예정이다.

옵션2로 배포하면, 백엔드를 어떤 식으로 배포해도 상관없다.
프론트와 백엔드 사이의 요청 경로만 그에 맞게 맞춰주면 된다.

최종 배포 방법

백엔드는 단일 EC2 + dokcer-compose 네트워크 방식 + ECR 구조로 배포한다.

프론트는 위 docker-compose에 Nginx 서비스를 추가한 Nginx 컨테이너 방식으로 배포한다.

- 위 구조를 채택한 이유

저렴한 비용
쉬운 구성 난이도

3개의 인프라 서비스와 4개의 비즈니스 서비스를 하나의 EC2에 올려야 한다.
따라서 EC2 인스턴스는 메모리 용량이 8GB인 t3.large를 선택했다.
-> 현재 AWS에서 제공하는 EC2 프리티어 모델 중 메모리 8GB 인 것은 m7i-flex.large 밖에 없어서 이 모델로 선택했다.

그 외 모니터링 스택 배포는 여유 메모리를 계산하여 진행(EC2 추가 구입, 일부만 배포 등)한다.

그 외 설계(ECS Fargate, CloudFront 등)는 로드맵에 개선사항으로 남겨뒀다.

[유시민의 글쓰기 특강] 5장 못난 글을 피하는 법

MvA — Fri, 12 Jun 2026 22:29:36 +0900

5장 후기

지난 4장까지는 '글을 잘 쓰는 법'에 대해 다뤘는데
이번 5장에서는 '잘 쓴 글과 못쓴 글을 구별하는 법'에 대해 다룰 겁니다!

글을 잘 쓰려면 독해력과 어휘력이 필요하고 많이 읽어야 늘었다.

하지만 세상엔 좋은 글만 있는 게 아니다.

못난 글을 읽으면 글쓰기 실력이 더 떨어질 수도 있다.

따라서 5장에서는 못난 글이 왜 못났는지 알아보는 감각을 배울 수 있다.

못난 글 알아보기

이 글이 못난 글인 지 어떻게 알아볼 수 있을까?

텍스트를 소리 내어 읽었을 때,
말하기 불편하고 이해하기 어렵고 듣기에 좋지 않으면 못난 글이다.

이 책의 3장에서 "말이 글보다 먼저다."라는 말이 나왔다.

말은 2종류가 있다.

입말: 생각과 감정을 소리로 표현한 것
글말: 생각과 감정을 문자로 표현한 것

이때, 말과 글 중에는 말이 먼저이므로 말로 해서 좋아야 잘 쓴 글이다.

아래에서 못난 글의 특징을 살펴보자.

1. 남의 나라 말 오·남용

어려운 한자말
- 육상에서의, 통합적으로, 이원화되어 등
일본말 조사와 수동태
- -에서의, -적, -화, -되어 등

한자나 일본말을 무조건 쓰지 말라는 것은 아니다.
하지만 남용하면 문제가 있다.

- 한자말 남용 예시
[원문]

'경제성장' 즉 자본주의 발전을 위하여 '비효율적인' 각종 민주제도를
폐지시키려 하는 사상적 경향을 우리는 파시즘이라 부릅니다.

[고친 글]

'경제성장' 즉 자본주의 발전을 위하여 '비효율적인' 민주제도를
없애버리자는 사상을 우리는 파시즘이라 합니다.

밑줄 친 곳은 변경될 곳이다. 한자말을 아예 안 쓰는 게 나을 수 있단 걸 보여준다.

- 일본말 오용 예시

'나의 살던 고향은 꽃 피는 산골'이라는 문장은 사실 '내가 살던 고향은 꽃 피는 산골'이 되어야 한다.
'으로의', '에로의', '에서의', '으로부터의', '에 있어서의'와 같이 '의'를 겹쳐 쓴 토씨도 모두 우리 말법에 어긋난다.

참고로 '토씨'는 조사 하나란 의미이다.
위의 예시는 사실 일본말 'の'를 우리말 조사 '의'로 옮긴 것인데,
일본말로 쓰면 자연스럽지만 우리말은 그런 식으로 토씨를 사용하지 않는다.

또한 우리말에는 피동문이 드물다.

하지만 일본말이나 영어를 그대로 우리말로 옮기면서 따라 쓰는 경우가 있다.

반드시 피동문을 써야 정확하게 의미를 전달할 수 있을 때만 사용한다.

'보여지다', '되어지다', '모여지다', '두어지다', '보아지다' 등 은 자동사를 피동형으로 만든 것으로 잘못된 표현이다.

보여지다 -> 보이다
되어지다 -> 되다
모여지다 -> 모이다
보아지다 -> 보이다

티스토리의 맞춤법 검사 기능

여담이지만 위 사진은 티스토리의 맞춤법 검사 기능이 동작중인 것인데, '보이다'라는 말이 철자 오류라고 나온다.

'키워지다', '다뤄지다', '두어지다'는 잘 안 쓰는 표현으로, 대부분의 상황에서 능동형으로 쓰는 게 자연스럽다.

부모님에 의해 키워졌다. -> 부모님이 키우셨다.
이 문제가 다뤄진다. -> 이 문제를 다뤘다.
책이 책상 위에 두어졌다. -> 책을 책상 위에 두었다.

2. 단어, 문장 오·남용

독자가 이해하기 어려운 단어 사용
서양말의 완료시제 사용
추상명사에 복수형 사용
분명한 의도가 없는 복문 사용

우리말은 완료시제가 없다. 그런 것이 없어도 의사소통엔 아무 문제가 없다.

어제 어머니를 만났었다. -> 어제 어머니를 만났다.
얼마 전 고향을 방문했었다. -> 얼마 전 고향을 방문했다.

또한 서양말은 주어가 단수냐 복수냐에 따라 동사 어미가 달라지지만

우리말에선 복수를 분명하게 드러내야 할 때가 아니면 사용하지 않는다.

방법들을 찾아야 한다. -> 방법을 찾아야 한다.

'방법'과 같은 추상명사에 복수형을 사용할 필요는 없다.

작가는 복문보단 단문 사용을 권한다.

복문은 한 문장에 주어와 술어가 둘 이상인 문장이다.
단문은 한 문장에 주어와 술어가 하나인 문장이다.

복문은 무엇인가를 강조하고 싶을 때

단문은 뜻을 정확하게 표현하고 싶을 때 사용한다.

쉽게 말해서 특별한 의도가 없다면 단문 사용이 좋다.

- 복문을 단문으로 바꾼 예시

[원본]

1894년 9월 어느 날, 프랑스의 참모본부 정보국은 프랑스 주재 독일대사관의 우편함에서 훔쳐낸 한 장의 편지를 입수했다.

[고친 글]
1894년 9월 어느 날, 프랑스 육군 참모본부 정보국 요원이 프랑스 주재 독일대사관의 우편함에서 편지 한 장을 훔쳐냈다.

원본에는 술어가 2개이므로 복문이다.
- 훔치다

- 입수하다
또한 주어가 누군 지 명확하지 않았다.

고친 글에선 주어를 '정보국 요원'으로 명확히 하고
술어를 '훔치다' 한 개만 사용해서 전하고자 하는 바를 분명히 했다.

[고친 글]을 한 번 더 손보면 다음과 같다.

[개정판 글]
사건은 1894년 9월에 일어났다. 프랑스 육군 참모본부 정보국 요원이 프랑스 주재 독일대사관 우편함에서 편지 봉투를 하나 훔쳤다.

먼저 긴 문장을 두 개의 단문으로 나눴다.
그리고 불필요한 조사를 덜어냈고
글의 분위기에 맞게 자연스러운 우리말로 바꿨다.

3. 거시기 화법

상황에 꼭 맞는 단어를 선택해야 한다. 이는 어휘가 풍부해야 가능하다.
'뜻이 불분명해서 아무 곳에나 넣어도 되는 단어'는 쓰지 말아야 한다.

다음은 책에 나온 낚시터 밥집 사장님의 대화 내용이다.

"오늘 거시기가 좀 거석 해서.. 많이 거시기하긴 거슥할 텐데...
그래도 잘 거시기해서 거슥하면 거시기하긴 할 거여!"

낚시를 많이 다니는 손님들은 다음과 같이 이해할 수 있다.
"오늘 날씨가 안 좋아서 잘 잡히진 않을 테지만, 자리를 잘 잡으면 손맛은 볼 수 있을 거야."
만약 오늘 날씨가 좋았다면 또 다르게 해석된다.
"오늘 바람이 많이 불어서 힘들 테지만, 자리를 잘 잡으면 그래도 몇 마리 잡을 수 있을 거야."

글을 쓸 때는 이런 화법을 지양해야 한다.
글에서는 '거시기'가 '부분'으로 표현될 수 있다.
그 외에도 '뜻이 불분명해서 아무 곳에나 넣어도 되는 단어'는 조심해야 한다.

옷의 마무리 부분이 아쉽다 -> 옷의 마무리가 부실한 점이 아쉽다.
불빛이 새는 부분이 있다. -> 불빛이 새는 곳이 있다.
박음질한 부분들인데, 이런 부분 때문에 -> 박음질한 실이 지나간 곳인데, 이것 때문에
이런저런 부분들이 아쉽지만 -> 이렇게 마무리가 허술해서 아쉬운 점이 있지만

오해의 소지가 있는 표현을 적절한 단어로 손 본 것이다.

우리말의 무늬

뜻은 비슷한데 느낌이 다른 말이 많다.

책에선 '모양'을 예로 들었다.

모습
자태
꼴
꼬락서니
몰골

좋은 순서로 배열하면 자태 - 모습 - 모양 - 꼴 - 꼬락서니 -몰골이 된다.

예시를 한 가지 더 들면,
'죽었다'와 같은 표현으론 '별세했다', '돌아가셨다', '뒈졌다', '밥숟가락 놨다' 등이 있다.

'천사 같은 몰골'이나 '어머니가 뒈졌다' 등은 명백하게 잘못된 표현이다.
하지만 애매한 표현들이 있다.

사회적 논의를 시도하는 것이 가능하고 -> 사회적으로 논의하는 행위를 허용하고
정치적 숙고를 촉발시키고 -> 정치적 숙고를 북돋을 수

위 예시처럼, 상황에 맞는 표현을 사용해야 한다.

마무리

5장을 읽으며 내가 못난 글을 쓰고 있었다고 느꼈다.

특히 일본말 조사나 수동태 사용, 불필요한 완료시제 및 복수형 사용, 복문 남용을 많이 한 것 같다.

Claude Code vs Claude Cowork 차이점

MvA — Fri, 12 Jun 2026 00:05:28 +0900

요즘 현업에서는 개발시, AI사용이 당연시 되고 있다고 한다.
또한 채용시 클로드 Code 사용 경험을 필수 조건으로 제시하는 회사들도 봤다.

여기서 중요한 것은 클로드 Code 사용 경험이다. 클로드 Cowork가 아닌

그렇다면 클로드 Code와 Cowork 어떤 차이가 있을까?
지금부터 알아보자.

클로드(Claude)

클로드의 사용 방법은 3가지가 있다.

Chat
Cowork
Code

Claude Chat

왼쪽 상단에서 사용 방식을 고를 수 있다. 기본적으로 Chat으로 설정된다.

Claude Cowork

클로드 Cowork는 기본적으로 샌드박스 위에서 동작한다.

다시말해, 가상환경에서 동작하기 때문에 클로드의 오동작이나 에러 및 해킹상황에서 비교적 안전하다.
또한 멀티태스킹에 능하고 각종 MVC를 연결한 문서작업에 능하다.

하지만 가상환경에서 동작하는 만큼 내 코드의 테스트나 빌드를 직접 할 순 없다.
그리고 내 PC와 직접적으로 맞닿아 있지 않기때문에 Git 명령어를 제어하는 데 한계가 있다.
또한 매 작업마다 가상환경을 구성하기 때문에 Cluade Code에 비해 실행이 오래걸린다.

Claude Code

클로드 Code는 기본적으로 내 OS의 권한을 받아 동작한다.

그래서 직접적으로 내 컴퓨터의 디렉토리위에 있는 파일들에 접근할 수 있다.
또한 명령어를 직접 실행시킬 수 있다.

그렇다보니 클로드 Cowork의 단점을 상당부분 커버한다.

직접적인 코드 테스트 및 빌드 불가
Git 명령어 제어불가
느린 실행시간

또한 컴파일 에러나 런타임 예외 발생 시, 로그를 실시간으로 읽어서 원인을 파악하고 스스로 코드를 수정할 수 있다.

하지만 Cowork와 달리 한 번에 하나씩 처리하기떄문에 멀티태스킹의 한계가 있다.
또한 클로드 Code 오작동 및 에러 발생 시 실제 로컬 OS 환경 오염 및 자료 손실 위험이 있다.
그리고 문서작업 면에서는 내장 도구가 부족해서 Cowork에 비해 성능이 떨어진다는 평가가 있다.

따라서, 개발시엔 속도가 빠른 클로드 Code를
문서작업엔 다양한 도구를 활용한 대규모 작업을 위한 클로드 Cowork를 사용하면 좋다.

또한 파견근무 및 금융권 등 보안 정책을 고려하면 클로드 Cowork가 선택지가 될 수 있다.

[유시민의 글쓰기 특강] 4장 전략적 독서

MvA — Thu, 11 Jun 2026 22:51:45 +0900

이번에는 책 '유시민의 글쓰기 특강' 4장 내용입니다!

1장~3장 내용 요약

1장

모든 표현은 결국 '생각'에서 나온다.
생각을 잘해야 '논증'도 잘한다.

- 논증을 잘하는 규칙 3가지

주장과 취향고백을 구별하라
주장은 반드시 논증한다.
처음부터 끝까지 글의 주제에 집중하라

2장

- 글쓰기를 잘하기 위한 철칙 2가지

많이 읽어라
많이 써라

이때, 철칙이란 '바꾸거나 어길 수 없는 중요한 법칙'이다.

글쓰기 연습은 '발췌 요약'부터 해봐라.
악플을 겁내지 말고 글을 보여주고 피드백을 수용해라.

3장

독해력을 늘리기 위해선 결국 '독서'를 많이 해야 한다.

번역서도 '우리말 글'이다. 따라서 우리말다운 문장으로 써야 한다.
또한 글을 쓸 때는 말하듯이 써라.

말보다 글이 먼저다.
생각을 담는 것은 언어다.

따라서!

좋은 생각(언어)이 좋은 말하기를 만들고
좋은 말하기가 좋은 읽기를 만든다.
좋은 읽기가 좋은 쓰기를 만든다.

이번 챕터(4장)

이번 4장의 키워드는 '어휘력'이다.

작가는 사람의 어휘력은 지식수준과 비례한다고 한다.
어휘를 많이 알아야 정확한 문장을 구사할 수 있다는 것이다.

어휘력을 늘리는 방법 역시 많이 읽는 것이다.

3장에서도 독해력을 늘리는 방법으로 많이 읽는 것을 얘기했다.

그렇다면 단순히 많이 읽으면 글을 잘 쓰게 될까?

이번 4장에서는 그에 대한 답을 다룬다.

독해란

먼저 독해란 텍스트의 한계와 오류를 찾아내거나 텍스트를 다른 맥락에서 해석하는 작업을 포함한다.
즉, 비판적 사고를 가지고 책을 읽어야 독해력이 는다는 뜻이다.

비판적 사고란

아래는 비판적 사고의 예시이다.

원문)
원자력은 탄산가스에 의한 온실효과를 줄일 수 있는 깨끗한 에너지이며, 또한 발전 단가도 석유나
액화가스에 비하면 거의 반값에 해당하는 저렴한 에너지이다.

고친 글)

원자력은 탄산가스에 의한 온실효과를 줄일 수 있는 깨끗한 에너지이다. 또한 발전 단가도 석유나
액화가스에 비하면 거의 반값에 해당하는 저렴한 에너지이다.

차이점은 중간에 한번 문장을 끊어준 것뿐이다.
한 문장에 하나의 개념만 담는 것의 중요성을 보여주려 한 예시다.

이때 평소 나는 가독성이 좋은 글에 대해 많이 했는데
독자 입장에서 한 문장에 여러 개념이 들어가면 어느 부분에 포인트를 두어 읽어야 할지 어려울 거라 생각했는데,
이 책에서 그 부분을 잘 짚어준 것 같다.

하지만 작가는 이 글은 아직도 우리말다운 표현이 아닌 부분 등 고칠 부분이 있다고 했다.
만약 이 글의 앞뒤 문장을 서로 다른 형태로 만든다면, 더욱 분명하고 자연스러운 글이 된다고 한다.

개선한 글)
원자력은 탄산가스를 내뿜지 않는 깨끗한 에너지여서 온실효과를 줄일 수 있다.
발전 단가도 저렴해서 석유나 액화가스의 반밖에 들지 않는다.

그리고 이 글을 적은 사람이 전문성이 있는 사람일지라도
이 글의 정보가 사실인지에 대한 비판적 사고는 필요하다고 했다.

원자력이 탄산가스보다 온실효과면에서 깨끗한가?
발전 단가가 저렴한 것은 사실인가?

이것이 독해를 하는 방법이라고 한다.
글의 이해를 넘어 문제점과 한계를 탐색해야 한다.
나아가 그 문제점이나 한계의 출처는 어디인지까지도

글쓰기 능력에 도움을 주는 책의 기준

독서를 함으로써 지식을 배우며 어휘를 익히고
독해를 함으로써 문장을 익힌다.

Q: 단순히 많이 읽으면 독해력이 좋아질까?

A: 그렇다.

하지만! 글쓰기 능력을 기르고 싶다면 그에 맞는 책을 읽는 게 좋다.
어떤 책이냐에 따라 배우고 익히는 어휘와 문장의 양과 질이 다르기 때문이다.

그럼 책을 고르는 기준은 무엇일까?

인간, 사회, 문화, 역사, 생명, 자연, 우주를 이해하는데 꼭 필요한 개념과 지식을 담은 책
정확하고 바른 문장을 구사한 책
지적 긴장과 흥미를 불러일으키는 책

즉, 다양하고 양질의 어휘를 접할 수 있고 정확한 문장을 배울 수 있고
즐거운 마음으로 읽을 수 있는 책이다.

작가님은 여러 책을 추천하셨는데
그중 관심 가는 것을 아래에 <책제목>, 작가명, (옮긴이명), 출판사 순으로 적었다.

<자유론>, 존 스튜어트, 서병훈 옮김, 책세상
주제: 어떤 국가나 사회가 개인의 자유를 제한하는 것이 정당한가?
고른 이유: 자유라는 어려운 주제를 최대한 쉬운 단어들로 이해하기 쉽게 적었다고 해서 관심이 갔다.
내 글의 방향성 역시 '모든 사람이 이해할 수 있는 글'이다.
글이라고 함은 결국 독자가 이해해야 의미가 있다고 생각하기 때문이다.
그런 의미에서 글 작성 시 도움이 될 것 같다.
<만들어진 신>, 리처드 도킨스, 김영사
주제: 우주는 누가 만들었나? 신이 인간을 만들었나, 인간이 신을 만들었나? 어떻게 증명할 수 있나?
인간은 종교의 도움 없이도 삶에 필요한 도덕을 세울 수 있는가?
신이 있는 세상과 없는 세상 가운데 어느 쪽이 더 희망적인가?
고른 이유: 무신론자지만 신이 인간사회에 미치는 영향력과 종교에 대해 철학적으로 생각해 볼 기회가 될 수 있을 것 같았다.
<정의란 무엇인가>, 마이클 샌델, 김영사
주제: 정의는 무엇이며, 실현하기 위해선 어떤 철학적·도덕적 원리에 의지해야 하는가? 법의 제도가 정의 원칙을 어떻게 얼마나 실현/침해하고 있는가? 이념이 대립하는 상황에서 최대한의 정의를 실현하는 방법은 무엇인가?
고른 이유: 일상생활 속에서, 정의에 관해 생각해 볼 일이 많이 없었는데, 좋은 기회가 될 것 같았다.
<불확실성의 시대>, 존 케네스 갤브레이스, 홍신문화사
주제: 고전파 경제학자들의 인류의 물질적 풍요라는 예언은 왜 실현되지 않았는가?
우리의 정치 체제는 거대 법인기업이 지배하는 현대 자본주의 체제를 민주적으로 제어할 수 있는가?
고른 이유: 주식에 관심이 있는데, 빅테크와 같은 거대 기업들이 지배하는 현대사회에 공감이 가서 미래에 대한 견문을 넒힐 수 있을 것 같았다.
<유토피아>, 토머스 모어, 서해문집
주제: 공공의 선과 사회적 정의를 실현하기 위해 신분과 계급과 사유재산이 없고 모든 사람이 땀 흘리며 노동하는 사회를 만드는 것은 가능한 일인가? 만약 가능하다면 우리는 어떤 원리 위에서 사회제도를 만들어야 하는가?
고른 이유: 애니메이션 '유토피아'를 재밌게 보기도 했고 유토피아를 주제로 하는 많은 창작물들을 봐왔다.
이 책을 읽으면 나중에 관련 작품들을 볼 때 더 깊은 사고를 할 수 있을 것 같았다.

마무리

결국 독해력과 어휘력은 많이 읽어야 기를 수 있다.

좋은 생각이 좋은 말하기 능력을 만들고
좋은 말하기가 좋은 읽기 능력을 만들고
좋은 읽기가 좋은 쓰기 능력을 기른다고 했었다.

여기에 더해 이 모든 것을 더욱 향상해 주는 것이 바로 독해력과 어휘력인 것 같다.

비판적 사고를 바탕으로 '독해'를 하고,
풍부한 어휘력을 바탕으로 글을 써야 정확하게 문장을 구사할 수 있다.

나아가서 독자의 입장에서 글을 바라보아 한 문장에 하나의 개념만을 담는다면, 글을 더욱 분명하게 할 수 있다.

[유시민의 글쓰기 특강] 3장 책읽기와 글쓰기 후기

MvA — Thu, 11 Jun 2026 05:29:55 +0900

오늘은 책 유시민의 글쓰기 특강 3장 후기입니다!

1~3장을 읽어보니 책의 흐름이 느껴져서, 이전 내용을 계속 기억하면 좋을 것 같아서!
항상 각 장에서 제일 중요한 내용을 요약하고 시작하려고 합니다.

(글의 오른쪽 하단 버튼으로 화이트/다크모드 전환이 가능합니다.)

내용 복기

1장

모든 표현은 결국 '생각'에서 나온다.
생각을 잘해야 '논증'도 잘한다.

- 논증을 잘하는 규칙 3가지

주장과 취향고백을 구별하라
주장은 반드시 논증한다.
처음부터 끝까지 글의 주제에 집중하라

2장

글은 문학적인 글과 논리적인 글로 나뉘는데,
비교적 재능의 영향을 덜 받는 논리적인 글의 경우 충분히 노력하면 잘 쓸 수 있다.

- 글쓰기를 잘하기 위한 철칙 2가지

많이 읽어라
많이 써라

이때, 철칙이란 '바꾸거나 어길 수 없는 중요한 법칙'이다.

처음 글쓰기를 연습할 때는 '발췌 요약'부터 해라.
글을 많이 안 써본 사람들은 글의 첫 문장을 적는데 어려움을 느낀다.
이는 전체적으로 글을 구성해 봐야 하기 때문

악플을 겁내지 말고 글을 보여주고 피드백을 수용해라.

이번 챕터(3장)

독해력

먼저 2장에서 글쓰기를 연습할 때는 텍스트 요약부터 하라고 했는데,
요약을 잘하기 위해서는 독해력이 필요하다.
독해력을 늘리려면 결국 '독서'를 많이 해야 한다.

이는 곧 2장에서 말한 철칙 중 하나인 '많이 읽어라'에 포함되는 말이기도 하다.

모국어의 중요성

언어는 생각을 담는 그릇이다.
다중언어 능력을 보유하는 것보다 자기 머리로 생각하는 능력이 중요하다.

번역서가 불편한 이유는 무엇일까

언어를 번역하는 방법은 직역과 의역으로 나뉜다.
하지만 작가는 의역을 강력히 추천했다.

번역서 또한 누군가 읽는 글이다.
번역서의 문장이 우리말답지 않다면 원서의 분위기와 전하고자 하는 감정이 제대로 전달될 수 없다.
번역서든 아니든 우리말 책은 우리말다운 문장으로 써야 한다.

그래서 모국어를 잘해야 한다고 한다.

그리고 글을 쓸 때는 말하듯이 쓰는 게 좋다고 한다.
그 이유는 아래에서 설명하겠다.

말이 글보다 먼저다.

1장에서는 생각의 중요성에 대해서 언급했는데
3장에서는 말의 중요성에 대해 말한다.

아기는 말하는 법을 익히기 전에 말귀를 알아듣고 반응한다.

그래서 부모들이 아이에게 동화를 읽어주는 게 좋다고 한다.

말을 못 해도 동화를 '들음'으로써 듣기 능력을 키우고
들을 수 있게 되면 '말하는'법을 배우게 된다고 한다.
말할 수 있으면 문자를 '읽는' 방법을 배우게 되고
읽을 수 있다면 글을 '쓰는' 방법을 배운다.

따라서 아기의 뇌는 시간순으로 보면 감정(생각) - 듣기 - 말하기 - 읽기 순으로 발달한다.

이때 읽기를 글로 치환하면 '말하기가 글보다 먼저'란 뜻이 된다.

결과적으로
생각을 잘해야 바르게 말할 수 있고
말을 잘해야 글을 올바르게 적을 수 있다.

글을 쓸 때도 자연스럽게
어떻게 쓸지를 먼저 생각하고 속으로 말해보고 글을 적게 된다.

말하듯이 쓰는 게 좋다고 하는 이유가 바로 이 때문이다.

코딩도 글쓰기다?

이 부분은 내가 3장을 읽으면서 든 생각이다.

개발자들이 코딩을 하는 것도
코드 = 글이니까.
결국 글을 적는 것이라고 생각하는데

요청 흐름을 코드로써 구현했을 때,
말로 설명할 수 있어야 좋은 코드이지 않을까?

그러려면 코드 또한 말하듯이 적어야 하지 않나 싶다.

코드를 적기 전에 먼저 설계(생각)를 하고
코드 구현(글 쓰기)은 말하듯이 적어야 보기 좋은 것 같다.

마무리

책 '유시민의 글쓰기 특강'을 3장까지 읽어봤는데

글의 전체적인 흐름이 느껴져서 좋았다.

생각을 잘하려면 많이 읽고 써봐야 한다.
생각을 잘하게 되면 말을 잘하게 된다.
말을 잘하게 되면 글을 잘 쓰게 된다.

3장의 핵심은 다음과 같다.

말이 글보다 먼저다.
생각을 담는 것은 언어다.
글은 말하듯이 써라.

[Spotify Web API 6편] Band 서비스 구현

MvA — Wed, 10 Jun 2026 03:33:38 +0900

이번 편에서는 본 프로젝트의 핵심 서비스 중 하나인 Band 서비스를 구현하고, 기능 동작을 Postman으로 확인했다.

또한 사용자가 사이트에 들어오는 것부터 사이트의 기능들을 하나씩 이용하는 사용자 요청 시나리오를 알아보자.
그 과정에서 이 프로젝트에서 Band서비스가 하는 역할이 무엇인지 구현은 어떤 식으로 했는지에 대해 정리했다.

사용자 요청 시나리오

먼저 사용자가 우리 사이트에 접속하고 기능들을 이용하려면 회원가입 후 로그인부터 해야 할 것이다.
회원가입을 할 때, 본인이 속한 밴드를 적어야 한다. (혹은 밴드장으로부터 초대를 받으면 자동으로 기입됨)

소속된 밴드가 없다면, 개인으로 활동하거나 밴드를 새로 생성해야 한다.

회원가입 과정

밴드를 새로 생성하는 경우

유저 회원가입 전에 밴드생성부터 하게 된다.
밴드 생성 Form에 밴드 정보를 입력하고, 밴드 생성이 완료되면 다시 회원가입 페이지로 가서
밴드 정보와 함께 회원가입을 진행한다.

이때 생성된 밴드 정보는 Band 서비스에서 관리한다.

밴드장으로부터 초대를 받는 경우

밴드 입력란이 밴드장이 속한 밴드명으로 자동으로 채워져 있다.
이때 밴드명은 중복될 수 없다.
나머지 유저 정보를 입력하여 회원가입을 진행한다.

밴드명을 알고 있는 경우

입력란에 밴드명을 입력한 후 인증절차를 가진다.
인증이 완료되면 나머지 유저 정보를 입력하여 회원가입을 진행한다.

개인(무소속)으로 회원가입 하는 경우

밴드 입력란에 '개인'을 체크하고 회원가입을 진행한다.

로그인 이후

이후 로그인이 완료되면 그때부터 Band와 Wiki 서비스의 기능을 이용할 수 있다.
자신이 속한 밴드와 멤버들의 정보를 확인할 수 있고,
밴드로 새로운 멤버를 초대할 수 있다.

그리고 멤버들만 열람할 수 있는 글을 작성하고 일정을 관리할 수 있다.

Wiki 서비스의 기능으로는 개인 or 밴드멤버로서 밴드곡을 검색하고, 검색된 곡 아래로 글을 작성할 수 있다.
다른 사람의 글을 조회하고 댓글을 달 수 있다.

그리고 글에 대한 궁금증이 생긴다면 글 작성자와 1대 1로 채팅을 할 수 있는데
그 기능은 Chat 서비스에서 담당한다.

사이트를 이용하는 유저들끼리 Follow를 할 수도 있는데 이 기능은 User 서비스에서 담당한다.

따라서, 모든 서비스의 시작은 회원가입으로부터 시작된다.
회원가입을 위해 소속된 밴드정보가 필요하기 때문에
밴드 서비스를 제일 먼저 개발하기로 결정!

Band 서비스

1. 역할

밴드 데이터를 생성 및 관리하며 ( Band 도메인 )
밴드에 멤버를 추가 및 관리할 수 있도록 한다. ( BandMember 도메인 )

밴드 멤버들끼리 사용할 수 있는 일정표가 있고, 그 일정표에 글을 작성할 수 있다. (TimeLinePost 도메인)
타임라인글에는 멤버들이 자유롭게 댓글을 달 수 있다. (TimeLinePostComment 도메인)

2. 구현 과정

먼저 Band 서비스엔 루트 애그리거트가 2개이다.

Band — 밴드와 멤버를 관리하는 애그리거트
TimelinePost — 타임라인 글과 댓글을 관리하는 애그리거트

그에 맞춰 컨트롤러를 2개로 나눴다.

BandController
TimeLinePostController

서비스 레이어 또한 2개로 나눴다.

BandService
TimeLinePostService

도메인 계층을 구현할 때, 2가지를 신경 써서 개발했다.

도메인 객체와 엔티티 객체를 분리
UUID타입의 PK값을 도메인에서 생성 후 Persistable <UUID>, isNew 패턴으로 신규/기존 엔티티 구분

먼저 도메인 계층에 도메인 객체를 두고 인프라 계층에 엔티티 객체를 두었다.

이때 도메인을 먼저 생성함으로써, 도메인 메서드의 검증 로직들이 엔티티 생성전에 동작할 수 있도록 했다.

이 과정에서 도메인 객체에서 UUID를 생성하게 되는데
UUID를 미리 생성하면 JPA가 신규 엔티티인지 기존 엔티티인지 구분하지 못하는 문제가 생긴다.
이를 해결하기 위해 Persistable <UUID> 인터페이스를 구현하고 @Transient boolean isNew 플래그로 신규 여부를 명시했다.

이는 PK값 생성을 DB에 위임하지 않음으로써, 서비스 간 데이터를 합치거나 샤딩시에 ID 충돌이 없어 확장하기 유리하기 때문이다.

아래는 응용계층과 표현계층에 코드 작성 시, 필요한 API 목록이다.

BandController (/api/bands)
| POST 	| /api/bands | 밴드 생성 |
| GET 	| /api/bands/{bandId} | 밴드 단건 조회 |
| GET 	| /api/bands?page=&size= | 밴드 목록 조회 |
| PATCH | /api/bands/{bandId} | 밴드 정보 수정 |
| DELETE | /api/bands/{bandId} | 밴드 삭제 |
| POST 	| /api/bands/{bandId}/members | 멤버 초대 |
| GET 	| /api/bands/{bandId}/members | 멤버 목록 조회 |
| DELETE | /api/bands/{bandId}/members/{userId} | 멤버 강퇴 / 탈퇴 |
| PATCH | /api/bands/{bandId}/leader | 리더 양도 |

TimelinePostController (/api/timeline-posts)
| POST 	| /api/timeline-posts | 포스트 작성 |
| GET 	| /api/timeline-posts/{postId} | 포스트 단건 조회 |
| GET 	| /api/timeline-posts?bandId= | 밴드별 포스트 목록 조회 |
| PATCH | /api/timeline-posts/{postId} | 포스트 수정 |
| DELETE | /api/timeline-posts/{postId} | 포스트 삭제 |
| POST 	| /api/timeline-posts/{postId}/comments | 댓글 작성 |
| DELETE | /api/timeline-posts/{postId}/comments/{commentId} | 댓글 삭제 |

[유시민의 글쓰기 특강] 2장 글쓰기의 철칙 후기

MvA — Tue, 9 Jun 2026 23:47:32 +0900

안녕하세요. 이번엔 책 [유시민의 글쓰기 특강] 2장에 대한 후기를 적었습니다!
책의 내용을 요약하고, 느낀 점을 적었습니다.
(글의 오른쪽 하단 버튼으로 화이트/다크모드 전환이 가능합니다.)

1장 내용 짧게 정리

- 모든 표현은 결국 생각에서 나오며, 생각을 잘해야 논증도 잘한다.
- 논증을 잘하는 '규칙'으로는 3가지가 있다.

주장과 취향고백을 구별하라.
주장은 반드시 논증한다.
처음부터 끝까지 글의 주제에 집중하라.

책 2장 내용 정리

먼저 유시민 작가님께서는 "글은 문학적인 글과 논리적인 글로 나뉜다"라고 설명하셨다.

문학적인 글

문학적인 글의 예시로는 시, 소설 등이 있다.
이를 예술적인 글이라고도 표현하셨다.

논리적인 글

논리적인 글의 예시로는 에세이, 보고서, 논문 같은 글이다.

문학적인 글은 재능의 영향을 많이 받지만, 논리적은 글은 노력으로 충분하 잘 쓸 수 있다고 하며
그 이유로써 글쓰기의 '철칙' 2가지를 소개하셨다.

위에서 봤듯 1장에서는 규칙, 2장에서는 철칙에 대해서 말했는데 그 이유가 있는 것 같다.
먼저 규칙과 철칙의 뜻에 대해서 알아보면,

규칙 : 여러 사람이 다 같이 지키기로 작정한 법칙. 또는 제정된 질서.
철칙 : 바꾸거나 어길 수 없는 중요한 법칙.

즉, 나는 '논증을 잘하는 3가지 규칙'을 작가님의 일종의 제안이라고 이해했다.
또, 작가님은 '글쓰기 근육을 만드는 유일한 방법은 쓰는 것이다. 여기에 예외는 없다. 그래서 '철칙'이다.'라고 표현하셨다.
정말 모든 분야에 적용되는 말이라고 생각한다.

철칙의 내용은 바로 '글은 많이 읽어야 잘 쓸 수 있고, 많이 쓸수록 더 잘 쓰게 된다.'이다.

[글쓰기의 철칙 1] 많이 읽어야 한다.

그리고 글쓰기는 텍스트 발췌 요약부터 시작하는 게 좋다고 했다.
이는 내가 이 책을 읽게 된 계기이다.

기술 블로그를 운영하며 글을 작성하며 느낀 점은
내가 개발을 못한다도 있지만, 글을 너무 못쓴다도 있었다.

기술 블로그도 '글'이다.
그렇다는 것은 '누군가 이 글을 읽는다'는 것이고,
많은 사람들이 원하는 '좋은 글을 위해선 잘 써야 하고 읽기 편하게 써야 한다'라고 생각한다.

그런 갈증으로 이 책을 사서 읽게 되었는데, 내가 찾는 지식을 알려주어서 너무 반가웠다.

어떤 글을 잘 썼다고 할까?

작가님께서는 잘 쓴 글의 특징을 위의 4가지로 표현하셨다.

첫째, 무슨 이야기를 하는지 주제가 분명해야 한다.

둘째, 그 주제를 다루는 데 꼭 필요한 사실과 중요한 정보를 담아야 한다.
셋째, 그 사실과 정보 사이에 어떤 관계가 있는지 분명하게 나타내야 한다.
넷째, 주제와 정보와 논리를 적절한 어휘와 문장으로 표현해야 한다.

이렇게 잘 쓰기 위해서 독해, 요약, 사유와 토론을 추천하셨다.

[글쓰기의 철칙 2] 많이 써봐야 한다.

작가님께서는 "학창 시절 배웠던 한문이 시대가 발전하면서 손으로 직접 안 쓰게 되며
이제는 손으로는 잘 쓰지 못하게 됐다"는 말을 하시며 '쓰기'의 중요성을 언급하셨다.

글을 많이 안 써본 사람들은 글의 첫 문장을 구성하는데 어려움을 느낀다고 했는데
그 이유가 '글 전체를 대략적으로라도 구성해야 하기 때문'이라고 설명했다.

이것도 정말 맞는 말이라고 생각한다. 1~2년 전만 해도 글의 초고를 작성하는데 되게 오래 걸렸다.
그리고 부트캠프에 들어가게 되며, 내가 쓴 글을 보여줄 일이 생겼는데 그 과정에서 많이 발전한 것 같다.

어제 회의하던 내용 글로 정리해 봤는데, 보시면서 오늘 회의하면 좋을 것 같아요!
튜터님께 질문드릴 내용 정리해 봤는데, 이걸 보여드리면서 같이 물어봐요!
저번에 알려주신 내용 글로 정리해 봤는데, 틀린 내용이나 느낀 점 말해주면 좋을 것 같아요!

등 주로 내가 직접 보여주는 형식이었다.
누군가가 먼저 찾아와서 내 글을 볼 정도의 수준이 되는 것은 더 미래의 일이라고 생각한다.

안 그래도 할 일이 많은데, 글을 빠르게 작성할 수 있는 것은 현대시대에도 좋은 능력이라고 생각한다.

혹평과 악플을 겁내지 말자

2장에서 말하는 마지막 주제이다. 철칙은 아니지만 작가님의 경험이 담겨있는 것 같다.

'글을 쓸 때는 읽는 사람이 누구일지 미리 살펴야 한다.'라는 내용이 나오는데
유인물(전단지)을 만들며 어떤 유인물이 사람들이 오래 가지고 있는가?를 조사하며 그 사람들의 니즈(Needs)를 파악해야 한다는 뜻이었다. 그러면서 타인의 평가와 비판을 듣고 다음 작업 때 반영해야 한다고 했다.

이력서의 경우가 바로 위 예시에 해당하며 기업의 채용담당자들이 읽는 글이다.
그래서 정해진 형식이 있다.
따라서 글을 이쁘게 작성했다고 해서 내용이 독자의 니즈와 맞지 않으면 가치가 떨어지게 된다.
만약 위처럼 이력서를 잘못 작성했다면, 피드백을 받고 형식에 맞게 적으면 될 뿐이다.

[Spotify Web API 5편] Docker 및 공통모듈 세팅

MvA — Sun, 7 Jun 2026 21:44:37 +0900

5편에서는 구현전에 해놔야 하는 것들을 했다.

각 서비스의 Dockerfile
docker-compose.yml
공통에러, 응답 처리
모든 서비스 연동 확인
컨피그 Repo에 설정 파일 추가

내일부터는 밴드 서비스 -> 위키 서비스 -> 게이트웨이 및 유저 서비스 -> 챗 서비스 -> CI 구현 -> 배포 -> 모니터링 -> 프런트 개발 순서로 진행할 것이다.

아래 토글(더보기)은 개발 체크리스트이다.

BandFeed 개발 체크리스트

0단계 — 사전 준비

[x] API / 테이블 / 인프라 설계서 작성
[x] GitHub 레포 생성 (BandFeed, BandFeed-config)
[x] 모노레포 멀티모듈 구성 (Gradle)
[x] Config 레포 생성 및 Config Server 연동
[x] .gitignore / .env 설정
[x] Docker Compose 구성 (MySQL, Kafka, Redis, 모니터링 profile)
[x] 각 서비스 Dockerfile 작성 (7개)

1단계 — MSA 인프라 및 핵심 비즈니스 구축 (Base MVP)

인프라

[x] Eureka Server 구축 및 동작 확인
[x] Config Server 구축 및 각 서비스 yml 연동
[x] Gateway Service 생성 및 유레카 등록
[x] 공통 모듈 구성
- [x] BaseEntity (Auditing)
- [x] ErrorCode 인터페이스
- [x] BusinessException
- [x] CommonErrorCode
- [x] CommonResponse<T>
- [x] GlobalExceptionHandler

서비스 생성 및 유레카 등록

[x] User Service
[x] Band Service
[x] Wiki Service (Post/Song)
[x] Chat Service

Band Service — 핵심 기능 구현

[ ] 도메인 설계 (Entity, Repository)
[ ] Spotify API 연동
[ ] Band CRUD API

Wiki Service — 핵심 기능 구현

[ ] 도메인 설계 (Entity, Repository)
[ ] Post/Song 위키형 게시판 CRUD API (인증 없이 우선 개발)
[ ] Resilience4j 서킷 브레이커 적용
[ ] @Retryable 재시도 로직 적용 및 검증

2단계 — 게이트웨이 라우팅/보안 및 커뮤니티 확장 (Feature MVP)

Gateway 라우팅 및 인증

[ ] 각 서비스로의 라우팅(Routing) 설정
[ ] User Service 로그인/회원가입 구현
[ ] Gateway에서 JWT 토큰 발급·검증 흐름 완성
[ ] X-User-Id 헤더 전달 필터 구현

인증 기반 기능

[ ] BandMember 매핑 구현
[ ] 프라이빗 타임라인 (접근 제어) 구현

Chat Service

[ ] WebSocket + STOMP 개념 학습
[ ] 1:1 DM 기능 구현
[ ] Kafka 연동 (메시지 이벤트)

기타

[ ] FeignClient 서비스 간 통신 구현
[ ] 이벤트 기반 로직 구현 (Kafka)
[ ] 통합 시나리오 테스트용 .http 파일 작성

3단계 — 인프라 고도화 및 아키텍처 검증 (Architecture MVP)

배포

[ ] GitHub Actions CI 파이프라인 구축
[ ] Docker 기반 AWS 멀티 컨테이너 CD 구현
[ ] 배포 환경 동작 확인

모니터링

[ ] Actuator + Prometheus 엔드포인트 설정
[ ] Loki + Promtail 로그 수집 설정
[ ] Grafana 대시보드 구성
[ ] Alertmanager Slack 알림 설정

성능 검증

[ ] JMeter / k6 부하테스트 환경 구성
[ ] 외부 API 지연 시 서킷 브레이커 Fallback 검증
[ ] Redis 캐싱 적용 전후 TPS 비교

프런트엔드

[ ] 프론트 개발
[ ] 프론트 배포
[ ] 프론트로 동작 테스트
[ ] 버그 수정

마무리

[ ] 실사용자 배포
[ ] 피드백 수집 및 반영

오늘 배운 것

1. 도커 컴포즈 구성시, 변수처럼 묶어서 설정을 적용할 수도 있다.

x-java-tz: &java-tz
  TZ: Asia/Seoul
  JAVA_TOOL_OPTIONS: -Duser.timezone=Asia/Seoul

x-common-service: &common-service
  depends_on:
    eureka-server:
      condition: service_healthy
    config-server:
      condition: service_healthy
    mysql:
      condition: service_healthy
  networks:
    - bandfeed-network
    
  band-service:
    build:
      context: .
      dockerfile: apps/band-service/Dockerfile
    container_name: bandfeed-band
    ports:
      - "${BAND_SERVER_PORT}:9020"
    environment:
      <<: *java-tz
      SERVER_PORT: 9020
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/${MYSQL_BAND_DB}?useSSL=false&serverTimezone=Asia/Seoul&allowPublicKeyRetrieval=true
      SPRING_DATASOURCE_USERNAME: ${MYSQL_USER}
      SPRING_DATASOURCE_PASSWORD: ${MYSQL_PASSWORD}
      EUREKA_CLIENT_SERVICEURL_DEFAULTZONE: http://eureka-server:8761/eureka/
      CONFIG_SERVER_URL: ${CONFIG_SERVER_URL}
    <<: *common-service

- 모든 서비스의 공통으로 적용되는 타임존 설정
- 핵심 비즈니스 로직을 처리하는 마이크로 서비스에 적용하는 depends-on 설정

2. 도커 컴포즈 구성 시, 프로필 설정으로 원하는 서비스만 실행

  prometheus:
    image: prom/prometheus:v2.53.0
    container_name: bandfeed-prometheus
    profiles: ["monitoring"]
    environment:
      - TZ=Asia/Seoul
    ports:
      - "${PROMETHEUS_PORT}:9090"
    volumes:
      - ./monitoring/prometheus/prometheus.yaml:/etc/prometheus/prometheus.yaml
      - ./monitoring/prometheus/alert-rules.yaml:/etc/prometheus/alert-rules.yaml
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yaml'
      - '--storage.tsdb.retention.time=14d'
    restart: unless-stopped
    networks:
      - bandfeed-network

- profiles: ["프로필명"]을 추가했다.

docker-compose up -d
docker-compose --profile monitoring up -d

모니터링 서비스는 내가 설계한 개발 순서상, 나중에 사용하기에
지금 사용할 서비스만 도커 컴포즈로 실행할 수 있도록 했다.
이후 모니터링 관련 이미지도 포함하여 실행하고 싶다면 --profile monitoring을 추가하면 된다.

3. 컨피그 Repo에 있어야 하는 설정과 각 서비스에서 가지고 있어야 할 설정

# 각 서비스가 가져야할 설정들
spring:
  application:
    name: band-service        # Config server가 이 이름으로 파일을 찾음
  config:
    import: optional:configserver:http://localhost:8888  # Config server 연결

server:
  port: 9020   # 로컬 실행 시 fallback 포트

# 컨피그 Repo에 넣어야 할 설정들
spring:
  datasource:		# DB 접속 정보
    url: jdbc:mysql://mysql:3306/band_db
    username: bandfeed
    password: secret
  jpa:
    hibernate:
      ddl-auto: update

# 서비스 디스커버리
eureka:
  client:
    service-url:
      defaultZone: http://eureka-server:8761/eureka/

# 외부 서비스 URL, 각종 키, feature flag 등

DB 정보같이 각 서비스별로 달라지는 설정들은 컨피그 Repo에서 관리한다.

4. 모니터링 개념 및 방식

각 서비스(Spring Boot)
    ↓ /actuator/prometheus (메트릭)
Prometheus (수집)
    ↓
Grafana (시각화)

각 서비스(로그)
    ↓ Docker 컨테이너 로그
Promtail (수집)
    ↓
Loki (저장)
    ↓
Grafana (시각화)

5. 공통 에러 처리

ErrorCode 객체를 인터페이스로 선언.
BusinessException에서 ErrorCode를 생성자 주입받음.
각 서비스에서 enum 객체를 생성 후 ErrorCode를 구현.
예외 발생 시, GlobalExceptionHandler에서 가로채어 예외 반환.
예외 반환 시, CommonResponse로 형식이 통일되어 반환됨.

6. 공통 모듈 자체의 jar 파일 생성 문제

문제 상황

Gradle> bandfeed> Tasks> build> build 중 문제 발생!

- 에러 로그

Error while evaluating property 'mainClass' of task ':apps:bootJar'.
> Main class name has not been configured and it could not be resolved

문제는 apps 모듈의 jar파일을 생성하는데, main 클래스가 없다는 점이었다.

분석

- 루트 폴더의 build.gradle의 일부분

// 루트 모듈을 제외한 하위 프로젝트 공통 설정
subprojects {
    apply plugin: 'java'
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(21)
        }
    }

    configurations {
        compileOnly {
            extendsFrom annotationProcessor
        }
    }

    dependencies {
        implementation 'org.springframework.boot:spring-boot-starter'
        testImplementation 'org.springframework.boot:spring-boot-starter-test'
        testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    }

    tasks.named('test') {
        useJUnitPlatform()
    }
}

루트 폴더 하위의 모듈들에게 공통 의존성을 추가하는 부분이다.
근데 setting.gradle 설정 때문에 apps 자체도 모듈이 된다.

rootProject.name = 'bandfeed'

include 'common'
include 'apps:config-server'
include 'apps:eureka-server'
include 'apps:gateway-service'
include 'apps:band-service'
include 'apps:user-service'
include 'apps:wiki-service'
include 'apps:chat-service'

apps:라고 prefix를 둔 순간 gradle이 apps라는 중간 부모 모듈을 만든다.

조치 및 해결

- apps 모듈의 자체 jar 파일 생성기능을 비활성화

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.14'
    id 'io.spring.dependency-management' version '1.1.7'
}

// root project 실행 가능 Jar 파일 생성기능 Off
bootJar.enabled = false

// subprojects 설정(루트 프로젝트 하위 모듈 서비스들 공통 설정)


// 모듈의 기본 jar 파일 생성기능 off
project(':common') {
    bootJar.enabled = false
    jar.enabled = true
}

project(':apps') {
    bootJar.enabled = false
    jar.enabled = false
}

// 나머지 서비스들 플러그인 적용(gradle 감지)

subprojects에 대상으로 포함되어도 jar파일을 생성하지 않게 함으로써 에러를 해결했다.

[유시민의 글쓰기 특강] 1장 논증의 미학 후기

MvA — Sun, 7 Jun 2026 18:21:09 +0900

이번 글에서는 '유시민의 글쓰기 특강'이라는 책을 읽고, 느낀 점을 적어보려고 합니다.
(글의 오른쪽 하단 버튼으로 화이트/다크모드 전환이 가능합니다.)

출처: 교보문고

오늘은 책의 1장을 읽고 느낀 점을 적었습니다.

책을 읽고 느낀 점

1장에서 전하려는 핵심은 모든 표현의 출발은 '생각'에서 시작한다는 것이다.
말로 표현하던, 행동으로 표현하던 말이다.
그래서 생각을 잘해야 논증도 잘할 수 있다고 한다.

이 책에서는 토론과 글을 잘 쓰기 위한 3가지 규칙을 소개했다.
1. 취향고백과 주장을 구별한다.
2. 주장은 반드시 논증한다. ( 주장을 하면 논증해야 하는 책임이 생긴다. )
3. 글의 주제에 끝까지 집중하라.

1번부터 살펴보자.

생각(취향고백) : A는 B이다.
주장 : A는 B라고 생각한다.

이 책에서는 '대한민국 최고 미남은 장동건이다'라고 예시를 들었다.

이는 주장이 아니며 취향고백에 가깝다고 했다.

만약 주장을 하고 싶었다면, '나는 장동건을 대한민국 최고미남이라고 생각한다'라고 했어야 했다.
위의 2번에서 말했듯, 주장은 반드시 논증해야 한다.

다시 말해, 장동건이 미남이라고 생각하는 이유나 근거를 들어야 한다.
미남의 기준을 제시하고, 장동건이 그 기준에 들어맞는다는 것을 증명하면 된다.

이 말을 들은 사람은, 주장에 동의하거나 반박할 수 있다.

미남의 기준을 새로 제시하거나, 다른 인물이 그 기준에 더 잘 들어맞는다고 할 수 있다.

위에서 '대한민국 최고 미남은 장동건이다'라는 말이 주장이 아닌 이유는
논증하지 않았기 때문에 반박도 할 수 없기 때문이다.

따라서, 논증하지 않은 주장은 반박할 수 없고, 그런 주장은 주장으로 받아들여지지 않는다고 한다.

기억나는 나의 일화

위 주제와 관련한 기억나는 내 일화를 소개하려고 한다.

- 상황

친구와 술집에서 '치즈라볶이'를 먹고 나니 점원이 서비스로 떠먹는 아이스크림을 주었다.
그 후 또 다른 친구가 뒤늦게 도착해, 해물파전을 시켜 먹었다.

근데 파전을 먹을 앞접시가 따로 없어서 나는 아까 아이스크림을 먹은 그릇을 앞접시로 사용했다.
여기서 문제가 발생했다.

친구 1: "전을 아이스크림 다 묻은 그 앞접시에 먹어?"
나: "라볶이 빨간 국물을 묻히기 싫어서 그랬다."
친구 1: "진짜 안타깝다.."
나: "(발끈하며) 아니!"
친구 2: "그만그만 얘들아 싸우지 말자."
친구 2: "원래는 라볶이 먹던 앞접시에 먹는 게 맞긴 하는데.. 싸우지 말자"

나는 더 반박하고 싶었지만, 그날 술자리의 분위기를 망치고 싶지 않아 그만하기로 했다.

위 상황을 책의 토론, 논증의 3가지 규칙을 적용해 보자.
먼저, 여기서 제일 좋은 방법은 그냥 점원에게 새로 앞접시를 달라고 하면 됐다.

하지만 이미 있는 앞접시를 재활용해야 한다면 2가지 선택지가 있었다.

라볶이 국물이 묻은 앞접시
아이스크림이 묻은 앞접시

나는 둘 중 그나마 소스가 덜 묻은 아이스크림이 묻은 앞접시를 선택했지만,
애초에 '둘 중 어느 것이 전에 묻는 것이 싫은지'는 취향문제라고 생각해서 애초에 논쟁할 필요가 없다고 생각한다.

그리고 만약 그냥 라볶이 국물에 먹는 걸 추천한다며, 그 이유에 대해 설명했다면 좋은 주장이 됐을 것이다.
하지만 친구 1은 "전을 아이스크림 앞접시에 먹는 것이 안타깝다"라고 주장했지만, 그에 대한 논증을 하지 않았다.

따라서 이 말은 그냥 비난을 한 것이라고 생각한다.

물론 술자리에서 했던 대화내용이기에 친구 1을 비난하고 싶은 마음은 없다.
술자리에서마저 이런 논증의 규칙을 다 지키는 사람을 얼마 없을 거라 생각하기 때문이다.

하지만 이 책을 읽고 갔더라면..
좀 더 대화를 시도해 볼 수 있었을 것 같다.
안타깝다고 했다면 그 이유에 대해 물어본다던지 말이다.
나도 감정적으로 생각해서 내 주장을 다하지 못했던 것 같다.

다시 정리하면,

주장과 취향고백은 구별해라.
주장은 반드시 논증해라.
처음부터 끝까지 주제에 집중해라.

[Spotify Web API 4편] MSA 프로젝트 초기 세팅

MvA — Sun, 7 Jun 2026 01:45:38 +0900

이번 4편부터는 드디어 구현을 시작하는데, 먼저 개발 로드맵 다시 살펴보자.

개발 로드맵

[1단계] MSA 인프라 및 핵심 비즈니스 구축 (Base MVP)

~~API, 테이블, 인프라 설계서 작성~~
Eureka Server(디스커버리) 및 Config Server(설정 관리) 구축
User 서비스, Band 서비스, Post 서비스 생성 및 유레카 등록
[핵심 기능] Spotify API 연동 및 Post/Song 위키형 게시판 CRUD 완성 (인증 없이 우선 개발)
[장애 격리] Post 서비스 내에 Resilience4j 서킷 브레이커 및 @Retryable 재시도 로직 적용 및 검증

[2단계] 게이트웨이 라우팅/보안 필터 및 커뮤니티 확장 (Feature MVP)

Gateway 서비스 구축 및 각 서비스로의 패스 라우팅(Routing) 적용
[인증/인가 빌드업] User 서비스에서 로그인 검증 후, Gateway에서 JWT 토큰을 발급·검증하는 흐름 완성
[인증 기반 개발] 게이트웨이가 넘겨준 헤더(X-User-Id)를 활용해 BandMember 매핑 및 프라이빗 타임라인(접근 제어) 구현
Chat 서비스 추가 분리 및 WebSocket + STOMP 기반 1:1 DM 구축

[3단계] 인프라 고도화 및 아키텍처 검증 (Architecture MVP)

GitHub Actions와 Docker를 이용한 AWS 멀티 컨테이너 배포 파이프라인 구축
Prometheus + Grafana를 연동하여 서버 메트릭 모니터링 환경 구축
JMeter / k6 부하테스트를 통해 외부 API 지연 발생 시 서킷 브레이커 동작(Fallback) 검증 및 Redis 캐싱 적용 전후 TPS 비교
실사용자 배포 및 피드백 수집

맞다. 지금까지 딱 1줄 했다.

갈 길이 멀다... 얼른 MSA 환경부터 구성해 보자.

MSA 환경 구성

- 유레카 서버 프로젝트 생성

- 프로메테우스와 액츄에이터(모니터링용)
- 컨피그 클라이언트(yml 설정을 받아오기 위해)
- 유레카 서버

- 컨피그 서버 프로젝트 생성

- 프로메테우스, 액츄에이터
- 컨피그 서버
- 스프링 웹 ( 이후 공통 모듈로부터 주입받을 예정 )
(다른 서비스에 yml 파일을 전달할 때, HTTP REST API 방식으로 전달한다.
이때 필요한 내장 TomCat을 스프링 웹 의존성으로 지원받기 때문이다.)

- 게이트웨이 프로젝트 생성

- 프로메테우스, 액츄에이터
- 유레카 클라이언트
- 컨피그 클라이언트
- 롬복

- 스프링 시큐리티
- R4j
- 스프링 클라우드 게이트웨이
- Validation

+) Jwt 의존성 추가
(외부 라이브러리라서 수동으로 추가해야 한다.)

공통 모듈

공통 모듈에 어느 의존성까지 주입해야 하는지 고민해봐야 할 것 같다.
지금은 아래와 같이 설정했다.

plugins {
    id 'java-library'
    id 'io.spring.dependency-management'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.boot:spring-boot-dependencies:3.5.14"
    }
}

dependencies {
    // 모니터링 의존성 추가 예정
    // jpa
    api 'org.springframework.boot:spring-boot-starter-data-jpa'

    // querydsl
    implementation 'com.querydsl:querydsl-jpa:5.1.0:jakarta'
    
    // Srping Web
    implementation 'org.springframework.boot:spring-boot-starter-web'
    
    annotationProcessor 'com.querydsl:querydsl-apt:5.1.0:jakarta'
    annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api'

    // lombok
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
}

롬복은 api로 설정해도 annotationProcessor까지는 전파가 안된다고 해서
어차피 각 서비스에서도 의존성을 추가해줘야 해서 나중에 제거할 수도 있을 것 같다.

그리고 이후 prometheus나 actuator를 추가할 것 같다.

또, 루트 폴더 아래에 build.gradle에서도 의존성을 주입할 수 있다.

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.14'
    id 'io.spring.dependency-management' version '1.1.7'
}

// root project 실행 가능 Jar 파일 생성기능 Off
bootJar.enabled = false

allprojects {
    group = 'com.bandfeed'
    version = '0.0.1-SNAPSHOT'
    description = 'bandfeed'

    repositories {
        mavenCentral()
    }
}

// 루트 모듈을 제외한 하위 프로젝트 공통 설정
subprojects {
    apply plugin: 'java'
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'

    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(21)
        }
    }

    configurations {
        compileOnly {
            extendsFrom annotationProcessor
        }
    }

    dependencies {
        implementation 'org.springframework.boot:spring-boot-starter'
        testImplementation 'org.springframework.boot:spring-boot-starter-test'
        testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    }

    tasks.named('test') {
        useJUnitPlatform()
    }
}

project(':common') {
    bootJar.enabled = false
    jar.enabled = true
}

project(':apps:gateway-server') {
    apply plugin: 'org.springframework.boot'
}

project(':apps:config-server') {
    apply plugin: 'org.springframework.boot'
}

project(':apps:eureka-server') {
    apply plugin: 'org.springframework.boot'
}

// 그 외 마이크로 서비스들 추가 예정

그래서 유레카 서버, 컨피그 서버, 게이트웨이 서버 같은 인프라 서버들과
비즈니스로직을 처리하는 각 마이크로 서비스들에게 의존성을 다르게 주입하는 전략을 고민 중이다.

인프라 서버들은 루트 폴더 아래 build.gradle로부터만 의존성을 주입받는다.
그 외 서비스들은 루트 폴더 아래 build.gradle 의존성 + 공통모듈 의존성을 모두 주입받는다.

- band-service 프로젝트 생성

오늘 한 것:
- 프로젝트 Repo 생성 및 모노레포 멀티모듈 구성
- 컨피그 Repo 생성 및 연동
- 유레카-컨피그-게이트웨이서버 동작 확인
- 공통모듈 추가 및 BaseEntity 동작 확인
- 밴드 서비스 추가

내일 할 것 :
- 루트 폴더 아래 build.gradle에 band-service 추가
- user-service, wiki-service, chat-service 프로젝트 생성
- band-service, wiki-service MVP 개발

Todo List :

- user-service 구현 및 게이트웨이 시큐리티 기능 추가

- R4j 적용 및 FeignClient, Kafka 연동
- chat-service에서 사용할 ws 개념 알아보기
- chat-service MVP 개발

- 이벤트 로직이 필요한 파트 구현
- 통합 시나리오 테스트용 .http 파일 작성
- 모니터링 설정 추가

- CI 코드 작성

- AWS 배포

- CD 구현
- 배포환경에서 부하테스트
- 프런트 개발
- 프런트 배포
- 프런트로 동작 테스트
- 버그 수정
- 실 사용자 피드백받기 및 반영