나만의 개발 기록

# Docker Compose로 Mattermost 사내 메신저 구축하기

JaeSung Kim — Fri, 31 Jul 2026 10:01:33 +0900

Docker Compose로 Mattermost 사내 메신저 구축하기 (Teams 대체)

Teams를 더 이상 쓰지 않게 되면서, 무료 오픈소스 메신저를 자체 서버에 설치해보기로 했다. 여러 후보(Rocket.Chat, Zulip, Matrix) 중 Mattermost를 선택했다. Slack과 가장 비슷한 UX를 제공하고, 오픈소스 Team Edition은 인원 제한 없이 완전 무료이기 때문이다.

왜 Mattermost인가

2015년부터 개발된 오픈소스 프로젝트로 커뮤니티/문서가 풍부하다.
채팅, 채널, 파일 업로드, 검색, 멘션, DM, 이모지 반응 등 기본 기능은 전부 무료(Team Edition)이며 인원 제한이 없다.
LDAP/SSO, 고가용성 클러스터링, 컴플라이언스 리포트 같은 기능만 유료(Professional/Enterprise) 티어에서 제공된다. 일반적인 사내 채팅+파일공유 용도라면 무료판으로 충분하다.

docker-compose.yml 작성

Mattermost(Team Edition) + PostgreSQL 조합으로 구성했다.

version: "3.8"

services:
  postgres:
    image: postgres:15-alpine
    container_name: mattermost-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: mmuser
      POSTGRES_PASSWORD: <비밀번호>
      POSTGRES_DB: mattermost
    volumes:
      - /mnt/data/mattermost/postgres:/var/lib/postgresql/data
    networks:
      - mattermost-network

  mattermost:
    image: mattermost/mattermost-team-edition:latest
    container_name: mattermost
    restart: unless-stopped
    depends_on:
      - postgres
    ports:
      - "8065:8065"
    environment:
      MM_SQLSETTINGS_DRIVERNAME: postgres
      MM_SQLSETTINGS_DATASOURCE: "postgres://mmuser:<비밀번호>@postgres:5432/mattermost?sslmode=disable&connect_timeout=10"
      MM_SERVICESETTINGS_SITEURL: "http://서버IP:8065"
      MM_FILESETTINGS_DRIVERNAME: "local"
      MM_FILESETTINGS_DIRECTORY: "/mattermost/data"
    volumes:
      - /mnt/data/mattermost/config:/mattermost/config
      - /mnt/data/mattermost/data:/mattermost/data
      - /mnt/data/mattermost/logs:/mattermost/logs
      - /mnt/data/mattermost/plugins:/mattermost/plugins
      - /mnt/data/mattermost/client-plugins:/mattermost/client/plugins
      - /mnt/data/mattermost/bleve-indexes:/mattermost/bleve-indexes
    networks:
      - mattermost-network

networks:
  mattermost-network:
    driver: bridge

포인트

포트 충돌 방지: 서버에 이미 여러 서비스(Jenkins, GitLab, Elasticsearch 등)가 떠 있었기 때문에, docker ps로 사용 중인 포트를 먼저 확인하고 8065 포트가 비어있는지 체크했다.
볼륨 경로: 루트 파티션 용량이 넉넉하지 않아서(df -h 확인 결과 71% 사용 중), 별도로 마운트된 대용량 디스크(/mnt/data) 아래에 데이터를 저장하도록 경로를 잡았다.
DB 격리: postgres 서비스는 호스트에 포트를 노출하지 않고 컨테이너 내부 네트워크에서만 통신하도록 설정했다. 컨테이너 이름과 데이터 경로가 기존에 떠 있던 다른 postgres/mariadb 컨테이너들과 전혀 겹치지 않아 기존 서비스에 영향이 없다.

트러블슈팅 1: 권한 에러 (permission denied)

처음 docker compose up -d 실행 시 아래 에러가 반복적으로 발생했다.

Error: failed to load configuration: could not create config file: open /mattermost/config/config.json: permission denied

원인: Mattermost 컨테이너는 root가 아닌 UID 2000 사용자로 실행되는데, mkdir -p로 만든 호스트 폴더의 소유자가 root(또는 sudo 실행 계정)라서 컨테이너 내부에서 쓰기 권한이 없었다.

해결:

sudo chown -R 2000:2000 /mnt/data/mattermost/config
sudo chown -R 2000:2000 /mnt/data/mattermost/data
sudo chown -R 2000:2000 /mnt/data/mattermost/logs
sudo chown -R 2000:2000 /mnt/data/mattermost/plugins
sudo chown -R 2000:2000 /mnt/data/mattermost/client-plugins
sudo chown -R 2000:2000 /mnt/data/mattermost/bleve-indexes

이후 재기동하니 정상적으로 마이그레이션이 진행되고 서버가 떴다.

초기 설정: 관리자 계정 & 팀 초대

첫 계정 생성 시 사용자명(Username)은 영문 소문자 + 숫자만 가능하다. 한글 사용자명 입력 시 에러가 난다.
팀원 초대는 두 가지 방식이 있다.
1. 초대 링크 복사 → 카톡 등으로 직접 전달
2. 관리자 도구 → 사이트 구성 → "누구나 이 팀에 참여할 수 있습니다" 토글 활성화 → 서버 주소만 알려주면 팀원이 알아서 가입
이메일 초대는 SMTP 서버가 설정되어 있지 않으면 전송되지 않는다("SMTP가 시스템 콘솔에서 구성되지 않았습니다"). 소규모 팀이면 SMTP 설정 없이 링크/오픈서버 방식으로 충분하다.
데스크톱 앱에서 초대 링크 클립보드 복사가 안 되는 경우가 있었는데, 이때는 System Console에서 "공개 서버"를 활성화하고 서버 주소만 공유하는 방식으로 우회했다. (관리자 도구 → 사이트 구성 → 인증 → 가입 → 공개 서버: 활성화)

트러블슈팅 2: 개인 메시지가 실시간으로 안 뜸

DM을 보내도 바로 화면에 안 뜨고, 다른 채널로 갔다 와야 보이는 증상이 있었다.

확인한 것들:

docker stats로 CPU/메모리 확인 → 리소스는 충분히 여유로움 (CPU 0.1%대)
컨테이너 로그에서 웹소켓 에러 확인 → 특이 에러 없음

이 증상은 전형적으로 웹소켓 연결 문제일 때 나타난다. Mattermost는 실시간 메시지 전달을 위해 웹소켓을 쓰는데, MM_SERVICESETTINGS_SITEURL 값이 실제 접속 주소와 다르면 웹소켓 연결이 불안정해질 수 있어 이 값을 서버 실제 IP로 맞춰주는 것이 첫 번째 점검 포인트였다.

트러블슈팅 3: 모바일 푸시 알림이 안 옴

모바일 앱에서 "이 서버의 알림을 수신할 수 없습니다" 메시지가 계속 떴다.

1차 조치: System Console → 환경 → 푸시 알림 서버에서 다음과 같이 설정

모바일 푸시 알림: TPNS 연결을 사용하여 iOS 및 Android 앱에 알림을 전송합니다
푸시 알림 서버: https://push.mattermost.com (기본값인 push-test.mattermost.com이 아니라 test가 빠진 정식 URL로 변경)

이 값을 바꾸고 컨테이너를 재시작해도 동일한 에러가 계속 발생했다.

진짜 원인: 서버 주소가 http://(HTTPS 아님)였기 때문이다. Mattermost 공식 모바일 앱은 보안 정책상 서버가 HTTPS로 연결되어 있어야만 푸시 알림 등록을 허용한다. 즉 TPNS 설정 자체는 문제가 아니었고, 사이트 자체가 HTTPS가 아닌 것이 근본 원인이었다.

해결 방향:

사내망 + IP 접속이라면 → 자체 서명 SSL 인증서 + Nginx 리버스 프록시 (기기에서 인증서 신뢰 예외 처리 필요)
사용 가능한 도메인이 있다면 → Let's Encrypt 무료 인증서로 정식 HTTPS 적용 (권장)

정리

항목	무료 여부
채팅, 채널, DM, 파일 업로드	무료 (Team Edition)
데스크톱/모바일 알림	무료, 단 모바일 푸시는 HTTPS 필요
SSO/LDAP, 고가용성, 컴플라이언스	유료 (Professional/Enterprise)

소규모 팀의 사내 채팅용으로는 무료 Team Edition만으로 충분했고, docker-compose 하나로 기존에 운영 중이던 다른 서비스들과 완전히 격리된 상태로 손쉽게 추가할 수 있었다. 다만 모바일 푸시 알림까지 정상적으로 받으려면 HTTPS 적용이 사실상 필수라는 점은 미리 알아두면 좋을 것 같다.

파일 공유/동기화가 추가로 필요하다면 OneDrive 대체제로 Nextcloud를 같은 방식(docker-compose)으로 조합해서 쓸 수 있다.

# [Next.js + TS 실전] 9. FAQ · 시리즈 총정리

JaeSung Kim — Fri, 31 Jul 2026 09:51:53 +0900

[Next.js + TS 실전] 9. FAQ · 시리즈 총정리

입문 8편 + 실전 8편으로 작은 메모 앱을 끝까지 밀어 봤습니다.
마지막은 한눈에 지도, 자주 막히는 FAQ, 다음에 뭐 할지입니다.

이 글에서 하는 일

시리즈 전체 목차 정리
지금 앱이 할 수 있는 것 체크
실제로 자주 터지는 에러 Q&A
학습 로드맵 짧게

새 기능 추가는 없습니다.
복습·북마크용 글입니다.

시리즈 지도

입문 `[Next.js + TS]`

편	주제
1	왜 Next.js + TypeScript인가
2	프로젝트 만들고 폴더 구조
3	컴포넌트 타입 (Memo, props)
4	라우팅과 레이아웃
5	Server vs Client Component
6	데이터 가져오기 (async, loading/error)
7	폼과 Server Action
8	정리 + 다음 로드맵

실전 `[Next.js + TS 실전]`

편	주제
1	메모 수정과 삭제
2	Prisma + SQLite
3	Vercel 배포 (SQLite 한계)
4	폼 검증 (zod + useActionState)
5	로그인 (Clerk) + userId
6	Neon Postgres
7	삭제 확인 UI
8	목록 검색과 정렬
9	FAQ · 총정리 ← 지금

우리가 만든 것

메모 앱 기준으로 대략 이 정도입니다.

/                 소개
/memos            목록 (+ 검색·정렬)
/memos/new        작성 (+ zod 검증)
/memos/[id]       상세 (+ 삭제 확인)
/memos/[id]/edit  수정

기술 축:

App Router + TypeScript
Server Component 기본, 필요한 곳만 Client
Prisma (SQLite → Neon 가능)
Server Action CRUD
Clerk 로그인 + 내 메모만
Vercel 배포 이슈 이해

스스로 점검 체크리스트

기본

app/page.tsx = /, app/memos/page.tsx = /memos
layout.tsx와 page.tsx 차이를 설명할 수 있다
props / Memo 타입을 붙일 수 있다

서버·클라이언트

기본은 Server Component다
hooks / onClick이 있으면 Client로 분리한다
페이지 전체가 아니라 버튼·폼만 Client로 뺄 수 있다

데이터·폼

목록은 서버에서 await로 가져온다
쓰기는 Server Action + revalidatePath
zod로 검증하고 실패 시 상태 객체를 반환한다

인증·배포

미들웨어는 세션 연결, 보호는 auth.protect() / userId 쿼리
SQLite 파일은 Vercel과 안 맞는 이유를 안다
비밀 값은 .env / Vercel env에만 둔다

하나라도 막히면 해당 편만 다시 보면 됩니다.

FAQ (실제로 자주 막히는 것)

Q1. `/memos`가 404예요

원인 후보: 목록 파일에 상세 코드를 붙여 넣음.

파일	URL
`app/memos/page.tsx`	`/memos` 목록
`app/memos/[id]/page.tsx`	`/memos/1` 상세

상세(수정/삭제) 코드는 [id]/page.tsx 에 넣어야 합니다.
목록에 notFound()가 있으면 /memos도 404가 납니다.

Q2. `package.json`이 깨져서 npm이 안 돼요

시드 설정을 별도 객체로 하나 더 붙이면 JSON이 깨집니다.

잘못된 예:

  "devDependencies": { ... },
  {
    "prisma": { "seed": "..." }
  }
}

올바른 예 — 맨 바깥 키:

  "devDependencies": { ... },
  "prisma": {
    "seed": "npx tsx prisma/seed.ts"
  }
}

Q3. `userId` 마이그레이션이 실패해요

에러 예:

Added the required column userId without a default value. There are N rows...

이미 있는 행에 userId를 뭘로 채울지 몰라서입니다.

로컬 연습이면:

npx prisma migrate reset

데이터 삭제 후 스키마를 다시 맞춥니다.
그다음 시드에 userId도 넣어야 합니다. ("seed-user" 등)

Q4. 시드 메모가 로그인 목록에 안 보여요

정상일 수 있습니다.
시드 userId와 Clerk 로그인 userId가 다르기 때문입니다.

로그인 후 새로 작성한 메모로 확인하세요.

Q5. `createRouteMatcher`가 deprecated래요

최신 Clerk는 미들웨어에서 경로로 막지 말고,
페이지/레이아웃에서 auth.protect() 하라고 바뀌었습니다.

proxy.ts (또는 middleware.ts) → clerkMiddleware()만
app/memos/layout.tsx → await auth.protect()

Q6. `SignedOut` / `SignedIn`을 찾을 수 없어요

Clerk Core 3 / 최신 SDK에서는 Show 로 통합되었습니다.

<Show when="signed-out">...</Show>
<Show when="signed-in">...</Show>

ClerkProvider는 <html>을 감싸지 말고 <body> 안에 두는 형태를 권장합니다.

Q7. `parsed.error.flatten()`이 deprecated래요

Zod 4:

// 예전
parsed.error.flatten().fieldErrors

// 지금
z.flattenError(parsed.error).fieldErrors

Q8. `revalidatePath`는 뭐예요?

“이 경로 화면을 다시 준비해라”는 신호입니다.
메모를 추가/수정/삭제한 뒤 목록·상세가 옛 데이터로 남지 않게 합니다.

redirect = 이동, revalidatePath = 그 경로 캐시/데이터 갱신.

Q9. Prisma를 루트에 설치하고 memo-app에서 import했어요

앱은 memo-app 기준입니다.

패키지: memo-app에서 npm install
스키마: memo-app/prisma
명령: cd memo-app 후 npx prisma ...

루트(toyproject)와 섞이면 PrismaClient export 에러가 납니다.

Q10. Vercel에 올렸더니 데이터가 안 남아요 / DB 에러

SQLite file:./dev.db는 서버리스와 안 맞습니다.
Neon 등 외부 Postgres + Vercel DATABASE_URL이 필요합니다. (실전 3·6편)

Q11. 티스토리에 붙였더니 코드 블록이 안 먹어요

마크다운 모드인지 확인
```prisma 같은 생소한 언어 태그보다 ts / bash 또는 태그 없는 fence
JSX가 많은 블록은 미리보기에서 한 번 확인

채팅에서 복사할 때 코드펜스가 중간에 끊기면, .md 파일을 통째로 복사하는 편이 안전합니다.

한 줄로 다시 보는 핵심

주제	한 줄
Next	React로 앱 만드는 프레임워크 (폴더 = URL)
TS	데이터·props 계약
Server / Client	기본 서버, 인터랙션만 클라이언트
Action	폼이 부르는 서버 함수
Prisma	DB 쿼리를 타입과 함께
Clerk	로그인 + `userId`로 내 데이터만
Neon	배포용 Postgres
검색	상태는 URL 쿼리

다음에 공부하면 좋은 것

우선순위 예시:

테스트 — zod 스키마 / Action 단위 테스트
이미지 업로드 — 파일 저장·표시
권한·역할 — admin / member
캐시·성능 — fetch 옵션, 목록 페이지네이션
Auth.js — Clerk와 같은 구조를 직접 비교

새 시리즈를 쓴다면
“메모 앱 고도화” 또는 “포트폴리오용 기능 추가”로 끊는 편이 읽기 좋습니다.

마치며

이 시리즈의 목표는 문서를 다 외우는 게 아니었습니다.

작은 앱 하나를 만들고 → 저장하고 → 고치고 → 로그인하고 → 배포 이슈를 이해하는 것.

막힐 때마다 이 FAQ로 돌아와 보세요.
에러 메시지 한 줄이 보통 위 질문 중 하나에 연결됩니다.

질문·추가하고 싶은 FAQ가 있으면 댓글로 남겨 주세요.
같은 메모 앱 기준으로 이어서 정리할 수 있습니다.

전체 목차 (다시)

입문 1~8 · 실전 1~9
지금 이 글이 실전 시리즈의 매듭입니다.

# [Next.js + TS 실전] 8. 목록 검색과 정렬

JaeSung Kim — Fri, 31 Jul 2026 09:19:10 +0900

[Next.js + TS 실전] 8. 목록 검색과 정렬

메모가 늘어나면 목록만으로는 찾기 어렵습니다.
이번 편은 제목 검색과 정렬을 URL 쿼리로 붙입니다.
목표: ?q= · ?sort= · 서버에서 Prisma 필터.

이 편에서 할 일

왜 검색 상태를 URL에 두는지 이해하기
getMemos에 검색·정렬 옵션 추가하기
/memos 페이지에서 searchParams 읽기
검색 폼 + 정렬 링크 만들기

Client에서 배열을 filter해도 되지만,
이번엔 서버 컴포넌트 + DB 쿼리로 갑니다. 데이터가 커져도 같은 패턴입니다.

왜 URL에 두나

예:

/memos?q=Next&sort=oldest

장점:

새로고침해도 검색어 유지
링크를 공유할 수 있음
뒤로 가기와 자연스럽게 맞음
서버 컴포넌트가 searchParams로 바로 읽음

useState만 쓰면 위 이점이 약해집니다.
목록 필터의 기본은 쿼리스트링이 무난합니다.

1) 데이터 함수에 옵션 추가

lib/memos.ts의 getMemos를 확장합니다.

type GetMemosOptions = {
  q?: string;
  sort?: "newest" | "oldest";
};

export async function getMemos(
  userId: string,
  options: GetMemosOptions = {}
): Promise<Memo[]> {
  const q = options.q?.trim();
  const sort = options.sort ?? "newest";

  const rows = await prisma.memo.findMany({
    where: {
      userId,
      ...(q
        ? {
            title: {
              contains: q,
              // Postgres면 대소문자 무시에 mode: "insensitive" 가능
              // SQLite는 contains만으로 시작
            },
          }
        : {}),
    },
    orderBy: {
      createdAt: sort === "oldest" ? "asc" : "desc",
    },
  });

  return rows.map(toMemo);
}

포인트:

userId는 그대로 (내 메모만)
q가 있으면 제목 contains
sort로 asc / desc

Neon(Postgres)을 쓰면 이렇게 대소문자 무시가 됩니다.
title: { contains: q, mode: "insensitive" }
SQLite에서는 mode: "insensitive"가 지원되지 않을 수 있습니다.

Clerk를 아직 안 붙였다면 userId 인자는 프로젝트 상태에 맞게 조정하세요.

2) 목록 페이지에서 searchParams 읽기

app/memos/page.tsx:

import Link from "next/link";
import { auth } from "@clerk/nextjs/server";
import { redirect } from "next/navigation";
import MemoCard from "@/components/MemoCard";
import { getMemos } from "@/lib/memos";

type MemosPageProps = {
  searchParams: Promise<{ q?: string; sort?: string }>;
};

export default async function MemosPage({ searchParams }: MemosPageProps) {
  const { userId } = await auth();
  if (!userId) redirect("/");

  const params = await searchParams;
  const q = params.q ?? "";
  const sort = params.sort === "oldest" ? "oldest" : "newest";

  const memos = await getMemos(userId, { q, sort });

  return (
    <main>
      <h1>메모 목록</h1>

      <p>
        <Link href="/memos/new">새 메모 작성</Link>
      </p>

      <form>
        <label>
          제목 검색
          <br />
          <input type="search" name="q" defaultValue={q} placeholder="검색어" />
        </label>
        {" "}
        <button type="submit">검색</button>
        {q && (
          <>
            {" "}
            <Link href={`/memos?sort=${sort}`}>초기화</Link>
          </>
        )}
      </form>

      <p>
        정렬:{" "}
        <Link href={`/memos?q=${encodeURIComponent(q)}&sort=newest`}>최신순</Link>
        {" | "}
        <Link href={`/memos?q=${encodeURIComponent(q)}&sort=oldest`}>오래된순</Link>
      </p>

      <section>
        {memos.length === 0 ? (
          <p>조건에 맞는 메모가 없습니다.</p>
        ) : (
          memos.map((memo) => <MemoCard key={memo.id} memo={memo} />)
        )}
      </section>
    </main>
  );
}

포인트:

코드	의미
`searchParams`	URL `?q=&sort=`
`<form>`에 action 없음	같은 `/memos`로 GET 제출
`name="q"`	쿼리 키 이름
`defaultValue={q}`	검색 후에도 입력값 유지
`encodeURIComponent`	한글 검색어 링크 안전

auth / redirect는 Clerk 기준입니다.
미사용이면 기존 getMemos() 호출 방식에 옵션만 추가하면 됩니다.

동작 흐름

/memos?q=Next&sort=oldest
        ↓
page가 searchParams 읽음
        ↓
getMemos(userId, { q: "Next", sort: "oldest" })
        ↓
Prisma where + orderBy
        ↓
필터된 목록 렌더

useEffect로 클라이언트 fetch를 돌릴 필요가 없습니다.

검색 폼이 GET인 이유

<form>
  <input name="q" />
  <button type="submit">검색</button>
</form>

기본 method는 GET
제출하면 /memos?q=입력값
Server Action이 아님 (데이터 변경이 아니라 조회)

쓰기(추가/수정/삭제)는 Action,
읽기 필터는 쿼리 — 역할이 갈립니다.

(선택) 디바운스 실시간 검색

입력할 때마다 바로 필터하려면 Client 컴포넌트가 필요합니다.

useState + useRouter().push(?q=...)
또는 클라이언트에서 이미 받은 목록을 filter

메모가 적을 때는 편하지만,
이번 편 목표인 “서버+URL”과 결이 다릅니다.
필요해지면 그때 추가하세요.

자주 하는 실수

1. searchParams를 await 안 함
→ 최근 Next에서는 Promise인 경우가 많음

2. 정렬 링크에서 q를 빠뜨림
→ 정렬 바꾸면 검색어가 사라짐. 링크에 q 유지

3. contains에 빈 문자열
→ trim() 후 없을 때는 where에 넣지 않기

4. 목록을 Client로 통째로 올리고 fetch
→ 이 편 패턴이면 서버 getMemos로 충분

5. Postgres mode: "insensitive"를 SQLite에 그대로
→ 에러 날 수 있음. DB에 맞게

이 편에서 가져갈 것

목록 필터 상태는 URL 쿼리가 기본이다
검색은 GET 폼, 쓰기는 Server Action
Prisma where / orderBy로 서버에서 거른다
검색어와 정렬을 링크에 같이 실어 상태를 유지한다

다음으로 이어가면 좋은 것

입문 + 실전 FAQ / 시리즈 총정리 — 지금까지 막혔던 포인트 모음

검색·정렬까지 오면 메모 앱의 “일상 UX”는 한 바퀴 돈 셈입니다.

시리즈 목차 (실전)

메모 수정과 삭제
Prisma + SQLite로 DB 붙이기
Vercel에 배포하기
폼 검증하기 (zod)
로그인 붙이기 (Clerk)
Neon Postgres 연결하기
삭제 확인 UI
목록 검색과 정렬 ← 지금

# [Next.js + TS 실전] 7. 삭제 확인 UI

JaeSung Kim — Fri, 31 Jul 2026 09:10:05 +0900

[Next.js + TS 실전] 7. 삭제 확인 UI

지금은 상세 페이지에서 삭제를 누르면 바로 지워집니다.
이번 편은 실수로 누르는 걸 막는 확인 단계를 붙입니다.
목표: window.confirm → 작은 Client 버튼 컴포넌트.

이 편에서 할 일

왜 확인이 필요한지 이해하기
DeleteMemoButton 클라이언트 컴포넌트 만들기
상세 페이지 폼에 연결하기
(선택) 간단한 모달로 바꾸기

Server Action·DB는 그대로입니다.
누르는 순간만 Client에서 한 번 막습니다.

지금 코드의 문제

상세 페이지 대략:

<form action={deleteMemoAction}>
  <input type="hidden" name="id" value={memo.id} />
  <button type="submit">삭제</button>
</form>

한 번 클릭 = 즉시 삭제 + /memos로 이동.

실무에서는 보통:

삭제 클릭
“정말 삭제할까요?”
확인 → 그때 서버로 전송

접근 두 가지

방식	장점	단점
`window.confirm`	코드 최소, 바로 동작	브라우저 기본 UI라 못생김
모달	디자인·문구 자유	컴포넌트가 조금 김

이번 편 추천은 confirm 먼저입니다.
패턴만 익히고, 나중에 모달로 갈아끼우면 됩니다.

1) DeleteMemoButton 만들기

경로: components/DeleteMemoButton.tsx

"use client";

type DeleteMemoButtonProps = {
  memoTitle: string;
};

export default function DeleteMemoButton({ memoTitle }: DeleteMemoButtonProps) {
  function handleClick(e: React.MouseEvent<HTMLButtonElement>) {
    const ok = window.confirm(
      `"${memoTitle}" 메모를 삭제할까요?\n삭제하면 되돌릴 수 없습니다.`
    );

    if (!ok) {
      e.preventDefault();
    }
  }

  return (
    <button type="submit" onClick={handleClick}>
      삭제
    </button>
  );
}

포인트:

'use client' → onClick / window 사용
type="submit" → 확인했을 때만 폼이 제출됨
preventDefault() → 취소하면 서버 Action이 안 불림
페이지 전체가 아니라 버튼만 Client (5편 패턴)

2) 상세 페이지에 연결

app/memos/[id]/page.tsx의 삭제 부분만 바꿉니다.

import Link from "next/link";
import { notFound } from "next/navigation";
import { deleteMemoAction } from "@/app/memos/actions";
import { getMemoById } from "@/lib/memos";
import DeleteMemoButton from "@/components/DeleteMemoButton";

type MemoDetailPageProps = {
  params: Promise<{ id: string }>;
};

export default async function MemoDetailPage({ params }: MemoDetailPageProps) {
  const { id } = await params;
  const memo = await getMemoById(id);

  if (!memo) {
    notFound();
  }

  return (
    <main>
      <h1>{memo.title}</h1>
      <p>{memo.content}</p>
      <time dateTime={memo.createdAt}>{memo.createdAt}</time>

      <p>
        <Link href={`/memos/${memo.id}/edit`}>수정</Link>
      </p>

      <form action={deleteMemoAction}>
        <input type="hidden" name="id" value={memo.id} />
        <DeleteMemoButton memoTitle={memo.title} />
      </form>
    </main>
  );
}

Clerk를 붙였다면 getMemoById(id, userId) 형태일 수 있습니다.
이번 편에서 바꾸는 건 삭제 버튼뿐입니다.

동작 확인

/memos/어떤id 상세로 이동
삭제 클릭
확인 창에서 취소 → 그대로 상세에 머무름
다시 삭제 → 확인 → 목록으로 이동하고 메모 사라짐

(선택) 간단한 모달

confirm이 밋밋하면 같은 자리에 모달을 넣을 수 있습니다.

"use client";

import { useState } from "react";

type DeleteMemoButtonProps = {
  memoTitle: string;
};

export default function DeleteMemoButton({ memoTitle }: DeleteMemoButtonProps) {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>
        삭제
      </button>

      {open && (
        <div
          role="dialog"
          aria-modal="true"
          style={{
            position: "fixed",
            inset: 0,
            background: "rgba(0,0,0,0.4)",
            display: "grid",
            placeItems: "center",
          }}
        >
          <div style={{ background: "white", padding: 16, minWidth: 280 }}>
            <p>
              <strong>{memoTitle}</strong> 을(를) 삭제할까요?
            </p>
            <p>삭제하면 되돌릴 수 없습니다.</p>

            <button type="button" onClick={() => setOpen(false)}>
              취소
            </button>
            {" "}
            <button type="submit" onClick={() => setOpen(false)}>
              삭제하기
            </button>
          </div>
        </div>
      )}
    </>
  );
}

주의:

바깥 삭제는 type="button" (폼 즉시 제출 방지)
모달 안 삭제하기만 type="submit"
이 버튼들은 반드시 <form action={deleteMemoAction}> 안에 있어야 함

접근성·포커스 트랩까지 가면 라이브러리(모달)를 쓰는 편이 낫습니다.
학습용으로는 위 수준이면 충분합니다.

왜 Action은 그대로인가

확인 UI는 브라우저 UX입니다.
진짜 삭제는 여전히 서버의 deleteMemoAction이 합니다.

그래서:

확인을 우회하는 요청이 올 수도 있음 → Action에서 id/권한 검증은 유지
UI만 Client, 삭제로직은 Server

보안을 confirm에 맡기지 마세요.
confirm은 실수 방지용입니다.

자주 하는 실수

1. 페이지 전체를 'use client'
→ 버튼만 Client로 분리

2. confirm 취소를 안 막고 submit
→ preventDefault() 필요

3. 모달의 삭제 버튼을 form 밖에 둠
→ action이 연결되지 않음

4. type="submit"인 첫 버튼이 모달을 안 거침
→ 열기 버튼은 type="button"

이 편에서 가져갈 것

삭제는 확인 한 단계가 있는 편이 안전하다
window.confirm으로 최소 구현 가능하다
인터랙션만 Client 컴포넌트로 뺀다
확인 UI ≠ 권한/검증 (Server Action은 그대로)

다음으로 이어가면 좋은 것

목록 검색·정렬
입문+실전 FAQ / 시리즈 총정리

시리즈 목차 (실전)

메모 수정과 삭제
Prisma + SQLite로 DB 붙이기
Vercel에 배포하기
폼 검증하기 (zod)
로그인 붙이기 (Clerk)
Neon Postgres 연결하기
삭제 확인 UI ← 지금

# [Next.js + TS 실전] 6. Neon Postgres 연결하기

JaeSung Kim — Fri, 31 Jul 2026 09:03:42 +0900

[Next.js + TS 실전] 6. Neon Postgres 연결하기

실전 3편에서 “Vercel에는 SQLite 파일 DB가 안 맞다”고 했습니다.
이번 편은 Neon(Postgres) 으로 바꿔, 배포 환경에서도 메모가 남게 합니다.
목표: provider 변경 · 마이그레이션 · 로컬/Vercel DATABASE_URL.

이 편에서 할 일

왜 Neon인지 짧게 이해하기
Neon 프로젝트 만들고 연결 문자열 받기
Prisma provider를 postgresql로 바꾸기
마이그레이션을 Postgres에 적용하기
Vercel 환경 변수에 DATABASE_URL 넣기

앱 코드(lib/memos.ts, Action, 페이지)는 거의 안 바꿉니다.
바꾸는 건 DB 종류와 연결 정보입니다.

왜 Neon인가

선택	한 줄
Neon	서버리스 Postgres, 무료 티어, Prisma와 궁합 좋음
Supabase	Postgres + 부가 기능이 많음 (이번 편 범위 밖)
로컬 SQLite	로컬 학습용으로 계속 써도 됨

Neon을 고른 이유:

Vercel 같은 서버리스와 잘 맞음
Connection string만 바꾸면 Prisma가 거의 그대로 동작
무료로 시작하기 쉬움

UI 메뉴 이름은 자주 바뀝니다.
프로젝트 생성 → Connection string 복사 만 기억하면 됩니다.

전체 그림

로컬 / Vercel 앱
      ↓
 DATABASE_URL (환경 변수)
      ↓
 Prisma Client
      ↓
 Neon Postgres (클라우드)

SQLite 때:

DATABASE_URL="file:./dev.db"

Neon 때:

DATABASE_URL="postgresql://..."

1) Neon에서 DB 만들기

https://neon.tech 가입
새 프로젝트 생성
Connection string 복사
(보통 postgresql://... 형태)

예시 형태 (값은 본인 것):

postgresql://USER:PASSWORD@HOST/neondb?sslmode=require

비밀번호가 들어 있습니다. GitHub에 올리지 마세요.
.env / Vercel Environment Variables에만 둡니다.

2) 로컬 `.env` 바꾸기

memo-app/.env:

DATABASE_URL="postgresql://USER:PASSWORD@HOST/neondb?sslmode=require"
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

이전 SQLite용 file:./dev.db는 주석 처리하거나 지웁니다.

로컬에서도 Neon을 쓰면:

PC를 꺼도 데이터가 클라우드에 남음
팀원과 같은 DB를 볼 수 있음 (주의: 연습용 키 관리)

원하면 로컬은 SQLite, 배포만 Neon으로 나눌 수도 있습니다.
이번 편은 로컬도 Neon으로 통일해서 흐름을 단순하게 갑니다.

3) Prisma 스키마: provider 변경

prisma/schema.prisma:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Memo {
  id        String   @id @default(cuid())
  title     String
  content   String
  userId    String
  createdAt DateTime @default(now())

  @@index([userId])
}

바뀐 핵심은 한 줄입니다.

provider = "sqlite"  →  provider = "postgresql"

Memo 모델은 그대로입니다.
(@@index([userId])는 있으면 조회에 도움이 됩니다.)

4) 마이그레이션을 Neon에 적용

SQLite용 마이그레이션 히스토리가 있으면 Postgres와 충돌할 수 있습니다.
연습 단계에서는 아래 둘 중 하나를 고르세요.

방법 A) 새 DB에 스키마만 밀어넣기 (가장 단순)

테이블이 비어 있는 Neon이라면:

npx prisma db push
npx prisma generate

db push는 마이그레이션 파일 없이 스키마를 DB에 맞춥니다.
프로토타입·학습에 편합니다.

방법 B) migrate로 정식 적용

npx prisma migrate dev --name postgres-init

기존 SQLite 마이그레이션 폴더 때문에 꼬이면:

prisma/migrations를 백업/삭제 (로컬 연습 한정)
다시 migrate dev --name init

실서비스에서는 히스토리를 함부로 지우면 안 됩니다.
혼자 쓰는 메모 앱 연습이라면 A 또는 “migrations 초기화 후 다시”가 현실적입니다.

시드:

npx prisma db seed

시드의 userId: "seed-user"는 Clerk 로그인 유저와 다릅니다.
목록 확인은 로그인 후 새 메모 작성으로 하세요.

5) 동작 확인 (로컬)

npm run dev

로그인
/memos/new에서 메모 작성
Neon Console → Tables에서 행이 보이는지 확인

보이면 클라우드 DB 연결 성공입니다.

6) Vercel에 DATABASE_URL 넣기

Vercel Project → Settings → Environment Variables
추가:

Name	Value
`DATABASE_URL`	Neon 연결 문자열
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Clerk 공개 키
`CLERK_SECRET_KEY`	Clerk 비밀 키

Production / Preview 체크
Redeploy

빌드 스크립트 권장 (package.json):

{
  "scripts": {
    "dev": "next dev",
    "build": "prisma generate && next build",
    "start": "next start",
    "postinstall": "prisma generate"
  }
}

Vercel 빌드 머신에서 Prisma Client가 생성되게 합니다.

프로덕션 마이그레이션은 보통:

npx prisma migrate deploy

을 CI나 배포 전에 한 번 실행합니다.
db push로만 맞춰 둔 상태면, 배포 전에도 스키마가 Neon에 이미 있어야 합니다.

코드는 왜 거의 안 바꾸나

lib/memos.ts는 여전히:

await prisma.memo.findMany({ where: { userId }, ... })

Prisma가 SQL 방언(SQLite vs Postgres)을 감춥니다.
그래서 실전 2편에서 데이터 레이어를 분리해 둔 것이 여기서 이득이 됩니다.

가끔 달라지는 것:

일부 raw SQL
타입/기본값 디테일
연결 풀 (서버리스에서는 Neon의 pooled URL을 쓰는 경우도 있음)

입문 다음 단계에서는 Connection string 하나로 충분합니다.
연결이 불안정하면 Neon 대시보드의 pooled connection 문자열을 써 보세요.

자주 하는 실수

1. .env의 따옴표/복붙 깨짐
→ 비밀번호에 특수문자가 있으면 URL 인코딩 필요할 수 있음

2. Vercel에 DATABASE_URL 안 넣음
→ 로컬만 되고 배포만 실패

3. SQLite dev.db를 그대로 커밋/배포 기대
→ Neon으로 바꾼 뒤에는 의미 없음

4. provider만 바꾸고 migrate/db push를 안 함
→ 테이블이 없어 런타임 에러

5. Clerk 키는 넣었는데 DB URL만 빠짐 (또는 반대)
→ 로그인 되는데 저장 실패 / 저장은 되는데 로그인 실패

6. 시드 메모가 로그인 목록에 안 보임
→ userId: "seed-user"라서 정상. 새 글로 확인

이 편에서 가져갈 것

Vercel 배포 앱의 DB는 외부 Postgres가 맞다
Neon = 시작하기 쉬운 서버리스 Postgres
Prisma는 provider + DATABASE_URL만 바꿔도 앱 코드를 유지하기 쉽다
비밀 값은 .env / Vercel env에만 둔다
로컬에서 한 번 쓰고, 같은 URL(또는 별도 prod URL)을 배포에 연결한다

다음에 이어가면 좋은 것

삭제 확인 UI / 목록 검색 (짧은 UX 보강)
시리즈 FAQ·총정리
로컬 SQLite + 배포 Neon을 .env로 나누는 팀 워크플로

시리즈 목차 (실전)

메모 수정과 삭제
Prisma + SQLite로 DB 붙이기
Vercel에 배포하기
폼 검증하기 (zod)
로그인 붙이기 (Clerk)
Neon Postgres 연결하기 ← 지금

# 면접 CS 정리 Day 3 (풀스택 / Java·Spring·React)

JaeSung Kim — Fri, 31 Jul 2026 08:25:13 +0900

면접 CS 정리 Day 3 (풀스택 / Java·Spring·React)

Q1. 401 vs 403

문제
HTTP 상태코드 401이랑 403 차이?

답

401: 인증이 안 됨 (로그인/토큰 없음·만료)
403: 인증은 됐지만 권한이 없음

한 줄: 401 = 누구인지 모름 / 403 = 누군진 알지만 못 함.

Q2. 복합 인덱스 좌측 접두어

문제
복합 인덱스 (user_id, created_at)이 있을 때
아래 중 인덱스를 잘 타는 것 / 못 타는 것은?

A. WHERE user_id = ?
B. WHERE created_at = ?
C. WHERE user_id = ? AND created_at = ?

답

A: 탐 (왼쪽 컬럼)
B: 못 탐 (앞 컬럼 스킵)
C: 가장 잘 탐 (인덱스 전부 활용)

복합 인덱스는 왼쪽 컬럼부터 써야 한다.

Q3. Dirty Read

문제
Dirty Read가 뭔지 한 줄, 막는 격리수준 이름은?

답
Dirty Read = 다른 트랜잭션이 커밋하기 전 데이터를 읽는 것.
막는 수준: READ COMMITTED

Q4. HashMap vs ConcurrentHashMap

문제
HashMap이랑 ConcurrentHashMap 차이? 멀티스레드에서 뭘 써야 하는지.

답
HashMap은 스레드 안전하지 않아서, 여러 스레드가 동시에 쓰면
데이터가 깨지거나 예외가 날 수 있다.
공유 Map이면 ConcurrentHashMap을 쓴다.

Q5. @Controller vs @RestController

문제
Spring @Controller랑 @RestController 차이?

답

@Controller: 보통 화면(뷰) 반환
@RestController: @Controller + @ResponseBody
→ 반환값이 뷰 이름이 아니라 JSON 등 응답 본문

REST API는 @RestController를 주로 쓴다.

Q6. XSS vs CSRF

문제
XSS랑 CSRF 차이 한 줄씩.

답

XSS: 페이지에 악의적 스크립트를 삽입해 실행시키는 공격
CSRF: 로그인된 사용자 브라우저로 원치 않는 요청을 보내게 하는 공격

XSS 완화 예: 출력 이스케이프, 쿠키 HttpOnly
CSRF 완화 예: CSRF 토큰, 쿠키 SameSite

Q7. N+1 문제

문제
N+1 문제가 뭔지, 목록 조회할 때 어떻게 발생하고 어떻게 줄이는지?

답
목록 조회 1번 후, 각 행마다 연관 데이터를 N번 추가 조회하는 문제.
(총 1+N번 쿼리)

줄이는 방법:

JPA: fetch join, @EntityGraph, 배치 조회(IN)
MyBatis: JOIN 한 방, id 목록 IN 조회 후 조립

오늘 한 줄 암기

401 = 인증 X / 403 = 권한 X
복합 인덱스 (A,B) → A OK, B만 NO
Dirty Read → READ COMMITTED
멀티스레드 Map → ConcurrentHashMap
N+1 = 목록 1 + 건별 N → fetch join / JOIN / IN

다음 목표

복합 인덱스 A도 탄다는 점까지 항상 말하기
XSS/CSRF 방어 수단 한 가지씩 더 정리

# [Next.js + TS 실전] 5. 로그인 붙이기 (Clerk)

JaeSung Kim — Thu, 30 Jul 2026 13:05:03 +0900

[Next.js + TS 실전] 5. 로그인 붙이기 (Clerk)

지금까지 메모 앱은 누구나 같은 목록을 보고 고칠 수 있습니다.
이번 편은 로그인을 붙이고, 내 메모만 보이게 만듭니다.
도구: Clerk (Next.js App Router와 연동이 단순함)

이 편에서 할 일

왜 직접 인증을 안 짜는지 짧게 이해하기
Clerk 프로젝트·키·패키지 준비
ClerkProvider + 미들웨어 + auth.protect()로 보호
내비에 로그인/유저 버튼 넣기
Prisma Memo에 userId 추가 → 내 메모만 CRUD

UI 클릭 경로는 Clerk 대시보드가 자주 바뀝니다.
키 발급 → env → 코드 연결 흐름만 정확히 따라가면 됩니다.

왜 Clerk인가

직접 만들면 대략 이만큼입니다.

회원가입 / 로그인 / 세션 / 쿠키
비밀번호 해시, 이메일 인증
로그아웃, 비밀번호 찾기…

학습 목표가 “인증 프로토콜”이 아니라면,
검증된 서비스 + SDK로 붙이는 편이 앱에 집중하기 좋습니다.

Clerk를 고른 이유:

Next App Router 공식 가이드가 친절함
<SignInButton />, <UserButton /> 같은 UI가 바로 있음
서버에서 auth()로 현재 유저 id를 얻기 쉬움

나중에 Auth.js 등으로 바꿔도 “보호된 라우트 + userId로 데이터 필터” 개념은 같습니다.

전체 그림

브라우저
  ↓
Clerk (로그인/세션)
  ↓
Next 미들웨어 (세션 연결)
  ↓
app/memos/layout (auth.protect)
  ↓
Server Action / Prisma
  ↓
Memo.userId === 현재 유저만 조회·수정·삭제

로그인만 하고 DB를 안 나누면,
여전히 남의 메모가 전부 보입니다.
이번 편의 진짜 목표는 userId 연결입니다.

1) Clerk 계정·애플리케이션

https://clerk.com 가입
새 Application 생성 (Next.js 선택)
API Keys에서 아래 두 값을 복사

이름	용도
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	브라우저에 노출돼도 되는 공개 키
`CLERK_SECRET_KEY`	서버 전용. GitHub에 올리면 안 됨

memo-app/.env (또는 .env.local)에 추가:

DATABASE_URL="file:./dev.db"
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

.gitignore에 .env / .env.local이 있는지 다시 확인하세요.

2) 패키지 설치

npm install @clerk/nextjs

3) 미들웨어 + 페이지(레이아웃)에서 보호

Next.js 16은 네트워크 경계 파일 이름이 proxy.ts인 경우가 있고,
15 이하는 보통 middleware.ts입니다.
(공식 문서가 middleware.ts를 말하면, 버전 기준으로 파일명만 맞추면 됩니다.)

`proxy.ts` — Clerk 연결만

경로: memo-app/proxy.ts (또는 middleware.ts)

import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: [
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
    "/(api|trpc)(.*)",
  ],
};

최신 @clerk/nextjs에서는 createRouteMatcher로 미들웨어에서 경로를 막는 방식이 deprecated입니다.
미들웨어는 Clerk 세션만 연결하고, 보호는 각 페이지/레이아웃에서 합니다.

`app/memos/layout.tsx` — /memos 전체 보호

import { auth } from "@clerk/nextjs/server";

export default async function MemosLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  await auth.protect();
  return children;
}

의미:

/memos, /memos/new, /memos/1 … → 이 레이아웃을 거치므로 로그인 필요
/ (홈) → 레이아웃 밖이라 비로그인 가능
auth.protect() → 없으면 로그인 화면으로

4) 레이아웃에 ClerkProvider + 버튼

app/layout.tsx (루트 레이아웃):

import Link from "next/link";
import type { Metadata } from "next";
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  Show,
  UserButton,
} from "@clerk/nextjs";
import "./globals.css";

export const metadata: Metadata = {
  title: "Memo App",
  description: "Next.js + TypeScript 실습",
};

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="ko">
      <body>
        <ClerkProvider>
          <header>
            <nav>
              <Link href="/">홈</Link>
              {" | "}
              <Link href="/memos">메모</Link>
              {" | "}
              <Show when="signed-out">
                <SignInButton /> <SignUpButton />
              </Show>
              <Show when="signed-in">
                <UserButton />
              </Show>
            </nav>
          </header>
          {children}
        </ClerkProvider>
      </body>
    </html>
  );
}

컴포넌트	역할
`ClerkProvider`	앱 전체에 Clerk 컨텍스트 (`<body>` 안)
`Show when="signed-out"`	로그아웃일 때 보일 UI
`Show when="signed-in"`	로그인일 때 보일 UI
`SignInButton` / `SignUpButton`	로그인·가입
`UserButton`	프로필·로그아웃

예전 SignedIn / SignedOut은 최신 Clerk에서 Show 로 바뀌었습니다.

npm run dev 후 홈에서 로그인 → /memos 접근이 되면 1차 성공입니다.

5) Prisma: 메모에 주인(`userId`) 붙이기

스키마를 바꿉니다. prisma/schema.prisma:

model Memo {
  id        String   @id @default(cuid())
  title     String
  content   String
  userId    String
  createdAt DateTime @default(now())

  @@index([userId])
}

마이그레이션:

npx prisma migrate dev --name add-memo-user-id

이미 시드/메모가 있다면 userId 때문에 충돌할 수 있습니다.
연습 단계면 DB를 비우고 다시 만들어도 됩니다.

npx prisma migrate reset

(reset은 데이터 삭제 + 마이그레이션 + 시드. 로컬에서만.)

시드(prisma/seed.ts)에도 임시 userId가 필요합니다.
예: "seed-user" — 나중에 실제 Clerk 유저 id와는 다릅니다.
실습은 로그인 후 새로 만든 메모로 확인하는 편이 낫습니다.

6) 데이터 레이어: 내 것만

lib/memos.ts를 userId 기준으로 바꿉니다.

import type { Memo } from "@/types/memo";
import { prisma } from "@/lib/prisma";

function toMemo(row: {
  id: string;
  title: string;
  content: string;
  createdAt: Date;
}): Memo {
  return {
    id: row.id,
    title: row.title,
    content: row.content,
    createdAt: row.createdAt.toISOString().slice(0, 10),
  };
}

export async function getMemos(userId: string): Promise<Memo[]> {
  const rows = await prisma.memo.findMany({
    where: { userId },
    orderBy: { createdAt: "desc" },
  });
  return rows.map(toMemo);
}

export async function getMemoById(
  id: string,
  userId: string
): Promise<Memo | undefined> {
  const row = await prisma.memo.findFirst({
    where: { id, userId },
  });
  return row ? toMemo(row) : undefined;
}

export async function addMemo(
  userId: string,
  input: { title: string; content: string }
): Promise<Memo> {
  const row = await prisma.memo.create({
    data: {
      userId,
      title: input.title,
      content: input.content,
    },
  });
  return toMemo(row);
}

export async function updateMemo(
  id: string,
  userId: string,
  input: { title: string; content: string }
): Promise<Memo | undefined> {
  try {
    const row = await prisma.memo.update({
      where: { id },
      data: input,
    });
    // 남의 메모면 위에서 이미 다른 유저 것일 수 있으니, 소유권 확인
    if (row.userId !== userId) {
      return undefined;
    }
    return toMemo(row);
  } catch {
    return undefined;
  }
}

export async function deleteMemo(
  id: string,
  userId: string
): Promise<boolean> {
  const existing = await prisma.memo.findFirst({
    where: { id, userId },
  });
  if (!existing) return false;

  await prisma.memo.delete({ where: { id } });
  return true;
}

더 안전한 update 패턴 (추천):

const result = await prisma.memo.updateMany({
  where: { id, userId },
  data: input,
});
if (result.count === 0) return undefined;
return getMemoById(id, userId);

updateMany + where: { id, userId }면 남의 id를 알아도 수정이 안 됩니다.

7) Action / 페이지에서 `auth()`로 userId

서버에서 현재 유저:

import { auth } from "@clerk/nextjs/server";

const { userId } = await auth();
if (!userId) {
  throw new Error("로그인이 필요합니다");
}

createMemo 예시 핵심만:

const { userId } = await auth();
if (!userId) {
  return { ok: false, message: "로그인이 필요합니다", values };
}

// ... zod 검증 후
await addMemo(userId, parsed.data);

목록 페이지:

import { auth } from "@clerk/nextjs/server";
import { redirect } from "next/navigation";
import { getMemos } from "@/lib/memos";

export default async function MemosPage() {
  const { userId } = await auth();
  if (!userId) redirect("/");

  const memos = await getMemos(userId);
  // ... 기존 UI
}

상세·수정도 getMemoById(id, userId)로 바꿉니다.
없으면 notFound() — 남 메모 URL을 쳐도 404.

updateMemoAction / deleteMemoAction에도 똑같이 userId를 넘기세요.

동작 확인 체크리스트

로그아웃 상태에서 /memos → 로그인으로 유도
가입/로그인 후 메모 작성
목록에 내 메모만 보임
(가능하면) 다른 계정으로 로그인 → 이전 계정 메모가 안 보임
다른 유저 메모 id를 URL에 넣으면 404

한 계정만 있어도 1~3이면 기본 연동은 성공입니다.

자주 하는 실수

1. CLERK_SECRET_KEY를 클라이언트에 노출
→ NEXT_PUBLIC_ 붙이지 말 것

2. 미들웨어만 하고 DB는 그대로
→ 로그인은 됐는데 데이터는 공유. userId 필수

3. auth()를 await 안 함
→ 최신 SDK는 await auth()

4. update를 where: { id }만 함
→ id를 알면 남의 글 수정 가능. 반드시 userId 조건

5. env를 넣고 서버를 안 재시작
→ .env 변경 후 npm run dev 다시

6. Root에 Clerk를 설치하고 memo-app에서 import
→ 패키지·env는 memo-app 기준

이 편에서 가져갈 것

인증은 직접 구현보다 서비스+SDK가 실무에서 흔하다
미들웨어 = Clerk 세션 연결 (clerkMiddleware)
접근 보호 = 레이아웃/페이지에서 auth.protect()
auth().userId = 서버에서 “지금 누구인지”
보호의 핵심은 DB 쿼리에 userId를 넣는 것
UI 컴포넌트(SignInButton 등)와 데이터 소유권은 같이 설계한다

다음으로 이어가면 좋은 것

Neon Postgres + Vercel에 CLERK_* 환경 변수까지 넣어 배포본 로그인
조직(Organization) / 역할(role) — 팀 메모
Auth.js로 같은 구조를 직접 비교

시리즈 목차 (실전)

메모 수정과 삭제
Prisma + SQLite로 DB 붙이기
Vercel에 배포하기
폼 검증하기 (zod)
로그인 붙이기 (Clerk) ← 지금

# [Next.js + TS 실전] 4. 폼 검증하기 (zod)

JaeSung Kim — Thu, 30 Jul 2026 10:57:55 +0900

[Next.js + TS 실전] 4. 폼 검증하기 (zod)

지금까지 검증은 if (!title) + throw new Error 수준이었습니다.
이번 편은 필드별 메시지를 폼 아래에 보여 줍니다.
목표: zod 스키마 · Server Action 반환값 · useActionState.

이 편에서 할 일

왜 throw만으로는 UX가 약한지 이해하기
zod로 메모 입력 규칙 정하기
createMemo가 성공/실패 결과를 반환하게 바꾸기
클라이언트 폼에서 useActionState로 에러 표시하기
수정 폼에도 같은 패턴 적용하기

DB·배포는 건드리지 않습니다.
이미 있는 작성/수정 폼의 품질만 올립니다.

지금 방식의 한계

현재 Action 대략:

if (!title || !content) {
  throw new Error("제목과 내용을 모두 입력하세요");
}

문제:

어떤 필드가 문제인지 모호하다
화면에는 error.tsx로 크게 깨지거나, 메시지가 폼과 떨어져 보인다
HTML required만 믿으면 브라우저마다 다르고, 서버 검증과 중복된다

원하는 UX:

제목
[                    ]
→ 제목은 1자 이상 입력하세요

내용
[                    ]
→ 내용은 1자 이상 입력하세요

전체 흐름

폼 제출
  ↓
createMemo (Server Action)
  ↓
zod로 검증
  ├─ 실패 → { ok: false, errors, values } 반환 (페이지 유지)
  └─ 성공 → DB 저장 후 redirect
  ↓
useActionState가 state를 받아 에러 표시

핵심 변화:

실패할 때 throw하지 않고 객체를 반환
폼이 그 객체를 읽어 메시지를 그림

1) zod 설치

memo-app에서:

npm install zod

zod = TypeScript와 잘 맞는 스키마 검증 라이브러리입니다.
“이 값은 이런 모양이어야 한다”를 한곳에서 선언합니다.

2) 스키마 파일

경로: lib/memo-schema.ts

import { z } from "zod";

export const memoFormSchema = z.object({
  title: z
    .string()
    .trim()
    .min(1, "제목은 1자 이상 입력하세요")
    .max(100, "제목은 100자 이하여야 합니다"),
  content: z
    .string()
    .trim()
    .min(1, "내용은 1자 이상 입력하세요")
    .max(5000, "내용은 5000자 이하여야 합니다"),
});

export type MemoFormInput = z.infer<typeof memoFormSchema>;

export type MemoFormState = {
  ok: boolean;
  message?: string;
  errors?: {
    title?: string[];
    content?: string[];
  };
  values?: {
    title: string;
    content: string;
  };
};

포인트:

코드	의미
`z.object`	폼 필드 묶음
`min` / `max`	길이 규칙 + 한국어 메시지
`z.infer`	스키마에서 TS 타입 자동 추출
`MemoFormState`	Action이 폼에 돌려줄 상태

errors.title을 배열로 둔 이유: zod가 필드당 메시지를 배열로 주기 때문입니다.

3) `createMemo`를 “결과 반환”형으로

app/memos/actions.ts의 생성 액션을 바꿉니다.

"use server";

import { z } from "zod";
import { redirect } from "next/navigation";
import { revalidatePath } from "next/cache";
import { addMemo, deleteMemo, updateMemo } from "@/lib/memos";
import { memoFormSchema, type MemoFormState } from "@/lib/memo-schema";

export async function createMemo(
  _prevState: MemoFormState,
  formData: FormData
): Promise<MemoFormState> {
  const values = {
    title: String(formData.get("title") ?? ""),
    content: String(formData.get("content") ?? ""),
  };

  const parsed = memoFormSchema.safeParse(values);

  if (!parsed.success) {
    return {
      ok: false,
      // Zod 4: parsed.error.flatten() 대신 z.flattenError
      errors: z.flattenError(parsed.error).fieldErrors,
      values,
    };
  }

  await addMemo(parsed.data);

  revalidatePath("/memos");
  redirect("/memos");
}

바뀐 점:

인자가 (prevState, formData) — useActionState 규약
safeParse — 실패해도 throw하지 않음
실패 시 errors + 사용자가 친 values를 돌려줌 (입력 유지)
성공 시만 redirect

deleteMemoAction은 이번 편에서 그대로 둬도 됩니다.

4) 작성 폼을 Client로 (에러 표시)

useActionState는 훅이라 클라이언트 컴포넌트가 필요합니다.
페이지 전체를 클라이언트로 올리기보다, 폼만 분리합니다. (5편 패턴)

경로: components/MemoForm.tsx

"use client";

import { useActionState } from "react";
import type { MemoFormState } from "@/lib/memo-schema";

type MemoFormProps = {
  action: (
    prevState: MemoFormState,
    formData: FormData
  ) => Promise<MemoFormState>;
  initialTitle?: string;
  initialContent?: string;
  submitLabel?: string;
  hiddenFields?: Record<string, string>;
};

const initialState: MemoFormState = { ok: true };

export default function MemoForm({
  action,
  initialTitle = "",
  initialContent = "",
  submitLabel = "저장",
  hiddenFields,
}: MemoFormProps) {
  const [state, formAction, pending] = useActionState(action, initialState);

  const titleValue = state.values?.title ?? initialTitle;
  const contentValue = state.values?.content ?? initialContent;

  return (
    <form action={formAction}>
      {hiddenFields &&
        Object.entries(hiddenFields).map(([name, value]) => (
          <input key={name} type="hidden" name={name} value={value} />
        ))}

      <p>
        <label>
          제목
          <br />
          <input
            type="text"
            name="title"
            defaultValue={titleValue}
            key={`title-${titleValue}`}
          />
        </label>
        {state.errors?.title?.[0] && (
          <span style={{ color: "crimson" }}>{state.errors.title[0]}</span>
        )}
      </p>

      <p>
        <label>
          내용
          <br />
          <textarea
            name="content"
            rows={5}
            defaultValue={contentValue}
            key={`content-${contentValue}`}
          />
        </label>
        {state.errors?.content?.[0] && (
          <span style={{ color: "crimson" }}>{state.errors.content[0]}</span>
        )}
      </p>

      <button type="submit" disabled={pending}>
        {pending ? "저장 중..." : submitLabel}
      </button>
    </form>
  );
}

포인트:

useActionState(action, initialState) → [state, formAction, pending]
defaultValue + key로 검증 실패 후 입력값 유지
pending으로 저장 중 버튼 비활성
HTML required는 빼도 됩니다 (서버+zod가 진실)

JSX를 <pre> 안에 넣을 때 < >로 이스케이프했습니다.
실제 파일에는 일반 <form>, <input>을 쓰세요.

5) 새 메모 페이지 연결

app/memos/new/page.tsx:

import MemoForm from "@/components/MemoForm";
import { createMemo } from "@/app/memos/actions";

export default function NewMemoPage() {
  return (
    <main>
      <h1>새 메모</h1>
      <MemoForm action={createMemo} />
    </main>
  );
}

확인:

/memos/new
제목·내용 비우고 저장
필드 아래 빨간 메시지
올바르게 입력하면 /memos로 이동

6) 수정도 같은 패턴

updateMemoAction도 (prevState, formData)로 맞춥니다.

export async function updateMemoAction(
  _prevState: MemoFormState,
  formData: FormData
): Promise<MemoFormState> {
  const id = String(formData.get("id") ?? "").trim();
  const values = {
    title: String(formData.get("title") ?? ""),
    content: String(formData.get("content") ?? ""),
  };

  if (!id) {
    return { ok: false, message: "메모 id가 없습니다", values };
  }

  const parsed = memoFormSchema.safeParse(values);

  if (!parsed.success) {
    return {
      ok: false,
      errors: z.flattenError(parsed.error).fieldErrors,
      values,
    };
  }

  const updated = await updateMemo(id, parsed.data);

  if (!updated) {
    return { ok: false, message: "메모를 찾을 수 없습니다", values };
  }

  revalidatePath("/memos");
  revalidatePath(`/memos/${id}`);
  redirect(`/memos/${id}`);
}

app/memos/[id]/edit/page.tsx:

import { notFound } from "next/navigation";
import MemoForm from "@/components/MemoForm";
import { updateMemoAction } from "@/app/memos/actions";
import { getMemoById } from "@/lib/memos";

type EditMemoPageProps = {
  params: Promise<{ id: string }>;
};

export default async function EditMemoPage({ params }: EditMemoPageProps) {
  const { id } = await params;
  const memo = await getMemoById(id);

  if (!memo) {
    notFound();
  }

  return (
    <main>
      <h1>메모 수정</h1>
      <MemoForm
        action={updateMemoAction}
        initialTitle={memo.title}
        initialContent={memo.content}
        hiddenFields={{ id: memo.id }}
        submitLabel="수정 저장"
      />
    </main>
  );
}

작성·수정이 같은 MemoForm을 씁니다.

`useActionState` 짧게

const [state, formAction, pending] = useActionState(action, initialState);

값	역할
`state`	마지막 Action 반환값 (에러·values)
`formAction`	`<form action={...}>`에 넘김
`pending`	제출 진행 중 여부

예전 useFormState와 같은 계열입니다.
React 19 / 최신 Next에서는 useActionState를 쓰면 됩니다.

왜 스키마를 Action에 두나

브라우저 required만으로도 빈 값은 막을 수 있습니다.
그래도 서버에서 다시 검증합니다.

DevTools로 required를 지우고 제출할 수 있음
API·Action은 폼 말고도 호출될 수 있음
규칙(최대 글자 등)을 한 스키마로 공유 가능

클라이언트에서 zod를 한 번 더 돌리는 “즉시 검증”은 나중에 추가해도 됩니다.
입문 다음 단계에서는 서버 검증 + 메시지 표시만으로 충분합니다.

자주 하는 실수

1. Action 시그니처를 예전 (formData)만 유지
→ useActionState는 (prevState, formData) 필요

2. 실패 시 계속 throw
→ error.tsx로 튕김. 필드 에러는 return { errors }

3. 페이지 전체를 'use client'
→ 폼만 Client, 페이지는 Server 유지

4. safeParse 대신 parse
→ 실패 시 throw. 폼 UX에는 safeParse가 맞음

5. redirect를 try/catch로 감싸서 에러로 착각
→ Next의 redirect는 특수 throw를 씁니다. 성공 경로에서만 호출

이 편에서 가져갈 것

검증 규칙은 zod 스키마로 한곳에 둔다
실패는 throw보다 상태 객체 반환
useActionState로 에러를 필드 옆에 보여 준다
폼만 Client Component로 분리한다
작성·수정은 같은 폼 컴포넌트를 재사용한다

시리즈 목차 (실전)

메모 수정과 삭제
Prisma + SQLite로 DB 붙이기
Vercel에 배포하기
폼 검증하기 (zod) ← 지금

# [Next.js + TS 실전] 3. Vercel에 배포하기

JaeSung Kim — Thu, 30 Jul 2026 10:48:06 +0900

[Next.js + TS 실전] 3. Vercel에 배포하기

실전 2편까지 로컬에서 Prisma + SQLite로 메모가 저장됩니다.
이번 편은 다른 사람이 URL로 접속할 수 있게 배포합니다.
목표: GitHub → Vercel 배포 · 환경 변수 · SQLite 한계와 대안.

이 편에서 할 일

배포 전 로컬 빌드 확인
GitHub에 올리고 Vercel 연결
환경 변수 설정 이해
왜 Vercel에서 SQLite가 힘든지 알기
현실적인 DB 선택지 정리 (Postgres 등)

“버튼 몇 번이면 끝”만 말하지 않습니다.
로컬 SQLite 앱을 그대로 Vercel에 올리면 어디서 막히는지까지 같이 봅니다.

배포가 되면 뭐가 바뀌나

	로컬	배포 후
접속	`localhost:3000`	`https://something.vercel.app`
서버	내 PC	Vercel 클라우드
데이터	`prisma/dev.db` 파일	파일 DB는 보통 유지 안 됨

화면(Next.js) 배포와 데이터 저장은 별개입니다.
이번 편의 핵심도 그 구분입니다.

1) 배포 전: 로컬에서 빌드해 보기

memo-app에서:

npm run build

에러 없이 끝나면 배포 가능성이 높습니다.
여기서 깨지면 Vercel에서도 거의 같은 에러가 납니다.

개발 서버만 켜 보는 것과 다릅니다.

npm run dev → 개발용
npm run build → 프로덕션 결과물 만들기

2) GitHub에 올리기

Vercel은 GitHub 저장소와 연결하는 방식이 가장 쉽습니다.

아직 git이 없다면 memo-app에서:

git init
git add .
git commit -m "Add memo app with Prisma"

.gitignore에 아래가 있는지 확인하세요.

.env
.env*.local
prisma/dev.db
prisma/dev.db-journal
node_modules
.next

GitHub에 새 저장소를 만들고 push:

git remote add origin https://github.com/본인계정/memo-app.git
git branch -M main
git push -u origin main

.env는 올리지 않습니다.
DB URL은 Vercel 대시보드에서 따로 넣습니다.

3) Vercel에 프로젝트 연결

https://vercel.com 가입/로그인 (GitHub 연동 권장)
Add New… → Project
방금 push한 저장소 Import
Root Directory가 memo-app이면 (모노레포인 경우) 그 폴더로 지정
Framework Preset: Next.js (보통 자동)
Deploy

첫 배포는 DB 없이도 프론트가 뜰 수 있지만,
메모 CRUD는 DB URL이 없으면 런타임에서 실패합니다.

4) 왜 SQLite는 Vercel과 안 맞나

로컬 SQLite는 디스크의 한 파일입니다.

Vercel(서버리스)은 대략 이렇게 동작합니다.

요청마다 짧은 수명의 함수가 뜸
파일 시스템은 읽기 위주 / 임시
인스턴스가 여러 개일 수 있음
재배포하면 로컬 파일이 날아감

그래서 file:./dev.db 방식은:

쓰기가 안 되거나
써도 다음 요청/재배포에 사라지거나
인스턴스마다 다른 DB를 보는

문제가 납니다.

한 줄로:

Vercel에 올릴 앱의 “진짜 DB”는 파일이 아니라, 외부 데이터베이스 서비스가 필요하다.

로컬 학습용 SQLite는 여전히 훌륭합니다.
배포 단계에서만 교체하면 됩니다. (실전 2편에서 lib/memos.ts만 바꾼 이유)

5) 배포용 DB 선택지

입문·실전 시리즈 기준으로 현실적인 선택:

선택	특징	추천
Neon / Supabase (Postgres)	Prisma와 궁합 좋음, 무료 티어 있음	⭐ 가장 무난
Turso (libSQL)	SQLite 호환에 가까운 원격 DB	SQLite 감각 유지하고 싶을 때
Prisma Postgres	Prisma 생태계 연동	Prisma 문서 따라가기 쉬움
로컬 SQLite만	배포 CRUD 불가에 가깝음	화면만 배포 데모용

이번 편에서는 방향을 Postgres(Neon 등)로 바꾼다고 잡고,
구체적인 클릭 경로는 서비스 UI가 자주 바뀌므로 공통 절차만 적습니다.

6) Postgres로 바꾸는 큰 그림

(1) 클라우드에서 DB 만들기

Neon / Supabase 등에서 프로젝트를 만들고
Connection string을 복사합니다. 예:

postgresql://USER:PASSWORD@HOST/DB?sslmode=require

(2) 스키마 provider 변경

prisma/schema.prisma:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Memo 모델은 그대로 둬도 됩니다.

(3) 로컬 `.env`도 잠시 Postgres로

DATABASE_URL="postgresql://..."

그다음:

npx prisma migrate dev --name postgres-init

(4) Vercel 환경 변수

Vercel Project → Settings → Environment Variables

Name	Value
`DATABASE_URL`	Postgres 연결 문자열

Production / Preview에 체크하고 저장한 뒤 Redeploy.

(5) 코드는?

lib/memos.ts, Server Action, 페이지는 그대로인 경우가 많습니다.
바뀌는 건 주로:

provider
DATABASE_URL
migrate 대상 DB

이게 데이터 레이어를 나눠 둔 보답입니다.

7) Vercel 빌드에서 Prisma 자주 하는 설정

package.json에 빌드 직전 generate를 넣는 경우가 많습니다.

{
  "scripts": {
    "dev": "next dev",
    "build": "prisma generate && next build",
    "start": "next start",
    "postinstall": "prisma generate"
  }
}

postinstall: npm install 직후 클라이언트 생성
build 앞 prisma generate: Vercel 빌드 환경에서 타입/엔진 준비

마이그레이션을 배포 파이프라인에 넣을지는 팀마다 다릅니다.
혼자 연습이면:

로컬(또는 CI)에서 prisma migrate deploy
앱은 Vercel에 배포

순서로 시작하는 편이 단순합니다.

8) 배포 후 체크리스트

https://프로젝트.vercel.app 접속
/memos 목록
새 메모 작성 → 새로고침 후에도 남는지
수정 / 삭제

안 되면 Vercel Deployments → 해당 배포 → Logs / Functions 에서
DATABASE_URL, Prisma 에러를 확인합니다.

자주 하는 실수

1. .env를 GitHub에 올림
→ 비밀 유출. 올렸다면 키 교체 + git 기록 정리 필요

2. Vercel에 DATABASE_URL을 안 넣음
→ 로컬에만 있어서 배포 환경에서 DB 연결 실패

3. SQLite 파일 그대로 배포 기대
→ 서버리스와 구조적으로 안 맞음

4. Root Directory 잘못 지정
→ toyproject 루트를 배포해 memo-app을 못 찾음
→ Vercel에서 Root를 memo-app으로

5. npm run build를 로컬에서 안 해보고 바로 배포
→ 같은 에러를 Vercel 로그에서만 헤맴

이 편에서 가져갈 것

Vercel 배포 = Git 연결 + 빌드 + (필요 시) 환경 변수
화면 배포와 DB는 별개다
SQLite 파일은 로컬용, Vercel에는 외부 DB가 맞다
Prisma면 provider + DATABASE_URL만 바꿔도 앱 코드는 유지하기 쉽다
배포 전에 npm run build로 먼저 검증한다

실습을 어디까지 하면 되나 (추천)

시간이 없다면:

GitHub + Vercel로 앱 화면만 배포해 보기
/memos가 DB 때문에 에러 나는 걸 로그로 확인
“그래서 외부 DB가 필요하다”를 글로 정리

시간이 있다면:

Neon(또는 Supabase) Postgres 연결
migrate + Vercel DATABASE_URL
CRUD가 배포 URL에서 동작하는지 확인

블로그에는 둘 다 솔직히 적어도 좋습니다.
완벽 배포보다 왜 SQLite가 안 되는지를 쓰는 편이 독자에게 더 가치가 있습니다.

시리즈를 마치며 (실전 1~3)

편	한 줄
1	수정·삭제로 CRUD 완성
2	Prisma + SQLite로 영속화
3	Vercel 배포 + 외부 DB 필요성

입문 8편 + 실전 3편이면:

React 경험 → Next App Router + TS → CRUD → DB → 배포 이슈까지

한 축이 이어집니다.

다음에 이어서 쓰기 좋은 주제:

Neon Postgres 연결 실습 (스크린샷 중심)
폼 검증 (zod + useActionState)
로그인 (Clerk / Auth.js)

시리즈 목차 (실전)

메모 수정과 삭제
Prisma + SQLite로 DB 붙이기
Vercel에 배포하기 ← 지금

# [Next.js + TS 실전] 2. Prisma + SQLite로 DB 붙이기

JaeSung Kim — Thu, 30 Jul 2026 10:15:15 +0900

[Next.js + TS 실전] 2. Prisma + SQLite로 DB 붙이기

실전 1편까지 CRUD는 완성됐습니다.
문제는 서버를 재시작하면 메모가 사라진다는 것입니다.
이번 편은 Prisma + SQLite로 진짜 저장을 붙입니다.

이 편에서 할 일

Prisma + SQLite 설치·초기화
Memo 테이블(스키마) 정의
lib/prisma.ts 클라이언트 만들기
lib/memos.ts를 배열 → DB 쿼리로 교체
시드(초기 데이터) 넣고 재시작해도 남는지 확인

페이지·Server Action 코드는 거의 안 건드립니다.
바뀌는 건 주로 lib/memos.ts입니다. 이게 이번 편의 핵심입니다.

왜 Prisma + SQLite인가

선택	이유
SQLite	파일 하나로 동작. 로컬 학습에 제일 단순
Prisma	스키마 → 타입 생성. TypeScript와 궁합이 좋음

나중에 PostgreSQL로 바꿀 때도, 스키마의 provider와 DATABASE_URL만 바꾸면 비슷한 코드로 갈 수 있습니다.
지금은 로컬에서 영속화가 목표입니다.

전체 그림

페이지 / Server Action
        ↓
   lib/memos.ts   ← 함수 이름은 그대로
        ↓
   lib/prisma.ts
        ↓
   SQLite 파일 (prisma/dev.db)

getMemos, addMemo 같은 함수 시그니처를 유지하면
actions.ts와 페이지는 그대로 두어도 됩니다.

1) 패키지 설치

memo-app 폴더에서:

npm install @prisma/client
npm install -D prisma

초기화 (SQLite):

npx prisma init --datasource-provider sqlite

생성되는 것:

prisma/schema.prisma
.env

.env 예시:

DATABASE_URL="file:./dev.db"

file:./dev.db는 prisma/ 폴더 기준 상대 경로입니다.
실제 DB 파일은 prisma/dev.db에 생깁니다.

.env는 Git에 올리지 마세요.
create-next-app이 .gitignore에 .env*를 넣어 둔 경우가 많습니다.

2) 스키마 정의

prisma/schema.prisma를 아래처럼 맞춥니다.

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model Memo {
  id        String   @id @default(cuid())
  title     String
  content   String
  createdAt DateTime @default(now())
}

포인트:

필드	의미
`@id`	기본 키
`@default(cuid())`	고유 id 자동 생성 (`Date.now()` 대체)
`DateTime`	DB에는 날짜 타입, 화면에는 문자열로 변환해서 씀
`@default(now())`	생성 시각 자동

테이블을 만들고 Prisma Client를 생성합니다.

npx prisma migrate dev --name init

성공하면:

prisma/dev.db 생성
prisma/migrations/ 생성
@prisma/client 타입이 갱신됨

3) Prisma Client 싱글톤

Next.js 개발 모드에서는 Hot Reload 때문에
PrismaClient를 매번 new 하면 연결이 쌓일 수 있습니다.

경로: lib/prisma.ts

import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma = globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

개발에서만 globalThis에 붙여 두는 패턴입니다.
공식 문서에서도 비슷한 예시를 씁니다.

4) `lib/memos.ts`를 DB로 교체

배열과 delay를 지우고, Prisma로 바꿉니다.

import type { Memo } from "@/types/memo";
import { prisma } from "@/lib/prisma";

function toMemo(row: {
  id: string;
  title: string;
  content: string;
  createdAt: Date;
}): Memo {
  return {
    id: row.id,
    title: row.title,
    content: row.content,
    createdAt: row.createdAt.toISOString().slice(0, 10),
  };
}

export async function getMemos(): Promise<Memo[]> {
  const rows = await prisma.memo.findMany({
    orderBy: { createdAt: "desc" },
  });

  return rows.map(toMemo);
}

export async function getMemoById(id: string): Promise<Memo | undefined> {
  const row = await prisma.memo.findUnique({
    where: { id },
  });

  return row ? toMemo(row) : undefined;
}

export async function addMemo(input: {
  title: string;
  content: string;
}): Promise<Memo> {
  const row = await prisma.memo.create({
    data: {
      title: input.title,
      content: input.content,
    },
  });

  return toMemo(row);
}

export async function updateMemo(
  id: string,
  input: { title: string; content: string }
): Promise<Memo | undefined> {
  try {
    const row = await prisma.memo.update({
      where: { id },
      data: {
        title: input.title,
        content: input.content,
      },
    });

    return toMemo(row);
  } catch {
    return undefined;
  }
}

export async function deleteMemo(id: string): Promise<boolean> {
  try {
    await prisma.memo.delete({
      where: { id },
    });
    return true;
  } catch {
    return false;
  }
}

포인트:

함수 이름·반환 타입은 그대로 → Action/페이지 수정 최소
toMemo로 DB Date → 화면용 string 변환
없는 id update/delete는 Prisma가 에러 → try/catch로 undefined / false
가짜 delay는 제거 (로딩 UI는 DB 속도에 맡김)

types/memo.ts의 Memo 타입은 그대로 둡니다.
DB 모델과 화면 모델을 toMemo로 연결하는 방식입니다.

5) 초기 데이터(시드) 넣기 (선택)

DB가 비어 있으면 목록이 텅 빕니다.
연습용 데이터를 넣고 싶다면:

prisma/seed.ts:

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

async function main() {
  await prisma.memo.createMany({
    data: [
      {
        title: "Next.js 시작",
        content: "App Router로 프로젝트 만들었다.",
      },
      {
        title: "TypeScript props",
        content: "MemoCard에 타입을 붙였다.",
      },
    ],
  });
}

main()
  .then(() => prisma.$disconnect())
  .catch(async (e) => {
    console.error(e);
    await prisma.$disconnect();
    process.exit(1);
  });

package.json 맨 바깥에 prisma 키를 추가합니다.
(주의: { "prisma": ... }를 파일에 따로 하나 더 붙이면 JSON이 깨집니다.)

예:

{
  "name": "memo-app",
  "scripts": { "...": "..." },
  "dependencies": { "...": "..." },
  "devDependencies": { "...": "..." },
  "prisma": {
    "seed": "npx tsx prisma/seed.ts"
  }
}

tsx가 없으면:

npm install -D tsx

시드 전에 반드시 마이그레이션을 먼저 하세요. (Memo 테이블이 있어야 함)

npx prisma migrate dev --name init
npx prisma db seed

또는 Prisma Studio로 직접 넣어도 됩니다.

npx prisma studio

브라우저에서 테이블을 GUI로 볼 수 있습니다.

6) 동작 확인

npm run dev
/memos/new에서 메모 추가
터미널에서 서버 중지 후 다시 npm run dev
/memos에 방금 메모가 남아 있으면 성공

이전(메모리 배열)이라면 여기서 사라졌을 겁니다.

Action / 페이지는?

대부분 수정할 필요 없습니다.

createMemo, updateMemoAction, deleteMemoAction은
이미 addMemo / updateMemo / deleteMemo만 호출합니다.

lib/memos.ts 구현만 바뀌었을 뿐입니다.

이게 좋은 설계입니다.

UI · Action · 데이터 레이어를 나누면,
저장소만 바꿔도 화면 코드는 버틸 수 있다.

`.gitignore` 확인

아래가 무시되는지 확인하세요.

.env
.env*.local
prisma/dev.db
prisma/dev.db-journal

DB 파일과 환경 변수는 저장소에 올리지 않는 편이 안전합니다.
팀원/다른 PC에서는 migrate로 스키마를 다시 만듭니다.

npx prisma migrate dev

자주 하는 실수

1. migrate를 안 돌림
→ prisma.memo가 없거나 테이블이 없어 에러

2. lib/prisma.ts 없이 매 파일에서 new PrismaClient()
→ 개발 중 연결 폭주 가능

3. createdAt을 Date 그대로 JSX에 뿌림
→ toMemo로 문자열 변환 권장 (기존 UI와 맞춤)

4. .env의 DATABASE_URL 오타
→ DB 파일을 못 찾아 실패

5. 예전에 쓰던 id 1, 2를 하드코딩한 링크
→ 이제 id는 cuid()라 긴 문자열입니다. UI의 Link는 memo.id를 쓰면 문제 없습니다.

6. loading이 너무 짧아져서 “로딩이 안 보여요”
→ 정상입니다. 원하면 loading.tsx는 그대로 두고, 느린 네트워크에서만 눈에 띕니다.

이 편에서 가져갈 것

메모리 배열은 학습용, 실서비스는 DB가 필요하다
Prisma = 스키마 + 타입 안전한 쿼리
SQLite = 로컬에 파일 하나로 시작하기 좋다
데이터 레이어만 바꾸면 CRUD UI/Action은 재사용된다
toMemo로 DB 모델과 화면 타입을 연결한다

다음 편 예고

[Next.js + TS 실전] 3. Vercel에 배포하기

빌드·환경 변수
SQLite의 한계와 배포 시 선택지
메모 앱을 URL로 열어보기

로컬 DB까지 붙였으니, 다음은 다른 사람이 접속할 수 있게 만드는 단계입니다.

미리 한 줄: Vercel 같은 서버리스 환경에서는 SQLite 파일 DB가 잘 안 맞을 수 있습니다.
다음 편에서 “왜”와 대안(예: Postgres)을 같이 정리합니다.

시리즈 목차 (실전)

메모 수정과 삭제
Prisma + SQLite로 DB 붙이기 ← 지금
Vercel 배포 (예정)

입문·실전 1편과의 연결

이전	이번
`const memos = [...]`	`prisma.memo.findMany`
`Date.now()` id	`cuid()`
서버 재시작 → 데이터 소멸	서버 재시작 → 데이터 유지
`delay()`로 로딩 연습	실제 I/O

함수 이름은 같고, 속이 DB로 바뀐 것이 이번 편의 전부입니다.

# [Next.js + TS 실전] 1. 메모 수정과 삭제

JaeSung Kim — Thu, 30 Jul 2026 09:38:15 +0900

[Next.js + TS 실전] 1. 메모 수정과 삭제

입문 시리즈(1~8편)에서 추가까지 했다면, 이번 편은 수정·삭제로 CRUD를 마칩니다.
목표: updateMemo / deleteMemo · Server Action 확장 · 수정 페이지.

이 편에서 할 일

lib/memos.ts에 수정·삭제 함수 추가
actions.ts에 Server Action 2개 추가
/memos/[id]/edit 수정 페이지 만들기
상세 페이지에 수정 링크 · 삭제 버튼 붙이기

7편에서 만든 추가(create) 흐름을 그대로 확장합니다.
새 개념보다 같은 패턴 반복이 목표입니다.

CRUD 중 지금 어디까지?

	상태	이번 편
Create	✅ 7편	—
Read	✅ 4~6편	—
Update	❌	✅
Delete	❌	✅

Create를 이미 Server Action으로 했으니, Update/Delete도 폼 + Server Action으로 가면 됩니다.

1) 데이터 함수: 수정·삭제

lib/memos.ts 하단에 추가합니다.

export async function updateMemo(
  id: string,
  input: { title: string; content: string }
): Promise<Memo | undefined> {
  await delay(300);

  const index = memos.findIndex((memo) => memo.id === id);
  if (index === -1) {
    return undefined;
  }

  memos[index] = {
    ...memos[index],
    title: input.title,
    content: input.content,
  };

  return memos[index];
}

export async function deleteMemo(id: string): Promise<boolean> {
  await delay(300);

  const index = memos.findIndex((memo) => memo.id === id);
  if (index === -1) {
    return false;
  }

  memos.splice(index, 1);
  return true;
}

포인트:

updateMemo → 못 찾으면 undefined
deleteMemo → 못 찾으면 false
createdAt, id는 그대로 두고 제목·내용만 바꿉니다

2) Server Action 확장

app/memos/actions.ts에 두 함수를 추가합니다.

"use server";

import { redirect } from "next/navigation";
import { revalidatePath } from "next/cache";
import { addMemo, deleteMemo, updateMemo } from "@/lib/memos";

export async function createMemo(formData: FormData) {
  const title = String(formData.get("title") ?? "").trim();
  const content = String(formData.get("content") ?? "").trim();

  if (!title || !content) {
    throw new Error("제목과 내용을 모두 입력하세요");
  }

  await addMemo({ title, content });

  revalidatePath("/memos");
  redirect("/memos");
}

export async function updateMemoAction(formData: FormData) {
  const id = String(formData.get("id") ?? "").trim();
  const title = String(formData.get("title") ?? "").trim();
  const content = String(formData.get("content") ?? "").trim();

  if (!id || !title || !content) {
    throw new Error("제목과 내용을 모두 입력하세요");
  }

  const updated = await updateMemo(id, { title, content });

  if (!updated) {
    throw new Error("메모를 찾을 수 없습니다");
  }

  revalidatePath("/memos");
  revalidatePath(`/memos/${id}`);
  redirect(`/memos/${id}`);
}

export async function deleteMemoAction(formData: FormData) {
  const id = String(formData.get("id") ?? "").trim();

  if (!id) {
    throw new Error("삭제할 메모 id가 없습니다");
  }

  const deleted = await deleteMemo(id);

  if (!deleted) {
    throw new Error("메모를 찾을 수 없습니다");
  }

  revalidatePath("/memos");
  redirect("/memos");
}

7편과 비교:

	create	update	delete
입력	title, content	id, title, content	id
성공 후	`/memos`	`/memos/[id]`	`/memos`
revalidate	`/memos`	`/memos`, `/memos/[id]`	`/memos`

수정은 목록 + 상세 둘 다 갱신하는 게 안전합니다.

3) 수정 페이지: `/memos/[id]/edit`

폴더와 파일을 만듭니다.

app/memos/[id]/edit/page.tsx

import { notFound } from "next/navigation";
import { getMemoById } from "@/lib/memos";
import { updateMemoAction } from "@/app/memos/actions";

type EditMemoPageProps = {
  params: Promise<{ id: string }>;
};

export default async function EditMemoPage({ params }: EditMemoPageProps) {
  const { id } = await params;
  const memo = await getMemoById(id);

  if (!memo) {
    notFound();
  }

  return (
    <main>
      <h1>메모 수정</h1>

      <form action={updateMemoAction}>
        <input type="hidden" name="id" value={memo.id} />

        <p>
          <label>
            제목
            <br />
            <input
              type="text"
              name="title"
              defaultValue={memo.title}
              required
            />
          </label>
        </p>

        <p>
          <label>
            내용
            <br />
            <textarea
              name="content"
              rows={5}
              defaultValue={memo.content}
              required
            />
          </label>
        </p>

        <button type="submit">저장</button>
      </form>
    </main>
  );
}

포인트:

새 메모와 거의 같은 폼, defaultValue로 기존 값 채움
hidden input으로 id를 Action에 전달
'use client' 없음 → 서버 컴포넌트 + Server Action 조합

/memos/1/edit 에서 제목을 바꾸고 저장하면 상세 페이지 내용이 바뀌어야 합니다.

4) 상세 페이지에 수정·삭제 UI

app/memos/[id]/page.tsx를 아래처럼 확장합니다.

import Link from "next/link";
import { notFound } from "next/navigation";
import { deleteMemoAction } from "@/app/memos/actions";
import { getMemoById } from "@/lib/memos";

type MemoDetailPageProps = {
  params: Promise<{ id: string }>;
};

export default async function MemoDetailPage({ params }: MemoDetailPageProps) {
  const { id } = await params;
  const memo = await getMemoById(id);

  if (!memo) {
    notFound();
  }

  return (
    <main>
      <h1>{memo.title}</h1>
      <p>{memo.content}</p>
      <time dateTime={memo.createdAt}>{memo.createdAt}</time>

      <p>
        <Link href={`/memos/${memo.id}/edit`}>수정</Link>
      </p>

      <form action={deleteMemoAction}>
        <input type="hidden" name="id" value={memo.id} />
        <button type="submit">삭제</button>
      </form>
    </main>
  );
}

수정 → Link로 edit 페이지 이동
삭제 → 별도 <form> + deleteMemoAction

삭제는 onClick + fetch가 아니라 폼 제출로 처리합니다.
7편 추가와 같은 Server Action 패턴입니다.

동작 흐름

수정

/memos/1/edit 에서 저장
    ↓
updateMemoAction
    ↓
updateMemo (배열에서 해당 항목 교체)
    ↓
revalidatePath("/memos", "/memos/1")
    ↓
redirect("/memos/1")

삭제

/memos/1 에서 [삭제] 클릭
    ↓
deleteMemoAction
    ↓
deleteMemo (배열에서 splice)
    ↓
revalidatePath("/memos")
    ↓
redirect("/memos")

왜 삭제도 form + action인가

클릭 핸들러로도 할 수 있습니다.

"use client";
// onClick → fetch('/api/...') ...

하지만 지금 앱은 Server Action 중심입니다.

API 라우트를 따로 안 만들어도 됨
create/update/delete가 같은 파일·같은 패턴
서버에서만 데이터 변경

실무에서는 “삭제 전 확인(confirm)”을 넣을 때 클라이언트 버튼이 필요해질 수 있습니다.
입문+실전 1편에서는 가장 단순한 form 삭제로 충분합니다.

자주 하는 실수

1. 수정 폼에 id hidden을 빼먹음
→ Action에서 어떤 메모를 고칠지 모릅니다

2. value 대신 controlled input을 서버에서 쓰려 함
→ 서버 폼은 defaultValue가 맞습니다 (value + onChange는 Client)

3. update 후 revalidatePath('/memos/1')만 하고 목록은 안 함
→ 목록 카드 제목이 옛날로 남을 수 있습니다

4. action={deleteMemoAction()} 처럼 호출
→ action={deleteMemoAction} (함수 참조)

5. 삭제 후 상세 URL에 그대로 머무름
→ redirect('/memos')로 보내는 게 자연스럽습니다

이 편에서 가져갈 것

CRUD는 Create 패턴을 Update/Delete로 확장하면 된다
수정·삭제도 Server Action + FormData + hidden id
수정 페이지는 /memos/[id]/edit + defaultValue
revalidatePath는 바뀌는 경로를 모두 호출
지금은 메모리 배열, 나중에 DB로 함수만 교체

다음 편 예고

[Next.js + TS 실전] 2. Prisma + SQLite로 DB 붙이기

서버 재시작해도 메모가 남게
lib/memos.ts의 배열을 DB 쿼리로 교체
CRUD를 “진짜 저장”으로 바꾸기

시리즈 목차 (실전)

메모 수정과 삭제 ← 지금
Prisma + SQLite로 DB 붙이기 (예정)
Vercel 배포 (예정)

입문 시리즈와의 연결

입문	실전 1편
`addMemo`	`updateMemo`, `deleteMemo`
`createMemo`	`updateMemoAction`, `deleteMemoAction`
`/memos/new`	`/memos/[id]/edit`
추가 후 목록	수정 후 상세, 삭제 후 목록

입문 7편을 이해했다면, 이번 편은 복붙·수정 수준으로 따라올 수 있습니다.

# 면접 CS 정리 Day 2 (풀스택 / Java·Spring·React)

JaeSung Kim — Thu, 30 Jul 2026 09:25:50 +0900

면접 CS 정리 Day 2 (풀스택 / Java·Spring·React)

Q1. Spring Bean 스코프

문제
Spring Bean 기본 스코프는 뭐고, singleton이랑 prototype 차이는?

답

기본 스코프는 singleton
singleton: 컨테이너당 Bean 1개 공유
prototype: 가져올 때마다 새 객체 생성

singleton Service에 요청별 상태(currentUserId 필드 등)를 넣으면
여러 요청이 같은 인스턴스를 공유해서 위험하다.

Q2. Checked vs Unchecked Exception

문제
Checked Exception이랑 Unchecked Exception 차이?
@Transactional 기본 롤백이랑 어떻게 연결되는지?

답

Checked: IOException, SQLException 등 — 컴파일러가 처리 강제
Unchecked: RuntimeException 계열 — IllegalArgumentException, NPE, 보통의 BusinessException

@Transactional 기본:

unchecked → 롤백
checked → 롤백 안 함

checked도 롤백하려면
@Transactional(rollbackFor = Exception.class)
(@Rollback 아님)

Q3. MyBatis `#{}` vs `${}`

문제
MyBatis에서 #{}이랑 ${} 차이? 왜 기본은 #{}를 쓰는지?

답

#{}: PreparedStatement 파라미터 바인딩 → SQL Injection 방어에 유리
${}: 문자열 그대로 치환 → 위험

기본은 #{}.
${}는 테이블명·컬럼명·ORDER BY처럼 바인딩이 안 될 때만,
사용자 입력을 직접 넣지 말고 화이트리스트로 제한한다.

Q4. INNER JOIN vs LEFT JOIN

문제
INNER JOIN이랑 LEFT JOIN 차이? 매칭 안 되는 행 기준으로.

답

INNER JOIN: 양쪽 테이블에서 매칭되는 행만 (교집합)
LEFT JOIN: 왼쪽 테이블 전부 + 오른쪽이 없으면 NULL

Q5. accessToken / refreshToken

문제
JWT 로그인에서 accessToken이랑 refreshToken을 왜 나누는지?
access는 짧게, refresh는 길게 두는 이유는?

답
JWT는 탈취되면 만료 전까지 쓰일 수 있다.
그래서 API에 쓰는 accessToken은 짧게 두어 피해 구간을 줄이고,
만료 시 refreshToken으로 access를 재발급한다.

Q6. useEffect 의존성 배열

문제
React useEffect 의존성 배열이 [] / 없음 / [id]일 때 각각 언제 실행되나?

답

[] → 마운트 시 1번
없음 → 매 렌더마다
[id] → 마운트 + id 변경 시

Q7. DB 중복 신청 방지

문제
같은 휴가/출퇴근이 동시에 두 번 신청되는 걸 막으려면
앱 클릭 방지 말고 DB에서 쓸 수 있는 방법은?

답
(user_id, 날짜) 같은 컬럼 조합에 UNIQUE 제약을 건다.
동시 요청이 와도 하나는 중복 키 에러로 막힌다.
(프론트 연속클릭 방지만으론 부족 — DB가 최종 방어선)

오늘 한 줄 암기

Bean 기본 스코프 = singleton / prototype = 매번 새로
@Transactional 기본 롤백 = unchecked만
MyBatis #{} 바인딩 / ${} 치환
access 짧게 + refresh로 재발급
중복 방지 = UNIQUE 제약

# [Next.js + TS] 8. 정리 + 다음 학습 로드맵

JaeSung Kim — Wed, 29 Jul 2026 16:04:03 +0900

[Next.js + TS] 8. 정리 + 다음 학습 로드맵

1~7편에서 작은 메모 앱을 만들며 Next.js + TypeScript의 핵심 흐름을 따라 왔습니다.
마지막 편은 복습, 지금 앱의 한계, 다음에 공부할 순서를 정리합니다.

시리즈를 마치면서

처음에는 React만으로도 화면은 만들 수 있다는 이야기에서 시작했습니다.
끝날 즈음에는 이런 흐름을 직접 만들었을 겁니다.

/              → 소개
/memos         → 목록 (async fetch + loading/error)
/memos/new     → 작성 (Server Action)
/memos/[id]    → 상세

React 경험이 있는 사람이 Next.js App Router + TypeScript로 넘어올 때 필요한 것만 골라 다뤘습니다.
고급 패턴 전부를 다룬 시리즈는 아닙니다.
대신 “실제 앱을 한 바퀴 도는 감각”을 목표로 했습니다.

1~7편 한눈에 복습

편	핵심 한 줄
1	Next = React 위의 앱 프레임워크, TS = 타입 계약, App Router = 폴더가 URL
2	`create-next-app`, `app/page.tsx`가 곧 홈
3	`Memo` 타입 + `MemoCard` props
4	`/memos`, `/memos/[id]`, `layout`에 공통 내비
5	기본은 Server, hooks/이벤트만 Client
6	`async` 페이지, `loading.tsx`, `error.tsx`
7	Server Action + `FormData` + `revalidatePath`

각 편의 연결고리는 이겁니다.

타입(Memo)
  ↓
컴포넌트(MemoCard)
  ↓
라우팅(/memos, /memos/[id])
  ↓
서버/클라이언트 분리(LikeButton)
  ↓
데이터 가져오기(getMemos)
  ↓
데이터 쓰기(createMemo)

한 번에 외우려 하지 말고, URL 하나가 어떤 파일·어떤 데이터·어떤 컴포넌트로 이어지는지만 다시 따라가 보세요.

지금 만든 앱 구조

memo-app/
  app/
    layout.tsx          → 공통 내비
    page.tsx            → /
    memos/
      page.tsx          → 목록
      loading.tsx
      error.tsx
      actions.ts        → Server Action
      new/page.tsx      → 작성
      [id]/page.tsx     → 상세
  components/
    MemoCard.tsx
    LikeButton.tsx
  lib/
    memos.ts            → 데이터 함수
  types/
    memo.ts

이 구조가 App Router 앱의 작은 정석에 가깝습니다.

app/ = 라우트 + 페이지
components/ = UI 조각
lib/ = 데이터/비즈니스 로직
types/ = 타입 정의

스스로 점검하는 체크리스트

아래를 설명할 수 있으면 1~7편은 제대로 따라온 겁니다.

Next.js / App Router

app/page.tsx와 URL /의 관계를 설명할 수 있다
[id] 폴더가 동적 라우트인 이유를 안다
layout.tsx와 page.tsx 차이를 안다
Link를 쓰는 이유를 안다

TypeScript

Memo 타입이 왜 필요한지 안다
컴포넌트 props에 타입을 붙일 수 있다
Promise<Memo[]> 같은 async 반환 타입의 의미를 안다

Server / Client

Server Component가 기본값인 이유를 안다
'use client'가 필요한 경우를 2가지 이상 말할 수 있다
페이지 전체가 아니라 버튼만 Client로 분리할 수 있다

데이터

useEffect fetch 대신 서버에서 await하는 이유를 안다
loading.tsx가 언제 보이는지 안다
error.tsx가 왜 "use client"인지 대략 안다

Server Action

"use server"의 역할을 안다
FormData와 input name의 관계를 안다
revalidatePath와 redirect가 각각 뭘 하는지 안다

하나라도 막히면 해당 편만 다시 보면 됩니다.
처음부터 다시 읽을 필요는 없습니다.

지금 앱에 아직 없는 것 (정상)

이 시리즈 앱은 학습용입니다.
실서비스와 비교하면 아래가 비어 있습니다.

없는 것	왜 아직 안 했나	다음에
DB	메모리 배열로 흐름만 연습	Prisma, Drizzle, Supabase 등
인증	범위 밖	NextAuth, Clerk, Supabase Auth
수정/삭제	추가만 다룸	Server Action 확장
폼 에러 UI	`throw`만 소개	`useActionState`, zod
스타일링	최소	Tailwind, CSS Module
배포	로컬만	Vercel 등
테스트	범위 밖	Vitest, Playwright

“이게 없어서 실패”가 아니라, 의도적으로 빼 둔 것입니다.
한 번에 다 넣으면 Next의 핵심이 묻힙니다.

React만 쓸 때와 비교 (최종 정리)

주제	React만	Next App Router
라우팅	react-router 설정	폴더 = URL
첫 데이터	클라이언트 fetch 흔함	서버 `await`
인터랙션	전부 클라이언트	필요한 조각만 Client
폼 전송	API 라우트 + fetch	Server Action
공통 UI	Layout 컴포넌트 직접 구성	`layout.tsx`

React 지식은 버리는 게 아니라 그대로 씁니다.
바뀐 건 “어디서 실행되고, 어떤 파일이 페이지인지” 규칙입니다.

다음 학습 로드맵 (추천 순서)

1단계: 지금 앱을 조금 더 완성하기

가장 가까운 다음 단계입니다.

메모 수정/삭제 Server Action 추가
폼 검증 — 빈 값 말고 필드별 에러 메시지
Tailwind로 목록·카드 UI 정리 (이미 템플릿에 있으면 활용)

→ “읽기 + 쓰기”가 있는 CRUD 입문

2단계: 데이터 영속화

SQLite + Prisma 또는 Supabase로 DB 연결
lib/memos.ts의 메모리 배열을 DB 쿼리로 교체
서버 재시작해도 데이터가 남게 만들기

→ “장난감 앱”에서 “저장되는 앱”으로

3단계: 인증과 권한

로그인 붙이기
“내 메모만 보기” 같은 간단한 권한

→ 혼자 쓰는 앱 → 사용자별 앱

4단계: 배포와 운영

Vercel에 배포
환경 변수 (.env) 다루기
빌드/프리뷰/프로덕션 차이 이해

→ 로컬에서 끝나는 프로젝트 → 다른 사람도 접속 가능

5단계: 깊게 파고들 주제 (필요할 때)

Middleware, Route Handlers (app/api/...)
캐싱 전략 (revalidate, fetch 옵션)
Parallel Routes, Intercepting Routes
React Query와 Server Component 조합
E2E 테스트

한꺼번에 X. 2단계 DB 붙이기까지 가면 실무 감각이 확 올라갑니다.

자주 묻는 “다음에 뭐 보면 돼요?”

Q. 공식 문서부터 볼까요?
→ 네. Next.js Docs의 App Router 섹션을 이 시리즈와 병행하면 좋습니다.
이미 만든 앱 파일 이름과 문서 용어가 1:1로 맞을 겁니다.

Q. TypeScript를 더 깊게?
→ 지금은 type, props, Promise<T>면 충분합니다.
필요해질 때 Pick, Omit, zod 스키마를 보면 됩니다.

Q. Pages Router도 배워야 해요?
→ 새 프로젝트면 App Router만으로 충분합니다.
레거시 코드를 읽을 일이 생기면 그때 비교하면 됩니다.

Q. 포트폴리오로 써도 돼요?
→ DB + 배포 + 수정/삭제까지 붙이면 “Next 입문” 이상으로 보입니다.
지금 상태는 “학습 완주” 증거로는 좋고, 포트폴리오는 1~2단계 더 가면 좋습니다.

이 시리즈에서 가져갈 것 (마지막)

Next.js는 React를 대체하지 않는다. 앱 규칙을 더한다.
TypeScript는 데이터·props·함수의 계약이다.
App Router는 폴더·page·layout으로 URL과 화면을 만든다.
Server Component가 기본이고, Client는 꼭 필요할 때만 쓴다.
데이터는 서버에서 await하고, 폼은 Server Action으로 처리할 수 있다.
작은 앱 하나를 끝까지 밀어보는 게, 예제 조각 10개보다 낫다.

시리즈 전체 목차

왜 Next.js + TypeScript인가
프로젝트 만들고 폴더 구조 이해하기
TypeScript로 컴포넌트 타입 잡기
라우팅과 레이아웃
Server Component vs Client Component
데이터 가져오기
폼과 서버 액션 입문
정리 + 다음 학습 로드맵 ← 지금

마치며

8편까지 오면 “Next.js가 뭔지 들어 본” 수준이 아니라,
직접 만든 앱 하나가 있습니다.

다음은 새 글을 읽기보다,
메모 수정·DB·배포 중 하나를 골라 손으로 붙여 보는 게 가장 빠릅니다.

시리즈가 도움이 됐다면 댓글로

어떤 편이 제일 헷갈렸는지
다음에 다뤄 줬으면 하는 주제

남겨 주세요.
같은 메모 앱을 이어서 확장하는 후속 시리즈도 이어갈 수 있습니다.

# [Next.js + TS] 7. 폼과 서버 액션 입문

JaeSung Kim — Wed, 29 Jul 2026 15:30:06 +0900

[Next.js + TS] 7. 폼과 서버 액션 입문

6편까지는 메모를 읽기만 했습니다.
이번 편은 폼으로 메모를 추가합니다.
목표: Server Action · FormData · revalidatePath로 목록 갱신.

이 편에서 할 일

Server Action이 뭔지 짧게 이해하기
createMemo 액션 만들기
/memos/new 작성 폼 페이지 만들기
저장 후 /memos 목록이 갱신되는지 확인하기

DB는 아직 없습니다.
메모리 배열에 넣고, 새로고침 없이 목록이 바뀌는 흐름만 익힙니다.

왜 Server Action인가

예전에 흔했던 흐름:

클라이언트에서 fetch('/api/memos', { method: 'POST' ... })
API 라우트에서 저장
다시 목록 fetch

App Router에서는 더 단순한 길이 있습니다.

폼이 서버 함수를 직접 호출한다 → Server Action

별도의 API 라우트를 꼭 안 만들어도 됨
서버에서만 실행됨 (비밀키/DB 접근에 유리)
<form action={createMemo}> 로 연결 가능

전부 Action으로 대체하라는 뜻은 아닙니다.
폼 제출·간단한 mutation부터 배우기 좋습니다.

1) 데이터 레이어에 “추가” 붙이기

lib/memos.ts에 생성 함수를 추가합니다.

import type { Memo } from "@/types/memo";

const memos: Memo[] = [
  {
    id: "1",
    title: "Next.js 시작",
    content: "App Router로 프로젝트 만들었다.",
    createdAt: "2026-07-29",
  },
  {
    id: "2",
    title: "TypeScript props",
    content: "MemoCard에 타입을 붙였다.",
    createdAt: "2026-07-29",
  },
];

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export async function getMemos(): Promise<Memo[]> {
  await delay(800);
  return memos;
}

export async function getMemoById(id: string): Promise<Memo | undefined> {
  await delay(500);
  return memos.find((memo) => memo.id === id);
}

export async function addMemo(input: {
  title: string;
  content: string;
}): Promise<Memo> {
  await delay(300);

  const memo: Memo = {
    id: String(Date.now()),
    title: input.title,
    content: input.content,
    createdAt: new Date().toISOString().slice(0, 10),
  };

  memos.unshift(memo); // 맨 앞에 추가
  return memo;
}

id는 실습용으로 Date.now() 사용
서버를 재시작하면 배열은 초기값으로 돌아갑니다 (메모리라서 정상)

2) Server Action 파일

경로: app/memos/actions.ts

"use server";

import { redirect } from "next/navigation";
import { revalidatePath } from "next/cache";
import { addMemo } from "@/lib/memos";

export async function createMemo(formData: FormData) {
  const title = String(formData.get("title") ?? "").trim();
  const content = String(formData.get("content") ?? "").trim();

  if (!title || !content) {
    throw new Error("제목과 내용을 모두 입력하세요");
  }

  await addMemo({ title, content });

  revalidatePath("/memos");
  redirect("/memos");
}

읽어볼 것:

코드	의미
`"use server"`	이 파일의 함수는 서버에서 실행
`FormData`	`<form>`이 보낸 값 묶음
`formData.get("title")`	`name="title"` 입력값
`revalidatePath("/memos")`	목록 캐시/화면을 다시 준비
`redirect("/memos")`	저장 후 목록으로 이동

"use server"는 파일 맨 위에 둡니다.
(함수 단위로 쓸 수도 있지만, 입문에서는 파일 단위가 단순합니다.)

3) 작성 페이지: `/memos/new`

app/memos/new/page.tsx

import { createMemo } from "@/app/memos/actions";

export default function NewMemoPage() {
  return (
    <main>
      <h1>새 메모</h1>

      <form action={createMemo}>
        <p>
          <label>
            제목
            <br />
            <input type="text" name="title" required />
          </label>
        </p>

        <p>
          <label>
            내용
            <br />
            <textarea name="content" rows={5} required />
          </label>
        </p>

        <button type="submit">저장</button>
      </form>
    </main>
  );
}

포인트:

'use client' 없음 → 서버 컴포넌트 페이지
action={createMemo} 로 서버 함수 연결
input의 name 이 FormData 키와 같아야 함

http://localhost:3000/memos/new 에서 작성 → 저장하면 /memos로 이동하고 새 메모가 보여야 합니다.

4) 목록에서 “새 메모” 링크

app/memos/page.tsx에 링크를 하나 추가합니다.

import Link from "next/link";
import MemoCard from "@/components/MemoCard";
import { getMemos } from "@/lib/memos";

export default async function MemosPage() {
  const memos = await getMemos();

  return (
    <main>
      <h1>메모 목록</h1>
      <p>
        <Link href="/memos/new">새 메모 작성</Link>
      </p>

      <section>
        {memos.map((memo) => (
          <MemoCard key={memo.id} memo={memo} />
        ))}
      </section>
    </main>
  );
}

원하면 layout 내비에도 /memos/new를 넣어도 됩니다.

동작 흐름 (한눈에)

/memos/new 에서 제출
    ↓
createMemo (Server Action)
    ↓
addMemo (메모리 배열에 push)
    ↓
revalidatePath("/memos")
    ↓
redirect("/memos")
    ↓
목록이 새 데이터로 다시 렌더

클라이언트에서 useState로 목록을 직접 고치지 않아도 됩니다.
서버가 데이터를 바꾸고, 해당 경로를 다시 그리게 합니다.

최소 검증만 넣은 이유

지금은:

if (!title || !content) {
  throw new Error("...");
}

정도만 했습니다.

실서비스에서는:

필드별 에러 메시지 표시
useActionState 같은 패턴
zod 등 스키마 검증

으로 확장합니다.
입문 편에서는 폼 → 서버 → 목록 갱신 한 바퀴가 목표입니다.

자주 하는 실수

1. input에 name을 안 줌
→ formData.get("title")이 비어 있습니다

2. "use server"를 클라이언트 컴포넌트 한가운데에 무작정 붙임
→ Action은 서버 파일(또는 서버 함수)로 분리하세요

3. revalidatePath를 빼먹음
→ 저장은 됐는데 목록이 옛 화면일 수 있습니다

4. 서버 재시작 후 메모가 사라짐
→ 메모리 배열이라 정상입니다. DB 붙이면 유지됩니다

5. action={createMemo()} 처럼 호출해 버림
→ action={createMemo} (함수 참조)여야 합니다

이 편에서 가져갈 것

Server Action은 폼이 호출하는 서버 함수다
"use server" + FormData + name 속성이 기본 세트다
저장 후 revalidatePath로 목록을 갱신한다
redirect로 다음 화면으로 보낸다
지금은 메모리, 나중엔 DB로 addMemo만 바꾸면 된다

다음 편 예고

[Next.js + TS] 8. 정리 + 다음 학습 로드맵

1~7편 한눈에 복습
지금 앱에서 부족한 점 (DB, 인증, 배포)
다음에 공부하면 좋은 순서

시리즈 마무리다운 체크리스트 + 로드맵으로 끝냅니다.

시리즈 목차

왜 Next.js + TypeScript인가
프로젝트 만들고 폴더 구조 이해하기
TypeScript로 컴포넌트 타입 잡기
라우팅과 레이아웃
Server Component vs Client Component
데이터 가져오기
폼과 서버 액션 입문 ← 지금
정리 + 다음 학습 로드맵

# [Next.js + TS] 6. 데이터 가져오기

JaeSung Kim — Wed, 29 Jul 2026 15:15:21 +0900

[Next.js + TS] 6. 데이터 가져오기

5편까지는 lib/memos.ts의 배열을 동기적으로 읽었습니다.
이번 편은 서버 컴포넌트에서 데이터를 기다리는(async) 방식으로 바꿉니다.
목표: async 페이지 · 로딩 UI · 에러 UI.

이 편에서 할 일

React의 useEffect + fetch와 Next 서버 fetch의 차이 이해하기
getMemos / getMemoById를 async로 바꾸기
목록·상세 페이지를 async로 고치기
loading.tsx / error.tsx 맛보기

DB나 외부 API를 당장 붙이지 않아도 됩니다.
“가져오는 동안 기다린다” 흐름만 잡으면 됩니다.

왜 useEffect로 안 가져오나

Vite/CRA에서 흔했던 패턴:

"use client";

useEffect(() => {
  fetch("/api/memos")
    .then((res) => res.json())
    .then(setMemos);
}, []);

문제는 초기 흐름이 이렇게 됩니다.

빈 화면(또는 로딩) 먼저 그림
JS 실행
그제야 요청
다시 그림

App Router 서버 컴포넌트에서는:

export default async function MemosPage() {
  const memos = await getMemos();
  return ...
}

서버에서 데이터를 기다림
완성된 HTML을 보냄

목록처럼 첫 화면에 꼭 필요한 데이터는 서버에서 가져오는 쪽이 자연스럽습니다.
클릭 이후 추가 로드, 검색어 디바운스 같은 건 클라이언트 fetch가 맞는 경우도 많습니다.

1) 데이터 함수를 async로

lib/memos.ts를 아래처럼 바꿉니다.

import type { Memo } from "@/types/memo";

const memos: Memo[] = [
  {
    id: "1",
    title: "Next.js 시작",
    content: "App Router로 프로젝트 만들었다.",
    createdAt: "2026-07-29",
  },
  {
    id: "2",
    title: "TypeScript props",
    content: "MemoCard에 타입을 붙였다.",
    createdAt: "2026-07-29",
  },
];

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export async function getMemos(): Promise<Memo[]> {
  await delay(800); // 로딩 UI를 보기 위한 가짜 대기
  return memos;
}

export async function getMemoById(id: string): Promise<Memo | undefined> {
  await delay(500);
  return memos.find((memo) => memo.id === id);
}

포인트:

export const memos 직접 노출 대신 함수로만 가져오게 바꿈
Promise<Memo[]>로 반환 타입을 명시
delay는 실습용입니다. 실제 DB/API 자리라고 생각하면 됩니다

서버 컴포넌트에서는 자기 프로젝트의 /api를 다시 fetch하기보다,
이런 데이터 함수를 직접 await 하는 방식을 먼저 쓰는 게 좋습니다.

2) 목록 페이지를 async로

app/memos/page.tsx:

import MemoCard from "@/components/MemoCard";
import { getMemos } from "@/lib/memos";

export default async function MemosPage() {
  const memos = await getMemos();

  return (
    <main>
      <h1>메모 목록</h1>

      <section>
        {memos.map((memo) => (
          <MemoCard key={memo.id} memo={memo} />
        ))}
      </section>
    </main>
  );
}

바뀐 점:

async function
await getMemos()
더 이상 import { memos }가 아님

3) 상세도 동일하게

app/memos/[id]/page.tsx:

import { notFound } from "next/navigation";
import { getMemoById } from "@/lib/memos";

type MemoDetailPageProps = {
  params: Promise<{ id: string }>;
};

export default async function MemoDetailPage({ params }: MemoDetailPageProps) {
  const { id } = await params;
  const memo = await getMemoById(id);

  if (!memo) {
    notFound();
  }

  return (
    <main>
      <h1>{memo.title}</h1>
      <p>{memo.content}</p>
      <time dateTime={memo.createdAt}>{memo.createdAt}</time>
    </main>
  );
}

getMemoById 앞에 await만 추가하면 됩니다.
(이미 async 페이지였다면 그대로 두면 됩니다.)

4) 로딩 UI: `loading.tsx`

데이터 기다리는 동안 보여줄 파일을 만듭니다.

경로: app/memos/loading.tsx

export default function MemosLoading() {
  return (
    <main>
      <p>메모를 불러오는 중...</p>
    </main>
  );
}

/memos로 이동하면 잠깐 이 문구가 보였다가 목록이 뜹니다.
(delay(800) 덕분에 눈에 보입니다.)

loading.tsx는 같은 세그먼트(memos)의 page.tsx를 감싸는 즉시 로딩 UI입니다.
상세(memos/[id])에도 따로 두고 싶으면:

app/memos/[id]/loading.tsx

를 추가하면 됩니다.

5) 에러 UI: `error.tsx`

경로: app/memos/error.tsx

에러 경계는 클라이언트 컴포넌트여야 합니다.

"use client";

type MemosErrorProps = {
  error: Error;
  reset: () => void;
};

export default function MemosError({ error, reset }: MemosErrorProps) {
  return (
    <main>
      <h1>메모를 불러오지 못했습니다</h1>
      <p>{error.message}</p>
      <button type="button" onClick={() => reset()}>
        다시 시도
      </button>
    </main>
  );
}

일부러 에러를 내려면 getMemos 안에 잠깐 넣어 볼 수 있습니다.

export async function getMemos(): Promise<Memo[]> {
  await delay(800);
  throw new Error("샘플 에러입니다");
  // return memos;
}

확인 후 꼭 throw는 지우세요.

외부 API를 fetch할 때는

진짜 HTTP API라면 서버 컴포넌트에서 이렇게 씁니다.

export default async function MemosPage() {
  const res = await fetch("https://api.example.com/memos", {
    next: { revalidate: 60 }, // 60초 캐시 예시
  });

  if (!res.ok) {
    throw new Error("메모를 가져오지 못했습니다");
  }

  const memos: Memo[] = await res.json();
  // ...
}

지금 시리즈는 로컬 배열 + delay로 같은 async 흐름을 연습합니다.
나중에 API URL만 바꿔 끼우면 됩니다.

자주 하는 실수

1. 서버 페이지인데 useEffect로 다시 fetch
→ 초기 목록이면 async + await를 먼저

2. await 없이 Promise를 map에 넣음
→ const memos = await getMemos() 필수

3. loading.tsx에 'use client' + useState로 직접 로딩 관리
→ 세그먼트 loading.tsx만으로도 충분한 경우가 많음

4. error.tsx를 서버 컴포넌트로 작성
→ error.tsx는 "use client" 필요

이 편에서 가져갈 것

첫 화면 데이터는 서버 컴포넌트에서 await하는 편이 자연스럽다
데이터 함수는 async + Promise<타입>으로 계약한다
loading.tsx는 기다리는 동안의 UI
error.tsx는 실패한 동안의 UI (클라이언트)
지금은 가짜 delay, 나중엔 DB/API로 교체하면 된다

다음 편 예고

[Next.js + TS] 7. 폼과 서버 액션 입문

메모 추가 폼 만들기
Server Action으로 데이터 넣기
목록이 갱신되는 흐름 맛보기

읽기만 하던 앱에 쓰기를 붙입니다.

시리즈 목차

왜 Next.js + TypeScript인가
프로젝트 만들고 폴더 구조 이해하기
TypeScript로 컴포넌트 타입 잡기
라우팅과 레이아웃
Server Component vs Client Component
데이터 가져오기 ← 지금
폼과 서버 액션 입문
정리 + 다음 학습 로드맵

# [Next.js + TS] 5. Server Component vs Client Component

JaeSung Kim — Wed, 29 Jul 2026 15:08:02 +0900

[Next.js + TS] 5. Server Component vs Client Component

4편까지는 목록·상세·링크만 있었습니다. 전부 읽기에 가깝습니다.
이번 편은 App Router에서 제일 헷갈리는 부분,
서버 컴포넌트 / 클라이언트 컴포넌트 경계를 나눕니다.

이 편에서 할 일

기본값이 서버 컴포넌트인 이유 이해하기
'use client'가 필요한 순간 정리하기
좋아요 버튼을 작은 클라이언트 컴포넌트로 분리하기
MemoCard(서버)가 그 버튼을 조립하는 패턴 익히기

목표는 “전부 'use client'로 만들기”가 아닙니다.
꼭 필요한 곳만 클라이언트로 내리는 감각을 잡는 겁니다.

한 줄 정리

	Server Component	Client Component
기본?	App Router 기본값	파일 맨 위에 `'use client'`
실행 위치	서버	브라우저(+필요 시 서버에서 사전 렌더)
hooks (`useState` 등)	불가	가능
클릭/입력 이벤트	불가	가능
데이터 fetch	자연스러움	가능하지만 목적이 다름

React(Vite/CRA)에 익숙하면 전부 클라이언트처럼 느껴집니다.
Next App Router는 기본을 서버에 두고, 인터랙션만 브라우저로 보냅니다.

왜 기본이 서버인가

우리가 만든 MemosPage, MemoCard에는 아직:

useState 없음
onClick 없음
브라우저 API 없음

그래서 서버 컴포넌트로 충분합니다.

서버에서 HTML을 만들어 보내면:

첫 화면을 빨리 그릴 수 있고
불필요한 JS를 클라이언트로 덜 보내고
(나중에) DB/시크릿에 가까운 작업을 서버에 두기 쉽습니다

“React 컴포넌트 = 무조건 브라우저”가 아니라는 점이 핵심입니다.

언제 `'use client'`가 필요한가

아래가 필요하면 클라이언트 컴포넌트입니다.

useState, useEffect, useRef 같은 hooks
onClick, onChange 같은 이벤트
window, localStorage 같은 브라우저 API
일부 브라우저 전용 라이브러리

반대로, 데이터 보여주고 링크로 이동만 하면 서버로 남겨 두세요.

잘못된 습관:

"use client"; // 습관적으로 파일 맨 위에 붙임

export default function MemosPage() {
  // 사실 hooks도 이벤트도 없음
}

페이지 전체를 클라이언트로 올리면,
서버 컴포넌트의 이점을 스스로 버리는 셈입니다.

실습 아이디어: 좋아요 버튼

메모 카드에 “좋아요”를 눌러 숫자가 바뀌게 해 봅시다.
이건 useState가 필요하므로 클라이언트가 맞습니다.

하지만 MemoCard 전체를 'use client'로 바꾸지 않습니다.

MemoCard          ← 서버 (제목, 내용, 링크)
└─ LikeButton     ← 클라이언트 (클릭, state)

큰 덩어리는 서버, 인터랙션 조각만 클라이언트.
이게 App Router에서 자주 쓰는 패턴입니다.

1) `LikeButton` 만들기

경로: components/LikeButton.tsx

"use client";

import { useState } from "react";

export default function LikeButton() {
  const [likes, setLikes] = useState(0);

  return (
    <button type="button" onClick={() => setLikes((prev) => prev + 1)}>
      좋아요 {likes}
    </button>
  );
}

반드시 파일 맨 위에 "use client" (또는 'use client')가 있어야 합니다.
이 한 줄이 “이 파일은 클라이언트 컴포넌트 경계”라는 표시입니다.

2) 서버 `MemoCard`에 조립

components/MemoCard.tsx는 'use client'를 붙이지 않습니다.

import Link from "next/link";
import type { Memo } from "@/types/memo";
import LikeButton from "@/components/LikeButton";

type MemoCardProps = {
  memo: Memo;
};

export default function MemoCard({ memo }: MemoCardProps) {
  return (
    <article>
      <h2>
        <Link href={`/memos/${memo.id}`}>{memo.title}</Link>
      </h2>
      <p>{memo.content}</p>
      <time dateTime={memo.createdAt}>{memo.createdAt}</time>
      <div>
        <LikeButton />
      </div>
    </article>
  );
}

서버 컴포넌트가 클라이언트 컴포넌트를 자식으로 import하는 것은 OK입니다.

반대로, 클라이언트 컴포넌트가 서버 컴포넌트를 같은 방식으로 막 import해서 서버 전용 이점을 유지하긴 어렵습니다.
(필요하면 children으로 서버 결과를 넘기는 패턴을 씁니다. 지금은 몰라도 됩니다.)

동작 확인

npm run dev
/memos에서 좋아요 클릭
숫자만 올라가면 성공

페이지를 새로고침하면 숫자는 0으로 돌아갑니다.
지금은 메모리 state만 쓰기 때문입니다. (저장은 7편 쪽에서 다룹니다.)

경계를 가르는 기준 (실전용)

고민될 때 이 순서로 물어보세요.

hooks / 이벤트가 필요한가?
→ 없으면 서버
파일 전체가 아니라 버튼/입력만 필요한가?
→ 작은 클라이언트 컴포넌트로 분리
데이터 읽기가 주목적인가?
→ 페이지/카드는 서버에 두는 쪽을 먼저 생각

좋은 방향
─────────
page (Server)
  └─ MemoCard (Server)
       └─ LikeButton (Client)

피하고 싶은 방향
─────────
page (Client)  ← 페이지 통째로
  └─ 모든 것

자주 하는 실수

1. "use client"를 함수 안에 씀
→ 반드시 파일 최상단 (import보다 위)

2. 서버 컴포넌트에서 useState 사용
→ 에러 납니다. state가 필요하면 그 부분만 클라이언트로 분리

3. Link가 있다고 무조건 클라이언트
→ next/link는 서버 컴포넌트에서도 사용 가능

4. 샘플이라서 전부 클라이언트로 통일
→ 나중에 습관이 됩니다. 처음부터 경계를 나누는 연습을 하세요

이 편에서 가져갈 것

App Router 기본은 Server Component다
hooks/이벤트가 필요할 때만 Client Component다
페이지 전체가 아니라 인터랙션 조각에 'use client'를 붙인다
서버 카드 + 클라이언트 버튼 조합이 기본 패턴이다

다음 편 예고

[Next.js + TS] 6. 데이터 가져오기

서버 컴포넌트에서 fetch 하기
loading.tsx / error.tsx 맛보기
lib/memos.ts 하드코딩에서 한 걸음 나아가기

지금은 로컬 배열을 읽고 있습니다.
다음 편에서 데이터를 가져오는 방식을 정리합니다.

시리즈 목차

왜 Next.js + TypeScript인가
프로젝트 만들고 폴더 구조 이해하기
TypeScript로 컴포넌트 타입 잡기
라우팅과 레이아웃
Server Component vs Client Component ← 지금
데이터 가져오기
폼과 서버 액션 입문
정리 + 다음 학습 로드맵

# [Next.js + TS] 4. 라우팅과 레이아웃

JaeSung Kim — Wed, 29 Jul 2026 14:52:47 +0900

[Next.js + TS] 4. 라우팅과 레이아웃

3편에서 홈에 샘플 카드를 붙였습니다.
이번 편은 URL로 화면을 나누고, 공통 내비는 layout에 둡니다.
목표: /memos 목록 · /memos/[id] 상세 · 상단 링크.

이 편에서 할 일

샘플 데이터를 공용 파일로 분리하기
/memos 목록 페이지 만들기
/memos/[id] 상세 페이지 만들기
MemoCard에 상세 링크 달기
layout.tsx에 간단한 내비 넣기

App Router 핵심은 다시 이겁니다.

폴더 = URL
page.tsx = 화면
layout.tsx = 공통 틀

왜 홈에만 두면 부족한가

지금은 / 하나에 목록이 다 있습니다.
실제 앱에서는 보통 이렇게 나눕니다.

URL	역할
`/`	소개/홈
`/memos`	메모 목록
`/memos/1`	id가 1인 메모 상세

React Router로 직접 구성하던 일을, Next에서는 폴더를 만드는 것으로 해결합니다.

1) 샘플 데이터 공용화

목록과 상세가 같은 데이터를 봐야 합니다.
app/page.tsx 안에만 두면 상세에서 못 씁니다.

경로: lib/memos.ts

import type { Memo } from "@/types/memo";

export const memos: Memo[] = [
  {
    id: "1",
    title: "Next.js 시작",
    content: "App Router로 프로젝트 만들었다.",
    createdAt: "2026-07-29",
  },
  {
    id: "2",
    title: "TypeScript props",
    content: "MemoCard에 타입을 붙였다.",
    createdAt: "2026-07-29",
  },
];

export function getMemoById(id: string): Memo | undefined {
  return memos.find((memo) => memo.id === id);
}

memos: 전체 목록
getMemoById: id로 하나 찾기

아직 DB/API는 없습니다.
라우팅 연습용 가짜 데이터로 충분합니다. (6편에서 fetch로 바꿉니다.)

2) 목록 페이지: `/memos`

폴더와 파일을 만듭니다.

app/
  memos/
    page.tsx

app/memos/page.tsx:

import MemoCard from "@/components/MemoCard";
import { memos } from "@/lib/memos";

export default function MemosPage() {
  return (
    <main>
      <h1>메모 목록</h1>

      <section>
        {memos.map((memo) => (
          <MemoCard key={memo.id} memo={memo} />
        ))}
      </section>
    </main>
  );
}

브라우저에서 http://localhost:3000/memos 를 열면 목록이 보여야 합니다.

memos라는 폴더 이름이 곧 URL 경로입니다.

3) 상세 페이지: `/memos/[id]`

동적 구간은 대괄호 폴더로 만듭니다.

app/
  memos/
    page.tsx
    [id]/
      page.tsx

/memos/1 → params.id === "1"
/memos/2 → params.id === "2"

app/memos/[id]/page.tsx:

import { notFound } from "next/navigation";
import { getMemoById } from "@/lib/memos";

type MemoDetailPageProps = {
  params: Promise<{ id: string }>;
};

export default async function MemoDetailPage({ params }: MemoDetailPageProps) {
  const { id } = await params;
  const memo = getMemoById(id);

  if (!memo) {
    notFound();
  }

  return (
    <main>
      <h1>{memo.title}</h1>
      <p>{memo.content}</p>
      <time dateTime={memo.createdAt}>{memo.createdAt}</time>
    </main>
  );
}

포인트:

코드	의미
`[id]`	URL의 가변 구간
`params`	그 구간 값이 들어옴
`await params`	최근 Next에서는 params가 Promise인 경우가 많음
`notFound()`	없는 id면 404

http://localhost:3000/memos/1 이 열리고,
/memos/999 는 404가 나면 성공입니다.

버전마다 params가 동기 객체인 템플릿도 있습니다.
타입이 Promise라고 나오면 await 하면 되고, 아니면 params.id를 그대로 쓰면 됩니다.

4) 카드에서 상세로 이동: `Link`

<a href>도 되지만, Next에서는 Link를 씁니다.
클라이언트 쪽 이동을 더 부드럽게 처리합니다.

components/MemoCard.tsx를 수정합니다.

import Link from "next/link";
import type { Memo } from "@/types/memo";

type MemoCardProps = {
  memo: Memo;
};

export default function MemoCard({ memo }: MemoCardProps) {
  return (
    <article>
      <h2>
        <Link href={`/memos/${memo.id}`}>{memo.title}</Link>
      </h2>
      <p>{memo.content}</p>
      <time dateTime={memo.createdAt}>{memo.createdAt}</time>
    </article>
  );
}

목록에서 제목을 누르면 상세로 가야 합니다.

5) 홈은 소개 페이지로

목록은 /memos로 옮겼으니, 홈은 가볍게 둡니다.

app/page.tsx:

import Link from "next/link";

export default function HomePage() {
  return (
    <main>
      <h1>Memo App</h1>
      <p>Next.js + TypeScript 시리즈 실습 프로젝트</p>
      <p>
        <Link href="/memos">메모 목록 보기</Link>
      </p>
    </main>
  );
}

6) 공통 내비: `layout.tsx`

모든 페이지 위에 링크를 두고 싶다면 app/layout.tsx에 넣습니다.

children 위에 내비만 추가하면 됩니다. (폰트 설정 등은 기존 것 유지)

import Link from "next/link";
import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "Memo App",
  description: "Next.js + TypeScript 실습",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="ko">
      <body>
        <header>
          <nav>
            <Link href="/">홈</Link>
            {" | "}
            <Link href="/memos">메모</Link>
          </nav>
        </header>
        {children}
      </body>
    </html>
  );
}

이미 Geist 폰트 등이 있다면 내비만 추가해도 됩니다.
중요한 건 위치입니다.

layout
├─ header/nav   ← 모든 페이지 공통
└─ children     ← page.tsx 내용

/, /memos, /memos/1 어디로 가든 위 링크가 보여야 합니다.

지금 폴더 구조

app/
  layout.tsx          → 공통 내비
  page.tsx            → /
  memos/
    page.tsx          → /memos
    [id]/
      page.tsx        → /memos/:id
components/
  MemoCard.tsx
lib/
  memos.ts
types/
  memo.ts

자주 하는 실수

1. app/memos.tsx 파일만 만듦
→ 목록은 app/memos/page.tsx 여야 /memos가 됩니다.

2. [id]를 일반 폴더명 id로 만듦
→ 대괄호가 있어야 동적 라우트입니다.

3. 상세에서 목록 데이터를 또 하드코딩
→ lib/memos.ts로 한곳에서 관리하세요.

4. Link에 href="#"
→ 반드시 /memos/${memo.id}처럼 실제 경로를 넣습니다.

이 편에서 가져갈 것

App Router는 폴더로 URL을 만든다
[id]는 동적 세그먼트다
목록/상세가 같은 데이터를 쓰면 lib로 분리한다
페이지 이동은 Link
모든 페이지 공통 UI는 layout.tsx

다음 편 예고

[Next.js + TS] 5. Server Component vs Client Component

기본이 서버 컴포넌트인 이유
언제 'use client'가 필요한지
클릭 같은 인터랙션은 어디에 두는지

지금은 “읽기 전용 페이지” 중심입니다.
다음 편에서 서버/클라이언트 경계를 나눕니다.

시리즈 목차

왜 Next.js + TypeScript인가
프로젝트 만들고 폴더 구조 이해하기
TypeScript로 컴포넌트 타입 잡기
라우팅과 레이아웃 ← 지금
Server Component vs Client Component
데이터 가져오기
폼과 서버 액션 입문
정리 + 다음 학습 로드맵

# [Next.js + TS] 3. TypeScript로 컴포넌트 타입 잡기

JaeSung Kim — Wed, 29 Jul 2026 14:41:08 +0900

[Next.js + TS] 3. TypeScript로 컴포넌트 타입 잡기

2편에서 프로젝트를 띄웠다면, 이번 편은 타입을 붙인 컴포넌트를 만듭니다.
목표: Memo 타입 정의 → MemoCard props 타입 → 홈에 샘플 메모 보여 주기.

이 편에서 할 일

메모 데이터 모델(Memo) 타입 만들기
props에 타입이 있는 MemoCard 컴포넌트 만들기
홈 페이지에 샘플 데이터로 카드 렌더하기

고급 타입(제네릭 마법, utility type 잔치)은 하지 않습니다.
props / 데이터 모델만 확실하게 잡습니다.

왜 컴포넌트에 타입을 붙이나

React만 쓸 때도 props는 넘어갑니다.
문제는 “이 컴포넌트가 뭘 받는지”가 코드만 봐서는 흐릿하다는 점입니다.

// 타입 없이
function MemoCard({ title, content }) {
  return <article>...</article>;
}

title이 string인지?
createdAt도 넘겨야 하는지?
오타로 titel을 넘기면?

TypeScript를 붙이면 받는 쪽과 주는 쪽이 같은 계약을 공유합니다.

1) 데이터 모델부터: `Memo` 타입

프로젝트에 타입 전용 파일을 하나 둡니다.

경로: types/memo.ts

export type Memo = {
  id: string;
  title: string;
  content: string;
  createdAt: string;
};

포인트:

type으로 객체의 모양을 고정한다
나중에 API/DB에서 같은 형태를 쓰면 한곳에서만 바꾸면 된다
id를 number로 할지 string으로 할지는 팀마다 다르지만, 이 시리즈는 string으로 통일한다

2) props 타입: `MemoCard`

컴포넌트 폴더를 만듭니다.

경로: components/MemoCard.tsx

import type { Memo } from "@/types/memo";

type MemoCardProps = {
  memo: Memo;
};

export default function MemoCard({ memo }: MemoCardProps) {
  return (
    <article>
      <h2>{memo.title}</h2>
      <p>{memo.content}</p>
      <time dateTime={memo.createdAt}>{memo.createdAt}</time>
    </article>
  );
}

읽어볼 것:

코드	의미
`import type`	타입만 가져옴 (런타임 코드 아님)
`MemoCardProps`	이 컴포넌트가 받는 props 계약
`{ memo }: MemoCardProps`	구조 분해 + 타입 적용
`memo.title`	`Memo`에 있는 필드만 자동완성됨

실수로 memo.titlle을 쓰면 에디터/타입이 바로 에러를 냅니다.
1편에서 말했던 “안전벨트”가 여기서 체감됩니다.

3) 홈에서 샘플 데이터로 연결

app/page.tsx를 아래처럼 바꿉니다.

import MemoCard from "@/components/MemoCard";
import type { Memo } from "@/types/memo";

const sampleMemos: Memo[] = [
  {
    id: "1",
    title: "Next.js 시작",
    content: "App Router로 프로젝트 만들었다.",
    createdAt: "2026-07-29",
  },
  {
    id: "2",
    title: "TypeScript props",
    content: "MemoCard에 타입을 붙였다.",
    createdAt: "2026-07-29",
  },
];

export default function HomePage() {
  return (
    <main>
      <h1>Memo App</h1>
      <p>샘플 메모 목록</p>

      <section>
        {sampleMemos.map((memo) => (
          <MemoCard key={memo.id} memo={memo} />
        ))}
      </section>
    </main>
  );
}

확인 포인트:

sampleMemos: Memo[] → 배열 원소가 전부 Memo여야 함
필드 하나 빠지거나 이름 틀리면 페이지에서 바로 빨간줄
key={memo.id}는 React 리스트 렌더링 기본기 (타입과는 별개, 필수)

npm run dev로 http://localhost:3000을 보면 카드 두 개가 보여야 합니다.

props를 펼치는 다른 방식 (참고)

지금은 memo 객체 하나를 통째로 넘겼습니다.

가끔은 필드를 하나씩 받기도 합니다.

type MemoCardProps = {
  title: string;
  content: string;
  createdAt: string;
};

둘 다 틀린 건 아닙니다.

이 시리즈 추천:

데이터가 하나의 모델이면 객체로 넘긴다 (memo: Memo)

필드가 늘어날 때마다 props를 하나씩 추가하는 것보다,
모델만 고치면 되어서 유지보수가 쉽습니다.

`@/` 는 뭐지?

create-next-app에서 import alias를 켰다면:

import type { Memo } from "@/types/memo";

@/는 보통 프로젝트 루트를 가리킵니다.
tsconfig.json의 paths에 정의되어 있습니다.

상대 경로 지옥(../../../types/memo)을 피하려고 쓰는 설정입니다.

자주 하는 실수

1. Memo를 값처럼 import
→ 타입만 쓸 때는 import type { Memo } 권장

2. props 타입을 안 쓰고 매개변수만 적음
→ ({ memo })만 쓰면 memo가 any에 가까워져 이득이 사라짐

3. key를 인덱스(index)로만 씀
→ 샘플에선 당장 안 터져도, 목록이 바뀌면 버그 나기 쉬움. id 사용

4. types 폴더 위치 착각
→ app/types가 아니라 프로젝트 루트의 types/ (이 시리즈 기준)

이 편에서 가져갈 것

데이터 모양은 type으로 먼저 고정한다
컴포넌트 props에도 같은 타입을 연결한다
Memo[]로 샘플을 만들면 잘못된 데이터가 즉시 드러난다
모델 하나면 props도 객체 하나로 넘기는 편이 단순하다

다음 편 예고

[Next.js + TS] 4. 라우팅과 레이아웃

/memos 목록 페이지 만들기
/memos/[id] 상세 페이지
layout.tsx에 간단한 내비 넣기

지금은 홈에 샘플이 붙어 있는 상태입니다.
다음 편에서 URL별로 화면을 나누기 시작합니다.

시리즈 목차

왜 Next.js + TypeScript인가
프로젝트 만들고 폴더 구조 이해하기
TypeScript로 컴포넌트 타입 잡기 ← 지금
라우팅과 레이아웃
Server Component vs Client Component
데이터 가져오기
폼과 서버 액션 입문
정리 + 다음 학습 로드맵

# [Next.js + TS] 2. 프로젝트 만들고 폴더 구조 이해하기

JaeSung Kim — Wed, 29 Jul 2026 14:33:30 +0900

[Next.js + TS] 2. 프로젝트 만들고 폴더 구조 이해하기

1편에서 “왜 Next + TS인지”를 봤다면, 이번 편은 실제로 프로젝트를 띄우고 폴더를 열어보는 시간입니다.
목표: create-next-app → 실행 → app/page.tsx 문구 바꾸기까지.

이 편에서 할 일

Next.js + TypeScript 프로젝트 생성
로컬에서 실행해 보기
app/ 폴더 구조 읽기
홈 화면 문구를 바꿔 “여기가 페이지다”를 몸으로 익히기

설치만 하고 끝내면 금방 까먹습니다.
한 줄이라도 직접 고쳐 보는 것이 이번 편의 실습입니다.

사전 준비

아래가 있으면 됩니다.

Node.js (LTS 권장, 18 이상)
터미널 (PowerShell, cmd, 또는 VS Code/Cursor 터미널)
코드 에디터

버전 확인:

node -v
npm -v

숫자가 나오면 OK입니다.

프로젝트 만들기

터미널에서 원하는 폴더로 이동한 뒤:

npx create-next-app@latest memo-app

질문에 대략 이렇게 답하면 이 시리즈와 맞습니다.

질문	추천 답
TypeScript?	Yes
ESLint?	Yes
Tailwind CSS?	Yes (있어도 되고, 없어도 됨)
`src/` directory?	No (처음엔 `app/`이 루트에 있는 편이 단순)
App Router?	Yes
Turbopack?	Yes여도 무방
import alias (`@/*`)?	Yes

생성이 끝나면:

cd memo-app
npm run dev

브라우저에서 http://localhost:3000 을 엽니다.
Next 기본 시작 화면이 보이면 성공입니다.

왜 이 명령어인가

npx: 패키지를 전역 설치하지 않고 실행
create-next-app: Next 공식 스캐폴딩 도구
@latest: 최신 템플릿 사용

직접 package.json을 손으로 조립해도 되지만,
처음에는 공식 템플릿으로 시작하는 게 삽질이 적습니다.

폴더 구조, 지금 볼 것만

생성된 프로젝트에서 지금은 이것만 보면 됩니다.

memo-app/
  app/
    layout.tsx
    page.tsx
    globals.css
  public/
  package.json
  tsconfig.json
  next.config.ts   (또는 next.config.mjs)

`app/`

App Router의 중심입니다.
페이지와 레이아웃이 여기 있습니다.

`app/page.tsx`

/ (홈) 화면입니다.
이 파일의 return JSX가 브라우저에 보입니다.

`app/layout.tsx`

모든 페이지를 감싸는 공통 틀입니다.
<html>, <body>, 공통 폰트, 나중에 넣을 헤더 같은 것이 여기로 옵니다.

`app/globals.css`

전역 스타일입니다.
이번 시리즈에서는 깊게 안 들어가도 됩니다.

`package.json`

스크립트와 의존성 목록입니다.
npm run dev가 여기서 정의됩니다.

`tsconfig.json`

TypeScript 설정입니다.
지금은 “TS가 켜져 있다” 정도만 알면 충분합니다.

`public/`

이미지, 파비콘처럼 그대로 서빙할 정적 파일 자리입니다.

핵심 파일 열어보기

1) `app/layout.tsx`

대략 이런 형태입니다. (버전마다 세부 표현은 조금 다를 수 있음)

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

포인트:

children = 각 page.tsx가 들어가는 자리
홈이든 /memos든, 결국 이 레이아웃 안에 렌더됩니다

2) `app/page.tsx`

기본 템플릿에는 데모 UI가 잔뜩 들어 있습니다.
우리는 메모 앱의 홈으로 바꿀 겁니다.

실습: 홈 화면 문구 바꾸기

app/page.tsx를 아래처럼 간단하게 교체합니다.

export default function HomePage() {
  return (
    <main>
      <h1>Memo App</h1>
      <p>Next.js + TypeScript 시리즈 실습 프로젝트</p>
    </main>
  );
}

저장 후 브라우저를 보면:

제목이 Memo App
아래 설명 문구

로 바뀌어 있어야 합니다.

이게 이번 편의 핵심 체감입니다.

app/page.tsx를 고치면 /가 바뀐다.

React에서 컴포넌트를 수정하는 감각과 같습니다.
차이점은 이 파일이 곧 라우트라는 점입니다.

`layout`과 `page` 관계 (그림으로)

layout.tsx
└─ page.tsx   ← 지금 고친 홈

나중에 /memos를 만들면:

layout.tsx
├─ page.tsx          → /
└─ memos/page.tsx    → /memos

공통 헤더를 layout.tsx에 넣으면 두 페이지에 다 보입니다.
(헤더는 4편에서 본격적으로 다룹니다.)

자주 하는 실수

1. 서버가 안 떠 있는데 브라우저만 새로고침
→ 터미널에서 npm run dev가 켜져 있는지 확인

2. 다른 폴더의 파일을 수정
→ 지금 실행 중인 memo-app 안의 app/page.tsx인지 확인

3. 저장을 안 함
→ 에디터에 흰 점(미저장) 표시가 있으면 Ctrl+S

4. 포트가 이미 사용 중
→ localhost:3000 대신 터미널에 나온 다른 포트(예: 3001)로 접속

이 편에서 가져갈 것

Next 프로젝트는 create-next-app으로 시작하는 게 가장이다
App Router의 중심은 app/이다
page.tsx = 그 경로의 화면
layout.tsx = 화면들을 감싸는 공통 틀
홈을 바꾸려면 app/page.tsx를 고치면 된다

다음 편 예고

[Next.js + TS] 3. TypeScript로 컴포넌트 타입 잡기

props에 타입 붙이기
메모 카드 같은 작은 컴포넌트 만들기
Memo 타입을 실제로 화면에 연결하기

다음 편부터 “폴더만 있는 상태”에서 타입이 있는 UI 조각으로 넘어갑니다.

시리즈 목차

왜 Next.js + TypeScript인가
프로젝트 만들고 폴더 구조 이해하기 ← 지금
TypeScript로 컴포넌트 타입 잡기
라우팅과 레이아웃
Server Component vs Client Component
데이터 가져오기
폼과 서버 액션 입문
정리 + 다음 학습 로드맵

[Next.js + TS] 1. 왜 Next.js + TypeScript인가

JaeSung Kim — Wed, 29 Jul 2026 14:26:11 +0900

[Next.js + TS] 1. 왜 Next.js + TypeScript인가

React는 써 봤고, 이제 Next.js와 TypeScript를 제대로 잡고 싶은 사람을 위한 시리즈입니다.
App Router 기준으로 작은 메모 앱을 만들며 개념과 실습을 같이 갑니다.

이 시리즈에서 하는 일

React만으로도 화면은 만들 수 있습니다.
다만 실제 서비스에 가까워질수록 이런 질문이 생깁니다.

페이지(라우팅)는 어떻게 나눌까?
SEO / 초기 로딩은?
서버에서 데이터를 가져오는 게 나을까, 클라이언트에서 할까?
props랑 API 응답 타입이 자꾸 틀어지는데?

Next.js는 React 위에 앱에 필요한 뼈대를 올려 준 프레임워크이고,
TypeScript는 그 뼈대와 데이터를 타입이 있는 계약으로 붙잡아 줍니다.

이 시리즈는 이론만 늘어놓지 않습니다.
매 편 왜 쓰는지 → 핵심 개념 → 따라 치는 코드 → 정리 순서로 갑니다.

React만 쓸 때 vs Next.js

	React (CRA/Vite 등)	Next.js (App Router)
역할	UI 라이브러리	React 기반 풀스택 프레임워크
라우팅	react-router 등을 직접 구성	폴더 구조로 페이지 생성
렌더링	기본적으로 클라이언트 중심	서버/클라이언트 컴포넌트를 나눔
데이터	useEffect + fetch가 흔함	서버에서 fetch, Server Actions 등
배포 관점	SPA로 시작하는 경우가 많음	페이지/레이아웃 단위로 최적화하기 쉬움

한 줄로 말하면:

React = 부품
Next.js = 그 부품으로 집을 짓는 설계도 + 공구

React를 안다면 JSX, props, state, hooks는 그대로 씁니다.
Next.js는 그 위에 파일 기반 라우팅, 서버 컴포넌트, 데이터/폼 처리 같은 규칙을 더합니다.

왜 TypeScript를 같이 쓰나

TypeScript는 “어려운 문법 모음”이 아니라, 실수 예방용 안전벨트에 가깝습니다.

예를 들어 메모 객체:

type Memo = {
  id: string;
  title: string;
  content: string;
  createdAt: string;
};

이렇게 정해 두면:

memo.titlle 같은 오타를 에디터가 바로 잡아 줍니다
컴포넌트 props가 뭐가 필요한지 읽지 않아도 보입니다
API 응답 형태가 바뀌면 쓰는 쪽이 깨져서 빨리 알아챕니다

React만 쓸 때도 TS는 유용하지만,
Next.js처럼 페이지 · 레이아웃 · 서버/클라이언트 경계가 늘어날수록 타입의 이득이 커집니다.

이 시리즈에서는 고급 타입 마법을 하지 않습니다.
props, 데이터 모델, 함수 인자/반환 정도만 확실하게 잡습니다.

App Router를 한눈에

Next.js 13 이후 기본은 App Router입니다.
핵심은 단순합니다.

app/
  layout.tsx   → 공통 레이아웃 (헤더, 폰트 등)
  page.tsx     → "/" 페이지
  memos/
    page.tsx   → "/memos" 목록
    [id]/
      page.tsx → "/memos/123" 상세

폴더 이름이 URL이 됩니다
page.tsx가 있어야 그 경로가 페이지로 열립니다
layout.tsx는 하위 페이지를 감싸는 공통 UI입니다

나중에 다룰 Server Component / Client Component도 이 구조 위에서 이해하면 됩니다.

지금은 이것만 기억하면 충분합니다.

URL = 폴더
화면 = page.tsx
공통 틀 = layout.tsx

실습 예고: 메모 앱

앞으로 만들 것은 거창한 SaaS가 아닙니다.

메모 목록 보기
메모 상세 보기
메모 추가하기

이 작은 흐름 안에 라우팅, 타입, 서버/클라이언트, 데이터, 폼이 다 들어갑니다.

“예제용 코드 조각”보다 이어지는 앱 하나로 가면, 복습할 때 훨씬 편합니다.

이 편에서 가져갈 것

Next.js는 React를 대체하는 게 아니라, React로 앱을 만들기 위한 프레임워크다
TypeScript는 문법이 목적이 아니라, 데이터와 props의 계약을 고정한다
App Router는 폴더 = URL, page = 화면, layout = 공통 틀이다

다음 편 예고

[Next.js + TS] 2. 프로젝트 만들고 폴더 구조 이해하기

create-next-app으로 프로젝트 생성
app/, page.tsx, layout.tsx 직접 열어보기
첫 화면 문구를 바꿔 보며 “여기가 홈이다”를 몸으로 익히기

시리즈 목차

왜 Next.js + TypeScript인가 ← 지금
프로젝트 만들고 폴더 구조 이해하기
TypeScript로 컴포넌트 타입 잡기
라우팅과 레이아웃
Server Component vs Client Component
데이터 가져오기
폼과 서버 액션 입문
정리 + 다음 학습 로드맵

질문이나 “이 부분 더 풀어서” 싶은 구간 있으면 댓글로 남겨 주세요.
다음 편에서 실제로 프로젝트를 띄웁니다.

# 면접 CS 정리 Day 1 (풀스택 / Java·Spring·React)

JaeSung Kim — Wed, 29 Jul 2026 14:12:47 +0900

면접 CS 정리 Day 1 (풀스택 / Java·Spring·React)

Q1. PUT vs PATCH

문제
HTTP PUT과 PATCH의 차이, 실무에서 각각 언제 쓰는가?

답

PUT: 리소스 전체 교체. 빠진 필드가 있으면 null로 덮일 수 있음
PATCH: 부분 수정. 요청으로 온 필드만 변경

생성은 보통 POST, 전체 수정은 PUT, 일부 수정은 PATCH.

Q2. 생성자 주입을 선호하는 이유

문제
Spring에서 필드 주입(@Autowired on field)보다 생성자 주입을 선호하는 이유는?

답

테스트 시 mock 객체를 생성자로 넣기 쉽다
final로 필수 의존성을 명확히 하고 불변으로 유지할 수 있다
의존성 누락 시 객체 생성이 실패해서 문제를 빨리 발견한다

참고
생성자 주입이 순환참조를 “막아 주는” 것은 아니다.
순환이면 기동 시 바로 실패해서 설계를 고치게 만든다.

Q3. 인덱스가 있는데도 느린 이유

문제
인덱스를 만들었는데도 쿼리가 느릴 때 의심할 원인 2가지는?

답

조건 때문에 인덱스를 못 탐 (함수 감싸기, LIKE '%keyword', 타입 불일치)
선택도가 낮거나, 가져와야 할 행이 너무 많음

실행계획(EXPLAIN)에서 type = ALL, key = NULL 여부를 먼저 본다.

Q4. GET으로 데이터를 바꾸면 안 되는 이유

문제
왜 GET으로 서버 상태를 변경하면 안 되는가?

답

GET은 safe해야 한다 → 조회만, 상태 변경 X
브라우저 프리페치, 크롤러, 캐시가 GET을 자동 호출할 수 있음
URL/로그/히스토리에 남아 의도치 않은 변경·노출이 생길 수 있음

변경은 POST / PUT / PATCH / DELETE를 사용한다.
(POST가 무조건 더 보안에 강하다기보다, 메서드 의미가 다르다.)

Q5. React list의 key

문제
리스트 렌더링에서 key에 id를 쓰고 index를 잘 안 쓰는 이유는?

답
key는 React가 어떤 항목을 재사용/추가/삭제할지 구분하는 식별자다.

index를 key로 쓰면 삽입·삭제·순서 변경 시 항목이 잘못 매칭되어
input 값이 밀리거나 불필요한 리렌더가 발생할 수 있다.
그래서 고유한 id를 사용한다.

Q6. 트랜잭션 전파 REQUIRED

문제
@Transactional의 기본 propagation REQUIRED는
트랜잭션이 있을 때 / 없을 때 각각 어떻게 동작하는가?

답

트랜잭션 없음 → 새로 시작
트랜잭션 있음 → 기존 트랜잭션에 참여

한 줄: 있으면 쓰고, 없으면 만든다.
보너스: REQUIRES_NEW는 기존 트랜잭션과 분리해 무조건 새 트랜잭션을 연다.

Q7. CORS

문제
CORS가 무엇인가? Spring에서 정석으로 어떻게 해결하는가?

답
브라우저가 다른 Origin(스킴 + 호스트 + 포트)으로 요청할 때
보안상 제한하는 정책이다.

서버에서 허용 Origin/메서드/헤더를 설정한다.
(Spring: CorsConfiguration, Security CORS 등)

로컬 개발에서는 프론트 개발 서버 프록시로 우회하기도 한다.

오늘 한 줄 암기

PUT = 전체 교체 / PATCH = 부분 수정
GET = 조회만 (safe)
REQUIRED = 있으면 참여, 없으면 생성
React key = 고유 id
CORS = Origin이 다를 때 브라우저 제한

Claude Code / Cursor 개발 필수 스킬 4가지 설정법

JaeSung Kim — Wed, 22 Jul 2026 16:45:44 +0900

Claude Code / Cursor 개발 필수 스킬 4가지 설정법

AI 코딩 에이전트(Claude Code, Cursor)를 쓸 때 "그냥 시키는 대로 코드를 뱉는" 상태에서 벗어나게 해주는 스킬 4개를 정리했다. 각 스킬은 서로 다른 축을 커버하기 때문에 겹치지 않고 같이 쓸 수 있다.

스킬	관여하는 영역
Karpathy Guidelines	사고방식 전반 (가정 명시, 최소 수정, 검증 기준)
Ponytail	코드량 (과잉설계 방지, YAGNI)
Caveman	말투/응답 토큰량 (불필요한 설명 압축)
Superpowers	개발 프로세스 자체 (기획 → 계획 → TDD → 검증)

1. Karpathy Guidelines

Andrej Karpathy가 지적한 "LLM 코딩의 흔한 실수 패턴"을 CLAUDE.md 파일 하나로 방지하는 원칙 모음이다. 별도 프로그램이 아니라 순수 텍스트 파일이라 이식성이 가장 좋다.

핵심 원칙

가정 드러내기 — 애매하면 짐작하지 않고 명시
과잉설계 방지 — 요청하지 않은 기능·추상화 금지
외과수술식 수정 — 필요한 부분만 건드리기
검증 가능한 성공 기준 — 확인 가능한 완료 조건 먼저 정하기

Claude Code 설정

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

프로젝트 루트에 두면 세션 시작 시 자동으로 읽힌다. 이미 CLAUDE.md가 있다면 덮어쓰지 말고 뒤에 이어붙이기(append) 하는 것을 권장한다.

Cursor 설정

mkdir -p .cursor/rules
curl -o .cursor/rules/karpathy.mdc https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

프로젝트 전체가 아니라 모든 프로젝트에 적용하고 싶다면 홈 디렉토리의 ~/.cursor/rules/에 넣거나, Cursor Settings → Rules → User Rules에 내용을 붙여넣으면 된다.

커스터마이징
받은 파일 그대로 쓰지 말고 스택, 명령어, 컨벤션, 금지사항을 추가해서 120줄 이내로 다듬는 것이 좋다.

2. Ponytail

"이 코드 진짜 필요해?"를 강제로 묻는 YAGNI 결정 사다리 스킬이다. 과잉설계 함정(예: 날짜 피커 라이브러리 대신 <input type="date">)을 잡아내는 데 특화되어 있다.

Claude Code 설정

/plugin marketplace add DietrichGebert/ponytail
/plugin add ponytail@ponytail

설치 후 첫 세션에서 hook 신뢰(trust) 여부를 확인하라는 프롬프트가 뜨면 승인한다. node가 PATH에 잡혀 있어야 정상 작동하며, 정상 작동 시 상태줄에 [PONYTAIL] 뱃지가 표시된다.

Cursor 설정

mkdir -p .cursor/rules
# 저장소의 .cursor/rules 안 규칙 파일을 복사

Claude Code의 hook 기반 자동 활성화·상태줄 표시는 재현되지 않지만, 핵심 규칙 내용은 동일하게 적용된다.

리뷰 기능
코드 작성 후 /ponytail-review를 입력하면 과잉설계된 부분만 짚어준다. 단, 버그·보안 이슈는 다루지 않으므로 일반 코드 리뷰와 병행해야 한다.

3. Caveman

Claude의 응답 자체를 압축하는 스킬이다. 코드를 줄이는 게 아니라 서론·반복 설명·과한 안내문 같은 텍스트를 없애 출력 토큰을 줄인다.

설치 (Skills CLI, 여러 툴 공유 가능)

npx skills add https://github.com/juliusbrussee/caveman --skill caveman -g

글로벌(-g) 설치 시 여러 호환 툴이 공유하는 폴더에 들어가 Cursor 등에서도 인식될 수 있다.

Cursor 개별 설정

mkdir -p .cursor/rules
# 저장소 규칙 파일을 .cursor/rules/에 복사

참고

lite / full / ultra 강도를 선택해서 저장 가능
위험한 작업(테이블 삭제 등)에서는 자동으로 정상 모드로 돌아옴
팀원과 세션을 공유하거나 PR 코멘트로 남길 계획이면 lite 모드를 권장

4. Superpowers

코드 스타일이 아니라 개발 프로세스 전체를 강제하는 프레임워크다. Jesse Vincent(obra)가 만들었으며 14개 스킬이 세트로 묶여 있다.

핵심 흐름

brainstorming(요구사항 탐색) → writing-plans(계획 작성)
→ TDD(실패하는 테스트 먼저 작성) → 실행 → verification(완료 검증)

Claude Code 설정

/plugin install superpowers@claude-plugins-official

Cursor 설정
Cursor 마켓플레이스에서 "Superpowers" 검색 후 설치하거나, 채팅창에 아래 명령 입력:

/add-plugin superpowers

Cursor 팀이 공식 인증(Verified)한 몇 안 되는 플러그인이라 설치가 가장 간단하다.

설치 확인 방법
새 기능을 요청했을 때 AI가 바로 코드를 쓰지 않고 요구사항을 먼저 되묻는다면 정상 작동 중인 것이다.

스코프(적용 범위) 정리

구분	Claude Code	Cursor
전역(모든 프로젝트)	`~/.claude/skills/` 또는 플러그인 설치	`~/.cursor/rules/` 또는 Settings → User Rules
프로젝트 단위	프로젝트 루트 `CLAUDE.md` 또는 `./.claude/skills/`	프로젝트 루트 `.cursor/rules/`

플러그인/스킬은 한 번 설정해두면 이후 세션마다 자동으로 로드되며, 매번 다시 설정할 필요는 없다.

git 수정한 파일이 없는데 intelij에 staging에 올라가있는경우

JaeSung Kim — Wed, 27 May 2026 14:49:45 +0900

intelij를 사용하다가 상단에 Contents have differences only in line separators 알림이 보이고, staging에 수정하지 않은 파일들이 올라갔을경우 아래 명령어를 터미널에 입력하여 해결합니다.

#1. Git core.autocrlf 설정 (권장)
git config --global core.autocrlf true

#2. 현재 스테이징된 찌꺼기 파일들 한 번에 정리하기
git add --renormalize .

커서 AI 세팅

JaeSung Kim — Wed, 29 Apr 2026 14:42:09 +0900

모델선택

Claude 3.5 Sonnet: 현재 코딩에서 가장 똑똑하다고 평가받는 모델입니다. 기본으로 설정하는 걸 추천합니다.

GPT-4o: 논리적인 설명이나 일반적인 질문에 강점이 있습니다.

필수 성능 세팅

.cursorignore

- 프로젝트 루트에 해당 파일을 생성후 cursor가 인덱싱 하지 않을 파일을 설정합니다.

# 빌드 결과물 제외
dist/
build/

# 의존성 라이브러리 제외 (커서가 이미 구조를 알고 있으므로 인덱싱에서 제외하면 가벼워짐)
node_modules/

# 환경 변수 및 보안 파일 (가장 중요!)
.env
*.pem
keys/

# 로그 파일
*.log

.cursorrules

- 프로젝트 루트에 해당 파일을 생성후 사용자가 프롬프트를 적어 규칙을 지정함

- 모든 답변은 한국어로 친절하게 설명해줘.
- 코드 변경 전후의 핵심 차이점을 간단히 요약해줘.

Thinking 끄기

Thinking을 켜놓으면 그만큼 토큰이 많이 소모됨, 정말 풀리지않는 문제일경우만 Thinking 키기

Chat 10개정도 쌓이면 새로운 Chat 열어서 하기

- Chat에 내용이 너무 많이 쌓이면 ai가 이전 대화도 읽어서 실행하기 때문에 그만큼 토큰도 많이 소모됨

커서 AI 외부 데이터 수집차단 설정 방법

JaeSung Kim — Wed, 29 Apr 2026 14:33:41 +0900

오른쪽 상단 톱니바퀴 버튼 클릭

General탭에서 맨하단에 privacy를 Privacy Mode로 변경

월배당 계산기 (자산 시뮬레이터)

JaeSung Kim — Fri, 24 Apr 2026 15:06:14 +0900

https://stock-ten-iota.vercel.app/

월배당 자산 시뮬레이터

월배당 ETF 배당 재투자와 장기 자산 성장을 계산해보세요. 일반계좌·ISA계좌별 세후 수익 시뮬레이션.

stock-ten-iota.vercel.app

배당주에 관심이있어서 월배당 자산 시뮬레이터를 React, Typescript 바이브 코딩으로 만들어봤습니다.

서버에 정보를 수집하는거 없이 사용할수 있게 만들었습니다.

사용법

배당 시뮬레이션을 실행하고자하는 기간을 설정, 시작년월, 환율을 설정합니다.

추가 버튼을 클릭해서 배당주의 종목명 티커 투자하고자하는 계좌, 가격 등을 입력합니다.

차트로 표현

월별 예상 적립금, 배당금, 평가금, 누적원금등을 시뮬레이션 하게 개발하였습니다.

시뮬레이터이기 때문에 100프로 정확하지는 않습니다. 주식 가격이 계속 변동되고 배당금도 변하기때문에

Intelij Smart Tomcat 설정 방법

JaeSung Kim — Thu, 16 Apr 2026 15:48:32 +0900

간혹 프로젝트를 하다보면 Spring boot가 아닌 레거시 프로젝트를 진행할때가 있는데요.

해당 프로젝트를 실행하기 위해 smart tomcat을 설치하고 설정하는법을 포스팅 하였습니다.

File - Settings

- SmartTomcat 플러그인 installed

오른쪽 상단에 점 클릭후 Edit ... 클릭

- 플러스 버튼 클릭후 Smart Tomcat 클릭

- Tomcat Server: 오른쪽에 폴더모양 클릭후 pc에 설치한 Apache Tomcat을 선택해서 설정합니다.

만약 apache tomcat이 없을경우

아래 링크 접속후 download에서 받고자하는 버전의 톰캣을 다운로드합니다.

https://tomcat.apache.org/download-90.cgi

- Context Path는 톰캣을 실행했을때 맨뒤에 처음에 붙는 root context 입니다.

- Server Port는 8080포트로 띄우겠다 이런 뜻입니다.

VM options는 톰캣에 환경변수를 설정할수 있는데, 저가 설정한거는 로컬에서 톰캣을 실행했을때, log4j2-dev.xml 개발 로그 설정 파일을 바라보겠다 이런 뜻입니다.

이후 플레이 버튼 누르면 정상적으로 실행이 됩니다. 만약 안되면 build가 안되서 그럴경우가 대부분이므로, rebuild를 다시한후 실행하면 됩니다.

Intelij 단축키 설정

JaeSung Kim — Thu, 16 Apr 2026 15:32:09 +0900

1. 검색 및 이동

shift 2번

- 파일설정 클래스등 모든 것을 검색

Ctrl + N

- Java 클래스 파일을 이름으로 검색

Ctrl + Shift + N

- 모든 형식의 파일을 검색

Ctrl + E

- 최근에 열었던 파일 리스트 확인

Ctrl + B

- 메서드나 변수가 정의된 곳으로 이동 (Go to Declaration)

- test(); 에 커서를 두고 ctrl+B를 누르면 아래 test 정의된곳으로 커서가 감

2. 코드 편집

Ctrl + Space bar

- 가장 기본적인 자동 완성

Ctrl + Shift + Enter

- 세미콜론(;)이나 중괄호({})를 자동으로 채우고 줄바꿈

Ctrl + Alt + L

- 설정된 포맷에 맞춰 코드를 깨끗하게 정리 (Reformat Code)

Ctrl + D

- 현재 커서가 있는 줄을 바로 아래에 복사

Ctrl + Y

- 현재 커서가 있는 줄을 삭제

Ctrl + / (주석)

// 주석 처리 및 해제

Alt + Enter

- 에러 수정 제안이나 Quick Fix 실행 (가장 중요!)

3. 리팩토링

Shift + F6

- 변수, 메서드, 클래스 이름을 전체적으로 안전하게 변경

Ctrl + Alt + V

값을 먼저 입력하고 ctrl + Alt + V를 누르면 자동완성

- 리턴값이나 식을 변수로 추출 (Introduce Variable)

Ctrl + Alt + M

- 특정 코드 블록을 별도 메서드로 분리

Ctrl + Alt + P

- 메서드 내부의 값을 파라미터로 변경

4. 디버깅 및 실행

Shift + F10

- 프로젝트 실행

Shift + F9

- 디버깅 모드 실행

Ctrl + F8

- 브레이크 포인트(Breakpoint) 설정/해제

F8 / F7

- Step Over (다음 줄) / Step Into (메서드 안으로)

5. 보너스

Multi-Cursor

- Alt + Click 또는 Alt + Shift + Insert를 이용해 여러 줄을 동시에 수정할 수 있습니다.

Key Promoter X 플러그인

- 해당 플러그인 install을 하면 마우스 클릭시 오른쪽 하단 팝업으로 단축키를 알려줘서 자연스럽게 익힐수 있습니다.

- 예를들면 ctrl + 마우스왼쪽 클릭으로 메서드를 클릭해서 들어갔을경우 Ctrl + B로 들어갈수 있다고 알려주네요

Error occurred during initialization of VMjava.lang.Error: Properties init: Could not determine current working directory.at jdk.internal.util.SystemProps$Raw.platformProperties(java.base@17.0.18/Native Method)at jdk.internal.util.SystemProps$Raw.<init>(j

JaeSung Kim — Mon, 23 Feb 2026 17:27:07 +0900

Error occurred during initialization of VM
java.lang.Error: Properties init: Could not determine current working directory.
at jdk.internal.util.SystemProps$Raw.platformProperties(java.base@17.0.18/Native Method)
at jdk.internal.util.SystemProps$Raw.<init>(java.base@17.0.18/SystemProps.java:234)
at jdk.internal.util.SystemProps.initProperties(java.base@17.0.18/SystemProps.java:54)
at java.lang.System.initPhase1(java.base@17.0.18/System.java:2106)

ssh에서 java -version을 입력했을때 위와 같은 에러가 발생하였습니다.

이경우 java 자체의 결함이기보단 현재 터미널에 위치한 디렉터리가 갑자기 삭제되었거나 그럴때 터미널이 위치한 폴더를 시스템이 찾지 못했을때 생기는 에러입니다.

cd /
java -version

상위 폴더나 루트 디렉터리로 이동후 다시 입력을 해보면 정상적으로 java version이 표기가 됩니다.

Vue3 기본문법

JaeSung Kim — Thu, 15 Jan 2026 13:56:13 +0900

1. App.vue

<script setup lang="ts">
</script>

<template>
  <h1>Hello Vue 3</h1>
</template>

<style scoped>
</style>

- script setup -> Vue3 권장 문법

- template -> 화면

- style scoped -> 이 컴포넌트에만 스타일 적용

2. 반응형 데이터 (ref)

<script setup lang="ts">
import { ref } from "vue";

const count = ref(0);
</script>

<template>
  <h1>Count: {{ count }}</h1>
</template>

- ref(값) -> 반응형

- template에서는 .value 안씀

3. 이벤트 바인딩 (click)

<script setup lang="ts">
import { ref } from "vue";

const count = ref(0);

function increment(){
  count.value++;
}

</script>

<template>
  <h1>Count: {{ count }}</h1>
  <button @click="increment" >+</button>
</template>

- @click = v-on:click

- script에서는 .value로 값을 뽑음

- 버튼 클릭시 count를 1씩 증가

4. v-model (양방향 바인딩)

<script setup lang="ts">
import { ref } from "vue";

const name = ref("");
</script>

<template>
  <input v-model="name" placeholder="이름 입력" />
  <p>안녕하세요, {{ name }}</p>
</template>

- v-model = input <-> state 자동 연결

- form에서 필수 문법

5. 조건 렌더링 (v-if)

<script setup lang="ts">
import { ref } from "vue";

const isLogin = ref(false);
</script>

<template>
  <button @click="isLogin = !isLogin">
    로그인 토글
  </button>

  <p v-if="isLogin">로그인 상태</p>
  <p v-else>로그아웃 상태</p>
</template>

- 기본값 false이므로 처음 화면은 로그아웃 상태, 버튼 클릭시 로그인 상태로 변경됨

- 조간이 자주 바뀌면 v-show 고려,

6. reactive vs ref

- ref : 원시값 (number, string, boolean)

- reactive : 객체, 폼데이터

<script setup lang="ts">
import { reactive, ref } from "vue";

const count = ref(0);

const user = reactive({
  name: "",
  age: 0,
})
</script>

<template>
  <p>count: {{ count }}</p>

  <input v-model="user.name" placeholder="이름" />
  <input v-model="user.age" type="number" placeholder="이름" />

  <p>{{ user.name }} // {{ user.age }}</p>
</template>

- reactive는 .value 못씀

- 객체는 왠만하면 reactive

7. computed

<script setup lang="ts">
import { computed, ref } from "vue";

const count = ref(0);

const doubleCount = computed(() => {
  return count.value * 2;
})

</script>

<template>
  <button @click="count++"></button>
  <p>count: {{ count }}</p>
  <p>double: {{ doubleCount }}</p>
</template>

- 값 가공은 computed

- computed는 캐싱효과가 있음

7-1. computed 캐싱

<script setup lang="ts">
import { computed, ref } from "vue";

const count = ref(0);

const doubleCount = computed(() => {
  console.log("computed")
  return count.value * 2;
})

const test = () => {
  console.log("method");
  return count.value * 2;
}

</script>

<template>
  <button @click="count++"></button>
  <p>count: {{ count }}</p>
  <p>double: {{ doubleCount }}</p>
  <p>double: {{ doubleCount }}</p>
  <p>double: {{ test() }}</p>
  <p>double: {{ test() }}</p>
</template>

- 위에 코드를 실행후 network console로 확인을하면 computed로 선언한 함수는 2번 호출했는데 1번이 console로 찍히고,

함수를 2번 호출시는 2번 console이 찍힘

8. Watch

<script setup lang="ts">
import { ref, watch } from "vue";

const count = ref(0);

watch(count, (newVal, oldVal) => {
  console.log("변경 : ", oldVal, "->", newVal);
})

</script>

<template>
  <button @click="count++"></button>
  <p>{{ count }}</p>
</template>

- count 값이 변경될때 watch가 동작

9. v-for

<script setup lang="ts">
import { ref } from "vue";

const todos = ref([
  { id: 1, text: "Vue 공부" },
  { id: 2, text: "TypeScript 공부" },
]);
</script>

<template>
  <ul>
    <li v-for="todo in todos" :key="todo.id">
      {{ todo.text }}
    </li>
  </ul>
</template>

- key 필수, id 없으면 에러

9-1. computed + v-for

<script setup lang="ts">
import { ref, computed } from "vue";

const todos = ref([
  { id: 1, text: "Vue", done: true },
  { id: 2, text: "TS", done: false },
]);

const doneTodos = computed(() =>
  todos.value.filter(t => t.done)
);
</script>

<template>
  <h3>완료</h3>
  <ul>
    <li v-for="t in doneTodos" :key="t.id">
      {{ t.text }}
    </li>
  </ul>
</template>

- todo 리스트에서 done이 true인 항목만 필터링해서 화면에 뿌림

10. props & emit

Parent.vue

<script setup>
import { ref } from 'vue'
import Child from './Child.vue' // 자식 컴포넌트 불러오기

const myTitle = ref("부모가 주는 선물")
const myCount = ref(0)

// 자식이 보낸 신호를 받았을 때 실행할 함수
const handleIncrease = () => {
  myCount.value++
  console.log("자식의 신호를 받았습니다!")
}
</script>

<template>
  <div style="border: 2px solid #35495e; padding: 20px;">
    <h1> ‍ ‍  여기는 부모 컴포넌트</h1>
    <p>현재 부모의 숫자: {{ myCount }}</p>

    <Child 
      :childTitle="myTitle"
      :count="myCount"
      @increase-count="handleIncrease" 
    />
  </div>
</template>

Child.vue

<script setup>
// 1. Props 정의: 부모에게 받을 데이터 이름표를 만듭니다.
const props = defineProps({
  childTitle: String, // 타입 지정 (String, Number 등)
  count: Number
})

// 2. Emits 정의: 부모에게 보낼 신호 이름을 정합니다.
const emit = defineEmits(['increase-count'])

// 버튼 클릭 시 실행할 함수
const sendSignal = () => {
  // 'increase-count'라는 신호를 부모에게 발사! (필요하면 두 번째 인자로 데이터 전달 가능)
  emit('increase-count')
}
</script>

<template>
  <div style="border: 2px solid #42b883; padding: 10px; margin: 10px;">
    <h3>  여기는 자식 컴포넌트</h3>
    <p>받은 제목: {{ childTitle }}</p>
    <p>받은 숫자: {{ count }}</p>
    
    <button @click="sendSignal">숫자 올려달라고 조르기 (Emit)</button>
  </div>
</template>

TypeScript 기본문법 정리

JaeSung Kim — Wed, 14 Jan 2026 15:43:37 +0900

TypeScript = 자바스크립트에 타입을 붙인 것

쓰는 이유?

- 컴파일 전에 오류를 잡아줌

- 자동완성 + 리팩토링이 미친 듯이 좋아짐

- 협업 / 대규모 프로젝트 필수

- TS는 "문법"이 아니라 " 안전장치"라고 생각하면됨

1. 타입 붙이기

Javascript

let count = 0;
count = "hello"

- 자바스크립트는 런타임 실행 전까지 에러인지 모름

Typescript

let count: number = 0;
count = "hello";

- 타입스크립트는 컴파일시 에러가 발생하여 바로 확인이 가능함

자주 쓰는 기본 타입

let userName: string = "kim"
let age: number = 30;
let isLogin: boolean = true;

Typescript 타입 추론

let price = 100;

- pice 뒤에 : number를 선언하지 않아도 값을 보고 자동으로 타입을 추론함

2. 배열 & 객체

let numbers: number[] = [1, 2, 3];
let users: string[] = ["kim", "lee"];

3. interface / type

interface

interface User {
  id: number;
  email: string;
  isAdmin: boolean;
}

const user: User = {
  id: 1,
  email: "test@test.com",
  isAdmin: false,
};

3-1 interface를 써야하는 상황

DTO / API 응답 구조

interface UserDto {
  id: number;
  email: string;
  name: string;
}

interface ApiResponse<T> {
  success: boolean;
  data: T;
  message?: string;
}

Vue props 정의

interface User {
  id: number;
  email: string;
}

const props = defineProps<{
  user: User;
  isAdmin: boolean;
}>();

implements

interface LoginService {
  login(email: string, password: string): Promise<void>;
}

class AuthService implements LoginService {
  async login(email: string, password: string) {
    // ...
  }
}

확장 (extends)

interface BaseEntity {
  id: number;
  createdAt: string;
}

interface User extends BaseEntity {
  email: string;
}

type

type User = {
  id: number;
  email: string;
  isAdmin: boolean;
};

객체 구조 정의 -> interface

union, 함수 타입 -> type

3-2. type를 써야하는 상황

Union 타입

type Status = "idle" | "loading" | "error";
let status: Status = "loading";

함수 타입 정의

type LoginFn = (email: string, password: string) => Promise<void>;
const login: LoginFn = async (email, password) => {
  // ...
};

조합 타입 (intersection)

type WithToken = {
  accessToken: string;
};

type User = {
  id: number;
  email: string;
};

type AuthedUser = User & WithToken;

제네릭 + 조건 타입

type ApiResult<T> = 
  T extends string ? { value: string } : { value: number };

4. 함수 타입

4-1. 기본 함수

function add(a: number, b: number): number {
  return a + b;
}

4-2. 화살표 함수

const add = (a: number, b: number): number => {
  return a + b;
};

4-3. return 없는 함수

function log(msg: string): void {
  console.log(msg);
}

5. Optional / Nullable

5-1. Optional

interface User {
  id: number;
  name?: string; // 있어도 되고 없어도 됨
}

const u1: User = { id: 1 };
const u2: User = { id: 2, name: "kim" };

- name뒤에 ?를 붙이면 값이 있을수도 있고 없을수도 있다라는 의미임

5-2. null / undefined

let token: string | null = null;

token = "abc";
token = null; // OK

- token 값의 타입이 string이거나 null일수 있다 라는 의미

6. Union 타입

let status: "idle" | "loading" | "success" | "error";
status = "loading";
status = "done";   // 컴파일 에러

- 상태값에 done을 선언하지 않아서 컴파일 에러

7. any

let data: any = 123;
data.toUpperCase(); // 런타임 에러

- any는 어떤타입이든 들어올수 있다라고 설정하는거여서, 사용하면 typescript 쓰는 의미가 없음

- 123을 대문자로 바꾸려니 런타임 에러 발생

8. Unknown

let data: unknown;

if (typeof data === "string") {
  data.toUpperCase();
}

- unknown은 타입을 아직 모른다는걸 typescript에게 솔직하게 말하는 타입

9. any vs unknown

let data: any;

data = 123;
data = "hello";

data.toUpperCase();

- any로 선언을하면 toUpperCase 컴파일은 통과하지만, 런타임에서 에러가 발생함

let data: unknown;

data = 123;
data = "hello";

data.toUpperCase();

- unknown으로 선언하면 toUpperCase 컴파일에서 에러가 발생함, 즉 unknown은 확인하고 쓰라는걸 강제함

ubuntu 서버 최초 세팅

JaeSung Kim — Wed, 14 Jan 2026 13:07:52 +0900

1. 서버 접속

(기본 계정 : ubuntu)

ssh ubuntu@server_ip

2. 시스템업데이트

sudo apt update
sudo apt upgrade -y

3. 타임존 설정(선택이지만 추천)

sudo timedatectl set-timezone Asia/Seoul
timedatectl

4. sudo 권한 일반 사용자 계정 생성

sudo adduser username
sudo usermod -aG sudo username
groups username

4-1. sudo 계정 생성후 정상확인

su - username
sudo ls

-> 비밀번호 묻고 정상실행돠면 성공

5. ROOT 계정 SSH 로그인 비활성화

vim /etc/ssh/sshd_config

PermitRootLogin no # 해당 부분 no로 설정 yes면 root로 바로 로그인 가능한 상태임

(선택) 로그인 유지시간 설정

vim /etc/ssh/sshd_config

ClientAliveInterval 300
ClientAliveCountMax 0

ClientAliveInterval 300 : **300초(5분)**마다 클라이언트 응답 확인

ClientAliveCountMax 0 : 응답 없으면 즉시 세션 종료

결과: 5분 동안 아무 작업 없으면 자동 로그아웃

(선택) 패스워드 오류 허용 횟수 (로그인 실패 제한)

MaxAuthTries 3

패스워드 3번 틀리면 즉시 접속 종료

(선택) 로그인 시도 제한

LoginGraceTime 30

접속 후 30초 안에 인증 못 하면 강제 종료

운영서버에서 가장 많이 쓰는 조합

# 로그인 유지시간
ClientAliveInterval 300
ClientAliveCountMax 0

# 인증 보안
MaxAuthTries 3
LoginGraceTime 30

# root 로그인 차단 (이미 설정했을 가능성 높음)
PermitRootLogin no

- 만약 추가적으로 ssh 파일로만 로그인하고싶으면 아래 옵션을 설정하면 된다. id password 로그인 x

# 패스워드 로그인 허용 여부 (권장: 키 로그인만)
PasswordAuthentication no

5-1 ssh 설정파일 정상적으로 변경되었는지 확인후 restart

sudo sshd -t
sudo systemctl restart ssh

sudo sshd -t : sshd_config에 문법에 오류가 없으면 아무것도 안뜸

sudo systemctl restart ssh : ssh 재시작

6. 방화벽(UFW) 설정

sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp   # 또는 변경 포트
sudo ufw enable
sudo ufw status verbose

6-1. 웹서버 방화벽 설정

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

npm : 'npm' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다. 이름이 정확한지 확인하고 경로가 포함된 경우 경로가 올바른지 검증한 다음 다시 시도하십시오.

JaeSung Kim — Wed, 14 Jan 2026 11:04:16 +0900

컴퓨터를 포맷한후 npm명령어가 먹지않아서 해결방법 포스팅합니다.

npm 명령어를 쓰다가 해당 에러가 발생할경우, cmd창에 아래명령어를 쳐서 확인합니다.

node -v

-> node js가 설치가 안되어있으면 node js를 다운로드합니다.

https://nodejs.org/ko/download

Node.js — Node.js® 다운로드

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

nodejs.org

powershell에서 관리자 권한으로 실행

Get-ExecutionPolicy
Set-ExecutionPolicy RemoteSigned
npm -v

이후에 npm명령어가 정상적으로 동작하는것을 볼수있습니다.

reactJs 확장프로그램 devtool 설치

JaeSung Kim — Mon, 15 Dec 2025 20:16:10 +0900

https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi

React Developer Tools - Chrome 웹 스토어

Adds React debugging tools to the Chrome Developer Tools. Created from revision 3cde211b0c on 10/20/2025.

chromewebstore.google.com

해당 사이트에서 devtools 확장프로그램 추가

App.jsx

import Counter from "@/components/Counter";
import UserCard from "@/components/UserCard";

function App() {
  const user = {
    name: "Jaesung",
    age: 30,
    role: "Frontend Dev",
  };

  return (
    <div style={{ padding: 20 }}>
      <h1>React DevTools Test</h1>

      <Counter initial={5} />
      <Counter />

      <UserCard user={user} />
    </div>
  );
}

export default App;

components/Counter.jsx

import { useState } from "react";

function Counter({ initial = 0 }) {
    const [count, setCount] = useState(initial);

    return (
        <div style={{ border: "1px solid #ccc", padding: 12, marginBottom: 12 }}>
            <h3>Counter</h3>
            <p>count: {count}</p>
            <button onClick={() => setCount((c) => c + 1)}>+</button>
            <button onClick={() => setCount((c) => c - 1)}>-</button>
        </div>
    );
}

export default Counter;

components/UserCard.jsx

function UserCard({ user }) {
    return (
        <div style={{ border: "1px solid #aaa", padding: 12 }}>
            <h3>UserCard</h3>
            <p>name: {user.name}</p>
            <p>age: {user.age}</p>
            <p>role: {user.role}</p>
        </div>
    );
}

export default UserCard;

개발자도구 - Components를 클릭해보면 각 컴포넌트의 props hooks등을 확인할수 있다.

reactJs vsCode eslint 플러그인 설정

JaeSung Kim — Mon, 15 Dec 2025 20:07:42 +0900

플러그인 선택후 eslint 설치

eslint.config.js

import js from '@eslint/js'
import globals from 'globals'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import { defineConfig, globalIgnores } from 'eslint/config'

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{js,jsx}'],
    extends: [
      js.configs.recommended,
      reactHooks.configs.flat.recommended,
      reactRefresh.configs.vite,
    ],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
      parserOptions: {
        ecmaVersion: 'latest',
        ecmaFeatures: { jsx: true },
        sourceType: 'module',
      },
    },
    rules: {
      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
      'react/prop-types': 'off',
    },
  },
])

- rule안에 react/prop-types off로 설정

reactJs 프로젝트 경로 src '@' 설정

JaeSung Kim — Mon, 15 Dec 2025 19:58:53 +0900

vite.config.js

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { resolve } from "path";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": resolve("src"),
    },
  },
});

루트디렉터리에 jsconfig.json 생성

- vite.config.js만 생성하도 컴파일 에러가 나지않지만, Eslint 설정이 빡세게 되어있거나, idel에서 에러가 날경우가 있어서 아래 추가

jsconfig.json

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/*": [
                "src/*"
            ]
        }
    }
}

components/Header.jsx

function Header() {
    return (
        <header>
            <h1>My App Header</h1>
        </header>
    );
}

export default Header;

App.jsx

import Header from "@/components/Header";

function App() {
  return <Header />;
}

export default App;

index.css, app.css는 삭제

서버 시작

npm run dev

react 프로젝트 세팅

JaeSung Kim — Mon, 15 Dec 2025 19:06:48 +0900

노드 설치 및 확인

vsCode를 실행한후 아래 명령어를 실행한다.

node -v
npm -v

- 설치가 되어있지않으면 node js 설치를 한다.

https://nodejs.org/en/

Node.js — Run JavaScript Everywhere

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

nodejs.org

프로젝트 설정

vsCode 터미널에서 프로젝트를 생성할 폴더로 이동후 아래 명령어를 작성한다.

npm create vite@latest 프로젝트명

- React 선택

- Typescript나 JavaScript 사용하고자 하는 언어 선택

- no 선택

-> rolldown-vite는 Rust로 만든 차세대 번들러임 , rollup을 대체하려는 목적

특징은 훨씬 빠른 빌드속도를 가지고 있지만, 아직 실험단계임

- yes 선택

- 프로젝트안에 접속후 코드를 보고 싶으면 해당 경로로 이동후 아래 명령어를 입력한다.

cd 프로젝트경로
code .

[코프링] 13. dotenv 적용해서 spring 프로퍼티 중요정보 .env 파일로 분리하기

JaeSung Kim — Tue, 18 Feb 2025 14:01:42 +0900

spring 프로퍼티를 설정할때 중요정보를 보여주지 않고 따로 환경설정 파일로 분리하고 싶을때가 있을것이다.

그때 dotenv를 적용해서 env파일로 분리하는 방법을 아래 내용에 작성하려고 한다.

build.gradle.kts

//dotenv
implementation ("io.github.cdimascio:java-dotenv:5.2.2")

루트 디렉터리 경로에 .env 파일 생성

.env

SPRING_PROFILES_ACTIVE=local
SECRET=jwt시크릿키

application.yml

spring:
  config:
    import: optional:file:.env[.properties]
  profiles:
    active: ${SPRING_PROFILES_ACTIVE}  # 기본적으로 local 프로파일 사용 (운영에서는 prod로 변경)

jwt:
  expiration_time: 86400000 # 1일
  secret: ${secret}

logging:
  level:
    org.hibernate.SQL: DEBUG  # Hibernate 쿼리 로그 출력

config 아래 import 부분을 추가, .env에 설정한 key를 사용

application.kt

package com.contact.management

import io.github.cdimascio.dotenv.Dotenv
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.data.jpa.repository.config.EnableJpaAuditing


@SpringBootApplication
@EnableJpaAuditing
class ManagementApplication

fun main(args: Array<String>) {
	runApplication<ManagementApplication>(*args)
	val dotenv = Dotenv.load()
	System.out.println("SPRING_PROFILES_ACTIVE: " + dotenv.get("SPRING_PROFILES_ACTIVE"));
	System.out.println("SECRET: " + dotenv.get("SECRET"));
}

test 코드를 만들어도 되지만 간단하게 테스트 하기위해서 applicaiton.kt에 해당 코드 작성

.gitignore

.env*

- 깃에 커밋시 해당 환경설정 파일이 commit되면 안되므로 맨 아래 라인에 .env*을 추가

git ignore에 .env*을 포함해도 .env파일이 git staging에 보일경우 안보이게 하는법

1. .env 파일을 백업하고 프로젝트에 있는 .env 파일을 삭제

2. 아래 명령어 intelij 터미널에 입력

git rm .env --cached
git add .
git commit -m "remove .env file from git"
git push

3. 이후 다시 루트 디렉터리에 백업한 .env파일을 생성한후 git - commit 클릭

env 파일을 변경해도 커밋 changes에 안보이는것을 확인할수 있음

[코프링] 12. Render 무료 호스팅서버에 Spring boot + Kotlin 배포하기

JaeSung Kim — Fri, 14 Feb 2025 16:26:12 +0900

백엔드 무료서버가 몇가지있지만 그중 Render라는 무료 서버 호스팅 사이트에 배포하는 방법 관련 내용입니다.

이전 포스팅한 간단한 프로젝트를 Render에 배포해보겠습니다.

기본적으로 docker hub 회원가입 및 도커가 설치 되어있다는 기준으로 진행하겠습니다.

intelij 프로젝트에서 gradle build 클릭

DockerFile

FROM azul/zulu-openjdk:17-latest
VOLUME /tmp
COPY build/libs/*.jar app.jar
ENTRYPOINT ["java","-jar","/app.jar"]

intelij 터미널에 아래 명령어 순서대로 입력

docker build -t 프로젝트명 .
docker images
docker tag 프로젝트명:latest         도커아이디명/프로젝트명
docker push 도커아이디명/프로젝트명

docker hub 사이트 접속

https://hub.docker.com/

Docker Hub Container Image Library | App Containerization

Increase your reach and adoption on Docker Hub With a Docker Verified Publisher subscription, you'll increase trust, boost discoverability, get exclusive data insights, and much more.

hub.docker.com

- docker hub사이트에 접속해보면 이미지가 push가 잘된것을 볼수 있습니다.

render 사이트에 접속을 합니다.

https://dashboard.render.com/

Cloud Application Hosting for Developers | Render

Render is a unified cloud to build and run all your apps and websites with free SSL, global CDN, private networks and automatic deploys from Git.

dashboard.render.com

Overview - Create New Service

Web Service 클릭

docker hub에 push한 image url을 입력후 Connect

Region은 가장 가까운 Singapore로 설정

Instance Type는 Free로 설정

SPRING_PROFILES_ACTIVE -> prod로 설정이후 Deploy Web Service

배포 완료화면

- 로그를 보면 application.yml prod를 바라보게 설정이 된것을 볼수 있음

배포한 서버의 사용자 조회 api 호출

배포한 서버의 신규 사용자 등록 api 호출

[코프링] 11. Render 무료 호스팅서버 Postgres 데이터베이스 생성

JaeSung Kim — Fri, 14 Feb 2025 15:35:47 +0900

render 사이트에 접속을 합니다.

https://dashboard.render.com/

Cloud Application Hosting for Developers | Render

Render is a unified cloud to build and run all your apps and websites with free SSL, global CDN, private networks and automatic deploys from Git.

dashboard.render.com

1. 메인 - project에 들어가서 Create new proejct를 클릭

2. 프로젝트 이름 작성후 create

3. Overview 클릭 - 오른쪽에 플러스 버튼 클릭 - Create New Service 클릭

4. render는 database를 Postgres를 지원함, 하단에 Postgres 클릭

5. Postgres를 설정하는 화면

Name : postgres 프로젝트 이름 (render에서 사용하는거라 아무거나 적어도 무방)

Databse : 데이터베이스명

User: 사용자명

Region: 지역 선택 (가장 가까운 지역이 싱가폴이라서 고름)

Plan Options: Free로 선택해야함, 그래야 돈 안나감

6. info에 들어가면 생성된 database 정보를 볼수 있음

- External Database Url 옆에 눈모양 클릭후 jdbc url 복사

application.prod.yml

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://호스트명:5432/데이터베이스
    username: 사용자명
    password: 패스워드

  jpa:
    hibernate:
      ddl-auto: create
    show-sql: false
    properties:
      hibernate:
        format_sql: false

- 위에 복사한 url에서 필요한 정보들 yml에 값 설정

application.yml

spring:
  profiles:
    active: prod  # 기본적으로 local 프로파일 사용 (운영에서는 prod로 변경)

jwt:
  expiration_time: 86400000 # 1일
  secret: 시크릿키

logging:
  level:
    org.hibernate.SQL: DEBUG  # Hibernate 쿼리 로그 출력

prod로 설정해보고 application 시작

서버 시작시 로그를 보면 h2가 아니라 postgres가 뜨는것을 볼수 있음

- 이전에 만들었던 사용자 등록 api 호출

- 이전에 만들었던 사용자 조회 api 호출

render 무료호스팅으로 생성한 postgres가 정상적으로 연결된것을 확인할수 있음

[코프링] 10. application.yml 운영, 로컬 분리하기, postgres 설정

JaeSung Kim — Fri, 14 Feb 2025 15:23:10 +0900

기존에 application.yml이 하나였는데 로컬, 운영으로 분리해보겠습니다.

application.yml

spring:
  profiles:
    active: local  # 기본적으로 local 프로파일 사용 (운영에서는 prod로 변경)

jwt:
  expiration_time: 86400000 # 1일
  secret: jwt 시크릿키

application-local.yml

spring:
  h2:
    console:
      enabled: true
      path: /h2-console

  datasource:
    driver-class-name: org.h2.Driver
    url: jdbc:h2:mem:management
    username: sa
    password:

  jpa:
    hibernate:
      ddl-auto: create
    show-sql: true
    database-platform: org.hibernate.dialect.H2Dialect
    properties:
      hibernate:
        format_sql: true

로컬에서는 h2 데이터베이스를 바라보게 설정

application-prod.yml

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://호스트명:5432/데이터베이스명
    username: 사용자명
    password: 패스워드

  jpa:
    hibernate:
      ddl-auto: create
    show-sql: false
    database-platform: org.hibernate.dialect.PostgreSQLDialect
    properties:
      hibernate:
        format_sql: false

logging:
  level:
    org.hibernate.SQL: DEBUG  # Hibernate 쿼리 로그 출력

운영에서는 postgres 데이터베이스를 바라보게 설정

build.gradle

implementation("org.postgresql:postgresql")

posgresql 의존성 추가

jsch를 활용한 spring java에서 ssh command 명령어 실행하기

JaeSung Kim — Fri, 14 Feb 2025 13:23:38 +0900

프로젝트를 하다가 웹에서 버튼클릭시 서버에 설치된 파이썬 파일을 실행해야하는 일이 생겨서, 아래 관련 내용을 정리합니다.

jsch란?

JSCH는 Java에서 SSH 프로토콜을 지원하는 라이브러리로, SFTP, SCP, 포트 포워딩, 터널링 등의 기능을 제공합니다.
Spring에서는 JSCH를 활용하여 원격 서버에 접속하고 파일을 업로드/다운로드하는 등의 작업을 수행할 수 있습니다.

pom.xml

<dependency>
	<groupId>com.jcraft</groupId>
	<artifactId>jsch</artifactId>
	<version>0.1.55</version>
</dependency>

build.gradle

implementation group: 'com.jcraft', name: 'jsch', version: '0.1.55'

Controller

import com.jcraft.jsch.ChannelExec;
import com.jcraft.jsch.JSch;
import com.jcraft.jsch.Session;

...

@ResponseBody
@PostMapping("/sshCommand.json")

    public String sshCommand(@RequestBody Map<String, Object> params) {

        String host = "ssh ip를 입력";  // SSH 서버의 호스트
        int port = port를 입력;
        String user = "로그인 아이디 입력";     // SSH 로그인 사용자
        String password = "로그인 패스워드 입력";  // SSH 로그인 비밀번호
        String command = "df -h";  // ssh command에 입력할 명령어 입력

        Session session = null;
        ChannelExec channel = null;

        try {
            // JSch 객체 생성
            JSch jsch = new JSch();
            session = jsch.getSession(user, host, port);
            session.setPassword(password);

            // SSH 연결 시 호스트 키 확인을 건너뛰기
            session.setConfig("StrictHostKeyChecking", "no");

            // 연결 타임아웃 설정
        	session.connect(10000);

       		//session.connect();



            // 명령어 실행을 위한 채널 열기
            channel = (ChannelExec) session.openChannel("exec");
            channel.setCommand(command);  // 쉘 스크립트 실행 명령 설정
            channel.setErrStream(System.err);

            // 명령어 실행
            InputStream inputStream = channel.getInputStream();
            channel.connect();

            // 실행 결과 읽기
            BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println(line);  // 명령어 실행 결과 출력
            }
            channel.disconnect();
            session.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
        return "ok";  // 명령어 실행 후 홈으로 리다이렉트

    }

- command에는 ssh 명령어 입력창에 입력되는 명령어를 입력합니다.

//예제 home으로 이동한후 test.sh파일을 실행해라
cd /home && ./test.sh

session time out 현상이 있어서 아래 코드를 추가하였습니다.

아래코드는 session time out을 10초까지 기다린다는 의미입니다.

session.connect(10000);

jsch 0.1.55 socket is not established error가 발생할경우

- host, post, user, password를 다시 한번 확인해서 입력을 해야 합니다. 해당 정보가 맞지않거나 방화벽이 허용되지 않아, 웹 소켓 연결이 안될경우 발생하는 에러입니다.

[코프링] 9. Spring Kotlin Jpa Querydsl Security Jwt 적용

JaeSung Kim — Tue, 11 Feb 2025 14:27:42 +0900

jwt secret 생성

https://jwtsecret.com/generate

JwtSecret.com - Generate JWT Secrets Online

Full secret is hidden for security.

jwtsecret.com

- 위사이트 접속후 32자 클릭, Generate 선택후 복사

application.yml

spring:
  # H2 Console 설정
  h2:
    console:
      enabled: true  # H2 Console을 사용할지 여부
      path: /h2-console  # H2 Console의 접근 경로

  # 데이터베이스 설정
  datasource:
    driver-class-name: org.h2.Driver  # H2 드라이버 사용
    url: jdbc:h2:mem:management  # 메모리 내 데이터베이스 (테스트용)
    username: sa  # 접속할 사용자명
    password:  # 비밀번호 (없으면 공백으로 설정)

  # JPA 설정
  jpa:
    hibernate:
      ddl-auto: create  # 테이블 자동 생성 및 업데이트 (설정에 따라 'none', 'update', 'create', 'create-drop' 등이 가능)
    show-sql: true  # SQL 쿼리를 로그에 출력
    database-platform: org.hibernate.dialect.H2Dialect  # H2 데이터베이스용 Hibernate Dialect 설정
    properties:
      hibernate:
        format_sql: true  # SQL을 보기 쉽게 포맷

jwt:
  expiration_time: 86400000 #1일
  secret: 위에 복사한 key를 여기에 넣으세요

jwt, expiration_time, secret 추가

이번 포스팅에 추가, 변경된 파일들

build.gradle.kts

plugins {
	id("org.springframework.boot") version "3.4.2"
	id("io.spring.dependency-management") version "1.1.7"
	kotlin("jvm") version "1.9.25"
	kotlin("plugin.spring") version "1.9.25"
	kotlin("plugin.jpa") version "1.9.25"
	kotlin("kapt") version "1.9.25"
}

group = "com.contact"
version = "0.0.1-SNAPSHOT"

java {
	toolchain {
		languageVersion.set(JavaLanguageVersion.of(17))
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation("org.springframework.boot:spring-boot-starter-data-jpa")
	implementation("org.springframework.boot:spring-boot-starter-web")
	implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
	implementation("org.jetbrains.kotlin:kotlin-reflect")
	implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
	implementation("org.springframework.boot:spring-boot-starter-validation")

	//jwt
	implementation("io.jsonwebtoken:jjwt-api:0.11.5")
	implementation("io.jsonwebtoken:jjwt-impl:0.11.5")
	implementation("io.jsonwebtoken:jjwt-jackson:0.11.5")

	// QueryDSL 의존성 추가
	implementation("com.querydsl:querydsl-jpa:5.1.0:jakarta")
	kapt("com.querydsl:querydsl-apt:5.1.0:jakarta")
	kapt("jakarta.annotation:jakarta.annotation-api")
	kapt("jakarta.persistence:jakarta.persistence-api")

	implementation ("org.springframework.boot:spring-boot-starter-security")

	runtimeOnly("com.h2database:h2")
	testImplementation("org.springframework.boot:spring-boot-starter-test")
}

// Querydsl 설정부 추가 - start
val generated = file("src/main/generated")

// querydsl QClass 파일 생성 위치를 지정
tasks.withType<JavaCompile> {
	options.generatedSourceOutputDirectory.set(generated)
}

// kotlin source set 에 querydsl QClass 위치 추가
sourceSets {
	main {
		kotlin.srcDirs += generated
	}
}

// gradle clean 시에 QClass 디렉토리 삭제
tasks.named("clean") {
	doLast {
		generated.deleteRecursively()
	}
}
kapt {
	generateStubs = true
}

- jwt 부분 추가

각 의존성의 역할

- jjwt-api (io.jsonwebtoken:jjwt-api:0.11.5)
JWT를 생성, 서명, 검증할 수 있는 API를 제공하는 라이브러리
예를 들어, JWT를 생성할 때 Jwts.builder() 같은 기능을 사용할 수 있도록 해줌

- jjwt-impl (io.jsonwebtoken:jjwt-impl:0.11.5)
jjwt-api에서 제공하는 기능의 실제 구현체
API만 추가하면 동작하지 않으므로 반드시 함께 추가

- jjwt-jackson (io.jsonwebtoken:jjwt-jackson:0.11.5)
JSON 파싱을 위해 Jackson을 활용하는 구현체
JWT의 Payload(내용) 을 JSON 형식으로 변환하거나, JSON을 객체로 변환할 때 필요
Jackson을 사용하여 claims(클레임, JWT의 데이터) 정보를 다룰 수 있도록 해줌

User.kt

package com.contact.management.entity

import com.contact.management.audit.BaseEntity
import com.contact.management.dto.SignUpRequest
import com.contact.management.dto.UserUpdateRequest
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.EnumType
import jakarta.persistence.Enumerated
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table
import org.springframework.security.crypto.password.PasswordEncoder

@Entity
@Table(name = "users")
class User (
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long?= null,
    var password: String,
    var name: String,
    var age: Int,
    var email: String,

    @Enumerated(EnumType.STRING)
    @Column(name = "ROLE", nullable = false)
    var role: RoleType // Adding the role field

) : BaseEntity(){
    companion object {
        fun from(request: SignUpRequest, encoder: PasswordEncoder) = User(
            password = encoder.encode(request.password),
            name = request.name,
            age = request.age,
            email = request.email,
            role = RoleType.ROLE_USER
        )
    }

    fun update(request: UserUpdateRequest, encoder: PasswordEncoder){
        this.password = encoder.encode(request.password)
        this.name = request.name
        this.age = request.age
    }

}

- 사용자 권한 role 추가

RoleType.kt

package com.contact.management.entity

enum class RoleType {
    ROLE_USER,  // 일반 사용자
    ROLE_ADMIN  // 관리자
}

- 권한은 간단하게 일반사용자, 관리자

JwtAccessDeniedHandler.kt

package com.contact.management.jwt

import jakarta.servlet.ServletException
import jakarta.servlet.http.HttpServletRequest
import jakarta.servlet.http.HttpServletResponse
import org.springframework.security.access.AccessDeniedException
import org.springframework.security.web.access.AccessDeniedHandler
import org.springframework.stereotype.Component
import java.io.IOException

/**
 *  필요한 권한이 존재하지 않는 경우에 403 Forbidden 에러 return
 */
@Component
class JwtAccessDeniedHandler : AccessDeniedHandler {
    @Throws(IOException::class, ServletException::class)
    override fun handle(request: HttpServletRequest, response: HttpServletResponse, accessDeniedException: AccessDeniedException) {
        response.sendError(HttpServletResponse.SC_FORBIDDEN)
    }
}

- 이 코드는 Spring Security에서 JWT 기반 인증 및 권한 관리를 할 때, 사용자가 필요한 권한이 없을 경우 403 Forbidden 응답을 반환하는 역할을 하는 클래스

동작방식

1. 사용자가 보호된 API 엔드포인트에 요청
2. Spring Security가 사용자의 JWT 토큰을 검증
3. 사용자가 필요한 권한이 없으면 JwtAccessDeniedHandler의 handle() 메서드가 호출됨
4. 클라이언트에게 403 Forbidden 응답 반환

JwtAuthenticationEntryPoint.kt

package com.contact.management.jwt

import jakarta.servlet.ServletException
import jakarta.servlet.http.HttpServletRequest
import jakarta.servlet.http.HttpServletResponse
import org.springframework.security.core.AuthenticationException
import org.springframework.security.web.AuthenticationEntryPoint
import org.springframework.stereotype.Component
import java.io.IOException

/**
 *  유효한 자격증명을 제공하지 않고 접근하려 할때 401 Unauthorized 에러 리턴
 */
@Component
class JwtAuthenticationEntryPoint : AuthenticationEntryPoint {
    @Throws(IOException::class, ServletException::class)
    override fun commence(request: HttpServletRequest, response: HttpServletResponse, authException: AuthenticationException) {
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED)
    }
}

JwtAuthenticationEntryPoint는 로그인하지 않은 사용자가 보호된 API에 접근하면 401 응답을 반환
@Component를 사용하여 Spring Bean으로 등록되며, Security 설정에서 사용됩
AuthenticationEntryPoint 인터페이스를 구현하여 Spring Security에서 인증되지 않은 요청을 처리

JwtAuthFilter.kt

package com.contact.management.jwt

import com.contact.management.security.CustomUserDetailsService
import jakarta.servlet.FilterChain
import jakarta.servlet.ServletException
import jakarta.servlet.http.HttpServletRequest
import jakarta.servlet.http.HttpServletResponse
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.web.filter.OncePerRequestFilter
import java.io.IOException

class JwtAuthFilter(
    private val customUserDetailsService: CustomUserDetailsService,
    private val jwtUtil: JwtUtil
) : OncePerRequestFilter() { // OncePerRequestFilter -> 한 번 실행 보장

    @Throws(ServletException::class, IOException::class)
    override fun doFilterInternal(request: HttpServletRequest, response: HttpServletResponse, filterChain: FilterChain) {
        val authorizationHeader = request.getHeader("Authorization")

        // JWT가 헤더에 있는 경우
        if (authorizationHeader != null && authorizationHeader.startsWith("Bearer ")) {
            val token = authorizationHeader.substring(7)
            // JWT 유효성 검증
            if (jwtUtil.validateToken(token)) {
                val userId = jwtUtil.getUserId(token)

                // 유저와 토큰 일치 시 userDetails 생성
                val userDetails: UserDetails = customUserDetailsService.loadUserByUsername(userId.toString())

                val usernamePasswordAuthenticationToken = UsernamePasswordAuthenticationToken(
                    userDetails, null, userDetails.authorities
                )
                SecurityContextHolder.getContext().authentication = usernamePasswordAuthenticationToken
            }
        }

        filterChain.doFilter(request, response) // 다음 필터로 넘기기
    }
}

1. HTTP 요청의 "Authorization" 헤더에서 JWT를 추출.
2. JWT가 "Bearer "로 시작하는지 확인.
3. JWT의 유효성을 검사.
4. 유효하면 userId를 추출하여 UserDetails 객체를 생성.
5. UsernamePasswordAuthenticationToken을 생성하고 SecurityContextHolder에 저장.
6. 인증이 완료된 요청으로 설정한 후, 다음 필터로 넘김.

요약

JWT 인증을 처리하는 필터로, 요청을 가로채어 JWT를 검증하고 SecurityContext에 인증 정보를 저장하는 역할.
JWT를 헤더에서 추출하고 유효성을 검사한 후, 해당 사용자 정보를 SecurityContextHolder에 저장하여 Spring Security가 인증된 사용자로 인식하도록 설정.
Spring Security 설정에서 필터로 등록해야 동작.

JwtUtil.kt

package com.contact.management.jwt

import com.contact.management.exception.CommonException
import com.contact.management.exception.CommonExceptionCode
import com.contact.management.security.CustomUserDto
import io.jsonwebtoken.*
import io.jsonwebtoken.io.Decoders
import io.jsonwebtoken.security.Keys
import org.slf4j.Logger
import org.slf4j.LoggerFactory
import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Component
import java.security.Key
import java.time.ZonedDateTime
import java.util.*

/**
 * [JWT 관련 메서드를 제공하는 클래스]
 */
@Component
class JwtUtil(
    @Value("\${jwt.secret}") secretKey: String,
    @Value("\${jwt.expiration_time}") private val accessTokenExpTime: Long
) {
    private val log: Logger = LoggerFactory.getLogger(JwtUtil::class.java)
    private val key: Key = Keys.hmacShaKeyFor(Decoders.BASE64.decode(secretKey))

    /**
     * Access Token 생성
     * @param user
     * @return Access Token String
     */
    fun createAccessToken(user: CustomUserDto): String {
        return createToken(user, accessTokenExpTime)
    }

    /**
     * JWT 생성
     * @param user
     * @param expireTime
     * @return JWT String
     */
    private fun createToken(user: CustomUserDto, expireTime: Long): String {
        val claims: Claims = Jwts.claims().apply {
            put("id", user.id)
            put("email", user.email)
            put("authorities", user.role)
        }

        val now = ZonedDateTime.now()
        val tokenValidity = now.plusSeconds(expireTime)

        return Jwts.builder()
            .setClaims(claims)
            .setIssuedAt(Date.from(now.toInstant()))
            .setExpiration(Date.from(tokenValidity.toInstant()))
            .signWith(key, SignatureAlgorithm.HS256)
            .compact()
    }

    /**
     * Token에서 User ID 추출
     * @param token
     * @return User ID
     */
    fun getUserId(token: String): Long {
        val id = parseClaims(token)["id", Integer::class.java]  // Read the claim as an Integer
        return id?.toLong() ?: throw CommonException(CommonExceptionCode.INVALID_AUTH_TOKEN) // Convert Integer to Long
    }

    /**
     * JWT 검증
     * @param token
     * @return IsValidate
     */
    fun validateToken(token: String): Boolean {
        return try {
            Jwts.parserBuilder().setSigningKey(key).build().parseClaimsJws(token)
            true
        } catch (e: io.jsonwebtoken.security.SecurityException) {
            log.info("Invalid JWT Token", e)
            false
        } catch (e: MalformedJwtException) {
            log.info("Invalid JWT Token", e)
            false
        } catch (e: ExpiredJwtException) {
            log.info("Expired JWT Token", e)
            false
        } catch (e: UnsupportedJwtException) {
            log.info("Unsupported JWT Token", e)
            false
        } catch (e: IllegalArgumentException) {
            log.info("JWT claims string is empty.", e)
            false
        }
    }

    /**
     * JWT Claims 추출
     * @param accessToken
     * @return JWT Claims
     */
    fun parseClaims(accessToken: String): Claims {
        return try {
            Jwts.parserBuilder().setSigningKey(key).build().parseClaimsJws(accessToken).body
        } catch (e: ExpiredJwtException) {
            e.claims
        }
    }
}

이 코드는 JWT(JSON Web Token) 관련 유틸리티 클래스로,
JWT 생성
JWT 검증
JWT에서 사용자 정보 추출
하는 기능을 제공
Spring Security 기반으로 JWT 인증을 처리하는 핵심 로직

JWT 인증 흐름

클라이언트가 로그인 → JwtUtil.createAccessToken(user) 실행 → JWT 생성 후 반환.
클라이언트가 JWT를 Authorization 헤더에 담아 요청.
JwtAuthFilter가 요청을 가로채 JwtUtil.validateToken(token) 실행 → JWT가 유효하면 SecurityContext에 인증 정보 저장.
Spring Security는 SecurityContext에서 인증된 사용자 정보를 가져와 요청을 처리.

CustomUserDetails.kt

package com.contact.management.security

import org.springframework.security.core.GrantedAuthority
import org.springframework.security.core.authority.SimpleGrantedAuthority
import org.springframework.security.core.userdetails.UserDetails

class CustomUserDetails(
    private val member: CustomUserDto // Change from CustomUserInfoDto to CustomUserDto
) : UserDetails {

    override fun getAuthorities(): Collection<GrantedAuthority> {
        // RoleType에 따라 권한 리스트를 생성
        val roles = listOf(member.role).map { role -> SimpleGrantedAuthority(role.name) }
        return roles
    }

    override fun getPassword(): String = member.password // Ensure the DTO has password if needed

    override fun getUsername(): String = member.id.toString() // or member.name if that's preferred

    override fun isAccountNonExpired(): Boolean = true

    override fun isAccountNonLocked(): Boolean = true

    override fun isCredentialsNonExpired(): Boolean = true

    override fun isEnabled(): Boolean = true
}

CustomUserDetails 클래스는 사용자 정보를 Spring Security에 맞는 형태로 변환하여 제공
이를 통해 Spring Security의 인증(Authentication) 및 인가(Authorization) 절차가 정상적으로 처리

CustomUserDetailsService.kt

package com.contact.management.security

import com.contact.management.entity.User
import com.contact.management.repository.UserRepository
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.core.userdetails.UsernameNotFoundException
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
@Transactional(readOnly = true)
class CustomUserDetailsService(
    private val userRepository: UserRepository
) : UserDetailsService {

    override fun loadUserByUsername(id: String): UserDetails {
        val user: User = userRepository.findById(id.toLong())
            .orElseThrow { UsernameNotFoundException("해당하는 유저가 없습니다.") }

        // entity -> dto 변환
        val dto = CustomUserDto.from(user)

        return CustomUserDetails(dto)
    }
}

주요기능

DB에서 사용자 조회 (UserRepository 이용)
찾은 User 엔티티를 CustomUserDto로 변환
Spring Security의 UserDetails 객체(CustomUserDetails)로 반환

CustomUserDto.kt

package com.contact.management.security

//내부에서 사용하는 dto
import com.contact.management.entity.RoleType
import com.contact.management.entity.User

data class CustomUserDto(
    val id: Long?= null,
    var password: String,
    val name: String,
    val age: Int,
    val email: String,
    val role: RoleType
) {
    companion object {
        // Factory method for creating CustomUserDto from User entity
        fun from(user: User): CustomUserDto {
            return CustomUserDto(
                id = user.id,
                password = user.password,
                name = user.name,
                age = user.age,
                email = user.email,
                role = user.role
            )
        }
    }
}

SecurityConfig.kt

package com.contact.management.security

import com.contact.management.jwt.JwtAccessDeniedHandler
import com.contact.management.jwt.JwtAuthFilter
import com.contact.management.jwt.JwtAuthenticationEntryPoint
import com.contact.management.jwt.JwtUtil
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
import org.springframework.boot.autoconfigure.security.servlet.PathRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.method.configuration.EnableGlobalMethodSecurity
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
import org.springframework.security.config.annotation.web.configuration.WebSecurityCustomizer
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.security.web.SecurityFilterChain
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter

@Configuration
@EnableWebSecurity
//@EnableMethodSecurity(securedEnabled = true, jsr250Enabled = true, prePostEnabled = true)         //PreAuthorize 사용하기위한
class SecurityConfig(
    private val customUserDetailsService: CustomUserDetailsService,
    private val jwtUtil: JwtUtil,
    private val accessDeniedHandler: JwtAccessDeniedHandler,
    private val authenticationEntryPoint: JwtAuthenticationEntryPoint
) {

    companion object {
        private val AUTH_WHITELIST = arrayOf(
            "/api/users/**", // Allows unrestricted access to this endpoint
        )
    }

    @Bean
    @ConditionalOnProperty(name = ["spring.h2.console.enabled"], havingValue = "true")
    fun configureH2ConsoleEnable(): WebSecurityCustomizer {
        return WebSecurityCustomizer { web -> web.ignoring().requestMatchers(PathRequest.toH2Console()) }
    }

    @Bean
    fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http
            .csrf { it.disable() }
            .cors { }
            .sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) }
            .authorizeHttpRequests {
                it
                    .requestMatchers(*AUTH_WHITELIST).permitAll()
                    .requestMatchers("/api/test/users/**").hasAuthority("ROLE_USER")   //USER 역할만 접근 허용
                    .requestMatchers("/api/test/admin/**").hasAuthority("ROLE_ADMIN")  // ADMIN 역할만 접근 허용
                    .anyRequest().authenticated()
            }
            .exceptionHandling {
                it.authenticationEntryPoint(authenticationEntryPoint)
                    .accessDeniedHandler(accessDeniedHandler)
            }
            .addFilterBefore(JwtAuthFilter(customUserDetailsService, jwtUtil), UsernamePasswordAuthenticationFilter::class.java)
            .formLogin { it.disable() }
            .httpBasic { it.disable() }
        return http.build()
    }

    @Bean
    fun passwordEncoder(): PasswordEncoder = BCryptPasswordEncoder()
}

주요기능

JWT 기반 인증 적용 (JwtAuthFilter 추가)
세션 사용 안 함 (STATELESS 설정)
CSRF 및 기본 로그인 기능 비활성화
예외 처리 설정 (JwtAccessDeniedHandler, JwtAuthenticationEntryPoint)
H2 콘솔 보안 설정 (ConditionalOnProperty)
비밀번호 암호화 (BCryptPasswordEncoder)

주요설정

CSRF 보호 비활성화 (csrf { it.disable() })
JWT 기반 인증에서는 CSRF 토큰이 필요하지 않음.
CORS 설정 (cors { })
기본 CORS 설정 (필요시 CorsFilter 추가 가능).
세션 미사용 (SessionCreationPolicy.STATELESS)
JWT 기반 인증 방식에서는 세션을 사용하지 않음.
기본 로그인 방식 비활성화
formLogin { it.disable() } → 기본 폼 로그인 X.
httpBasic { it.disable() } → HTTP Basic 인증 X.

Spring Security 인증흐름

1. 사용자 로그인 요청
/api/users/login 엔드포인트로 로그인 요청 (AUTH_WHITELIST에 포함됨).
2. 로그인 성공 시 JWT 토큰 발급.
요청 헤더에 JWT 포함
클라이언트는 이후 요청마다 Authorization: Bearer <JWT> 헤더를 포함하여 보냄.
3. JwtAuthFilter에서 JWT 검증
JWT가 유효하면 SecurityContext에 사용자 정보 저장.
4. 요청 인증 처리
SecurityFilterChain에서 설정한 대로 인증이 필요한 요청인지 확인 후 처리.

UserController.kt

package com.contact.management.controller

import com.contact.management.dto.LoginRequest
import com.contact.management.dto.SignUpRequest
import com.contact.management.dto.UserResponse
import com.contact.management.dto.UserUpdateRequest
import com.contact.management.service.QuerydslUserService
import com.contact.management.service.UserService
import jakarta.validation.Valid
import org.springframework.data.domain.Page
import org.springframework.data.domain.Pageable
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.web.bind.annotation.*
import kotlin.math.log

@RestController
@RequestMapping("/api/users")
class UserController(
     private val userService: UserService
    ,private val querydslUserService: QuerydslUserService
) {

    @GetMapping
    fun getUsers(): ResponseEntity<List<UserResponse>> {
        val users = userService.getAllUsers()
        return ResponseEntity.ok(users)
    }

    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): ResponseEntity<UserResponse> {
        return ResponseEntity.ok(userService.getUserById(id))
    }

    @PostMapping
    fun createUser(@Valid @RequestBody request: SignUpRequest): ResponseEntity<UserResponse> {
        val createdUser = userService.createdUser(request)
        return ResponseEntity
            .status(HttpStatus.CREATED) // 201 Created
            .header(HttpHeaders.LOCATION, "/api/users/${createdUser.id}") // 생성된 리소스의 URI 반환
            .body(createdUser)
    }

    @PutMapping("/{id}")
    fun updateUser(@PathVariable id: Long,@Valid @RequestBody request: UserUpdateRequest): ResponseEntity<UserResponse> {
        val updatedUser = userService.updateUser(id, request)
        return ResponseEntity.ok(updatedUser)
    }

    @DeleteMapping("/{id}")
    fun deleteUser(@PathVariable id: Long): ResponseEntity<Void> {
        userService.deleteUser(id)
        return ResponseEntity.noContent().build() // 204 No Content
    }

    @GetMapping("/paged")
    fun getUsersWithPaging(pageable: Pageable, @RequestParam searchVal: String?): Page<UserResponse> {
        // 페이징된 사용자 목록 반환
        return querydslUserService.getUsersWithPaging(pageable, searchVal)
    }

    @PostMapping("/login")
    fun login(@Valid @RequestBody loginRequest: LoginRequest): ResponseEntity<String>{
        val token = userService.login(loginRequest)
        return ResponseEntity.ok(token)
    }
}

/login 추가

UserService.kt

package com.contact.management.service

import com.contact.management.dto.LoginRequest
import com.contact.management.dto.SignUpRequest
import com.contact.management.dto.UserResponse
import com.contact.management.dto.UserUpdateRequest
import com.contact.management.entity.QUser
import com.contact.management.entity.User
import com.contact.management.exception.CommonException
import com.contact.management.exception.CommonExceptionCode.EMAIL_ALREADY_EXISTS
import com.contact.management.exception.CommonExceptionCode.USER_NOT_FOUND
import com.contact.management.jwt.JwtUtil
import com.contact.management.repository.UserRepository
import com.contact.management.security.CustomUserDto
import com.querydsl.jpa.impl.JPAQueryFactory
import org.springframework.data.domain.Page
import org.springframework.data.domain.PageImpl
import org.springframework.data.domain.Pageable
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
@Transactional
class UserService(
     private val userRepository: UserRepository
    ,private val queryFactory: JPAQueryFactory
    ,private val encoder: PasswordEncoder
    ,private val jwtUtil: JwtUtil
) {

    @Transactional(readOnly = true)
    fun getAllUsers() : List<UserResponse> {
        return userRepository.findAll().map { UserResponse.from(it) }
    }

    @Transactional(readOnly = true)
    fun getUserById(id: Long): UserResponse {
        val user = userRepository.findById(id).orElseThrow{ CommonException(USER_NOT_FOUND) }
        return UserResponse.from(user)
    }

    fun createdUser(request: SignUpRequest): UserResponse {
        userRepository.findByEmail(request.email)?.let {
            throw CommonException(EMAIL_ALREADY_EXISTS)
        }

        val user = userRepository.save(User.from(request, encoder))
        return UserResponse.from(user)
    }

    // 사용자 업데이트
    fun updateUser(id: Long, request: UserUpdateRequest): UserResponse{
        val user = userRepository.findById(id).orElseThrow{ CommonException(USER_NOT_FOUND) }

        user.update(request, encoder)

        return UserResponse.from(user)
    }

    fun deleteUser(id: Long){
        if(!userRepository.existsById(id)){
            throw CommonException(USER_NOT_FOUND)
        }
        userRepository.deleteById(id)
    }

    @Transactional(readOnly = true)
    fun getUsersWithPaging(pageable: Pageable): Page<UserResponse> {
        val qUser = QUser.user

        // JPAQueryFactory를 사용하여 쿼리 작성
        val query = queryFactory
            .selectFrom(qUser)
            .orderBy(qUser.id.asc()) // ID 기준으로 오름차순 정렬 (필요에 따라 변경 가능)

        // 실제 데이터 조회
        val users = query
            .offset(pageable.offset) // 페이지의 시작 인덱스
            .limit(pageable.pageSize.toLong()) // 페이지 크기
            .fetch() // 결과 가져오기

        // 총 개수를 구하는 쿼리 작성 (countQuery)
        val countQuery = queryFactory
            .select(qUser.count()) // 총 개수 계산
            .from(qUser)
        val total = countQuery.fetchOne() ?: 0L // fetchOne()으로 단일 값 가져오기

        // Page 객체로 반환
        val userDtos = users.map { UserResponse.from(it) }
        return PageImpl(userDtos, pageable, total)
    }

    @Transactional(readOnly = true)
    fun login(request: LoginRequest): String {
        val email = request.email
        val password = request.password
        val user = userRepository.findByEmail(email) ?: throw CommonException(USER_NOT_FOUND)

        // 암호화된 password를 디코딩한 값과 입력한 패스워드 값이 다르면 예외를 던짐
        if (!encoder.matches(password, user.password)) {
            throw CommonException(USER_NOT_FOUND)
        }

        val info = CustomUserDto.from(user)
        return jwtUtil.createAccessToken(info)
    }

}

로그인시 해당 계정이 존재하지않는경우 USER_NOT_FOUND

암호화된 패스워드를 디코딩한 값과 입력한 패스워드값이 다를경우 USER_NOT_FOUND ERROR

통과시 jwt access token 생성 후 return

결과

사용자 등록

사용자 로그인

token값 return

TestController.kt

package com.contact.management.controller

import com.contact.management.dto.LoginRequest
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RestController

@RestController
class TestController {

    @GetMapping("/test")
    fun test(): String{
        return "ok";
    }

    @PostMapping("/api/test/user")
//    @PreAuthorize("hasRole('ROLE_USER')")
    fun userTest(@RequestBody loginRequest: LoginRequest): LoginRequest {
        return loginRequest
    }

    @PostMapping("/api/test/admin")
//    @PreAuthorize("hasRole('ROLE_ADMIN')")
    fun adminTest(@RequestBody loginRequest: LoginRequest): LoginRequest {
        return loginRequest
    }

}

users 계정으로 /api/test/user 호출

user계정으로 /api/test/admin 호출

user 계정으로 admin api를 호출하였을때, 403이 나와야할것 같은데, 401이 나옴 원인 파악중..

[코프링] 8. Companion Object - 팩토리 메서드 패턴 설정

JaeSung Kim — Mon, 10 Feb 2025 11:09:03 +0900

팩토리 메서드 패턴이란?
팩토리 메서드 패턴은 객체 생성을 캡슐화하여, 객체 생성 로직을 별도의 메서드로 분리하는 디자인 패턴 이를 통해 객체 생성 방식을 통제하고, 생성 과정이 변경되더라도 클라이언트 코드의 수정을 최소화

기존방식 (팩토리 메서드 미적용)

val user = User(
    password = encoder.encode(signUpRequest.password),
    name = signUpRequest.name,
    age = signUpRequest.age,
    email = signUpRequest.email
)

- 기존 방식의코드는 api 메소드 마다 user 값을 setting 해주려면 하나하나 전부 setting 해줘야하는 단점이 있다.

변경된 방식 (팩토리 메서드 적용)

val user = User.from(signUpRequest, encoder)

- 팩토리 메서드를 적용하면 api 메서드 마다 .from을 호출하는식으로 캡슐화를 해서, 코드도 더 간결해 보인다.

- 팩토리 메서드 역할

from 메서드는 SignUpRequest DTO와 PasswordEncoder를 받아, User 객체를 생성하는 역할
비밀번호는 평문으로 저장하면 보안상 문제가 있기 때문에, encoder.encode(request.password)를 통해 암호화된 비밀번호를 저장하는 로직을 캡슐화
이를 통해 User 객체를 직접 생성하지 않고, from 메서드를 통해 일관된 방식으로 안전하게 객체를 생성

- 팩토리 메서드 패턴의 장점 적용

객체 생성을 캡슐화
User 객체의 생성 로직이 한 곳(from)에 모여 있어, 객체 생성을 단순화하고 코드 중복을 방지
유지보수성 증가
만약 User 생성 방식이 바뀌어도 from 메서드만 수정하면 되므로, 다른 코드에 영향을 주지 않습니다.
의미 있는 생성 메서드 제공
from(request, encoder)는 User 객체를 생성하는 의미를 직관적으로 전달
생성자를 직접 호출하는 것보다 가독성이 좋아지고, 명확한 객체 생성 방법을 제공

그러면 이전에 작성한 코드에서 팩토리 메서드 패턴을 적용해 보자

User.kt

package com.contact.management.entity

import com.contact.management.audit.BaseEntity
import com.contact.management.dto.SignUpRequest
import com.contact.management.dto.UserUpdateRequest
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table
import org.springframework.security.crypto.password.PasswordEncoder

@Entity
@Table(name = "users")
class User (
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long?= null,
    var password: String,
    var name: String,
    var age: Int,
    var email: String
) : BaseEntity(){
    companion object {
        fun from(request: SignUpRequest, encoder: PasswordEncoder) = User(
            password = encoder.encode(request.password),
            name = request.name,
            age = request.age,
            email = request.email
        )
    }

    fun update(request: UserUpdateRequest, encoder: PasswordEncoder){
        this.password = encoder.encode(request.password)
        this.name = request.name
        this.age = request.age
    }

}

UserController.kt

package com.contact.management.controller

import com.contact.management.dto.SignUpRequest
import com.contact.management.dto.UserResponse
import com.contact.management.dto.UserUpdateRequest
import com.contact.management.service.QuerydslUserService
import com.contact.management.service.UserService
import jakarta.validation.Valid
import org.springframework.data.domain.Page
import org.springframework.data.domain.Pageable
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/users")
class UserController(
     private val userService: UserService
    ,private val querydslUserService: QuerydslUserService
) {

    @GetMapping
    fun getUsers(): ResponseEntity<List<UserResponse>> {
        val users = userService.getAllUsers()
        return ResponseEntity.ok(users)
    }

    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): ResponseEntity<UserResponse> {
        return ResponseEntity.ok(userService.getUserById(id))
    }

    @PostMapping
    fun createUser(@Valid @RequestBody request: SignUpRequest): ResponseEntity<UserResponse> {
        val createdUser = userService.createdUser(request)
        return ResponseEntity
            .status(HttpStatus.CREATED) // 201 Created
            .header(HttpHeaders.LOCATION, "/api/users/${createdUser.id}") // 생성된 리소스의 URI 반환
            .body(createdUser)
    }

    @PutMapping("/{id}")
    fun updateUser(@PathVariable id: Long,@Valid @RequestBody request: UserUpdateRequest): ResponseEntity<UserResponse> {
        val updatedUser = userService.updateUser(id, request)
        return ResponseEntity.ok(updatedUser)
    }

    @DeleteMapping("/{id}")
    fun deleteUser(@PathVariable id: Long): ResponseEntity<Void> {
        userService.deleteUser(id)
        return ResponseEntity.noContent().build() // 204 No Content
    }

    @GetMapping("/paged")
    fun getUsersWithPaging(pageable: Pageable, @RequestParam searchVal: String?): Page<UserResponse> {
        // 페이징된 사용자 목록 반환
        return querydslUserService.getUsersWithPaging(pageable, searchVal)
    }
}

- 기존에 dto를 UserDto 하나만 사용해서 실제 api를 만들때는 그렇게 하지 않기때문에 나눴습니다.

UserDto -> SignUpRequest, UserUpdateRequest

SignUpRequest -> 사용자 등록할때 사용하는 요청 파라미터

UserUpdateRequest -> 사용자 수정할때 사용하는 요청 파라미터

UserResponse 추가

SignUpRequest.kt

package com.contact.management.dto

import jakarta.validation.constraints.Email
import jakarta.validation.constraints.Max
import jakarta.validation.constraints.Min
import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.Pattern
import jakarta.validation.constraints.Size

data class SignUpRequest(
    val id: Long?= null,

    @field:Size(min = 8, message = "비밀번호는 최소 8자 이상이어야 합니다.")
    @field:Pattern(
        regexp = "^(?=.*[0-9])(?=.*[!@#\$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>/?]).{8,}\$",
        message = "비밀번호는 최소 1개 이상의 숫자와 특수문자를 포함해야 합니다."
    )
    val password:String,

    @field:NotBlank(message = "이름은 필수 입력 항목입니다.")
    @field:Size(min = 2, max = 50, message = "이름은 2~50자 사이여야 합니다.")
    val name: String,

    @field:Min(value = 0, message = "나이는 0 이상이어야 합니다.")
    @field:Max(value = 150, message = "나이는 150 이하여야 합니다.")
    val age: Int,

    @field:NotBlank(message = "이메일은 필수 입력 항목입니다.")
    @field:Email(message = "올바른 이메일 형식을 입력하세요.")
    val email: String
)

- validation을 추가

UserUpdate.kt

package com.contact.management.dto

import jakarta.validation.constraints.*

data class UserUpdateRequest(

    @field:Size(min = 8, message = "비밀번호는 최소 8자 이상이어야 합니다.")
    @field:Pattern(
        regexp = "^(?=.*[0-9])(?=.*[!@#\$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>/?]).{8,}\$",
        message = "비밀번호는 최소 1개 이상의 숫자와 특수문자를 포함해야 합니다."
    )
    val password:String,

    @field:NotBlank(message = "이름은 필수 입력 항목입니다.")
    @field:Size(min = 2, max = 50, message = "이름은 2~50자 사이여야 합니다.")
    val name: String,

    @field:Min(value = 0, message = "나이는 0 이상이어야 합니다.")
    @field:Max(value = 150, message = "나이는 150 이하여야 합니다.")
    val age: Int,

    @field:NotBlank(message = "이메일은 필수 입력 항목입니다.")
    @field:Email(message = "올바른 이메일 형식을 입력하세요.")
    val email: String
)

- validation을 추가

UserResponse.kt

package com.contact.management.dto

import com.contact.management.entity.User
import jakarta.validation.constraints.Email
import jakarta.validation.constraints.Size
import org.springframework.security.crypto.password.PasswordEncoder

data class UserResponse(
    val id: Long?= null,
    val name: String,
    val age: Int,
    val email: String
){
    companion object {
        fun from(user: User) = UserResponse(
            id = user.id,
            name = user.name,
            age = user.age,
            email = user.email
        )
    }
}

- UserResponse 추가

UserService.kt

package com.contact.management.service

import com.contact.management.dto.SignUpRequest
import com.contact.management.dto.UserResponse
import com.contact.management.dto.UserUpdateRequest
import com.contact.management.entity.QUser
import com.contact.management.entity.User
import com.contact.management.exception.CommonException
import com.contact.management.exception.CommonExceptionCode.EMAIL_ALREADY_EXISTS
import com.contact.management.exception.CommonExceptionCode.USER_NOT_FOUND
import com.contact.management.repository.UserRepository
import com.querydsl.jpa.impl.JPAQueryFactory
import org.springframework.data.domain.Page
import org.springframework.data.domain.PageImpl
import org.springframework.data.domain.Pageable
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
@Transactional
class UserService(
     private val userRepository: UserRepository
    ,private val queryFactory: JPAQueryFactory
    ,private val encoder: PasswordEncoder
) {

    @Transactional(readOnly = true)
    fun getAllUsers() : List<UserResponse> {
        return userRepository.findAll().map { UserResponse.from(it) }
    }

    @Transactional(readOnly = true)
    fun getUserById(id: Long): UserResponse {
        val user = userRepository.findById(id).orElseThrow{ CommonException(USER_NOT_FOUND) }
        return UserResponse.from(user)
    }

    fun createdUser(request: SignUpRequest): UserResponse {
        userRepository.findByEmail(request.email)?.let {
            throw CommonException(EMAIL_ALREADY_EXISTS)
        }

        val user = userRepository.save(User.from(request, encoder))
        return UserResponse.from(user)
    }

    // 사용자 업데이트
    fun updateUser(id: Long, request: UserUpdateRequest): UserResponse{
        val user = userRepository.findById(id).orElseThrow{ CommonException(USER_NOT_FOUND) }

        user.update(request, encoder)

        return UserResponse.from(user)
    }

    fun deleteUser(id: Long){
        if(!userRepository.existsById(id)){
            throw CommonException(USER_NOT_FOUND)
        }
        userRepository.deleteById(id)
    }

    @Transactional(readOnly = true)
    fun getUsersWithPaging(pageable: Pageable): Page<UserResponse> {
        val qUser = QUser.user

        // JPAQueryFactory를 사용하여 쿼리 작성
        val query = queryFactory
            .selectFrom(qUser)
            .orderBy(qUser.id.asc()) // ID 기준으로 오름차순 정렬 (필요에 따라 변경 가능)

        // 실제 데이터 조회
        val users = query
            .offset(pageable.offset) // 페이지의 시작 인덱스
            .limit(pageable.pageSize.toLong()) // 페이지 크기
            .fetch() // 결과 가져오기

        // 총 개수를 구하는 쿼리 작성 (countQuery)
        val countQuery = queryFactory
            .select(qUser.count()) // 총 개수 계산
            .from(qUser)
        val total = countQuery.fetchOne() ?: 0L // fetchOne()으로 단일 값 가져오기

        // Page 객체로 반환
        val userDtos = users.map { UserResponse.from(it) }
        return PageImpl(userDtos, pageable, total)
    }

}

User.kt에서 작성한 from, update를 호출하게 service단에서 변경

passwordEncoder는 아직 Bean으로 등록을 하지않아서, 다음 포스팅에 security 적용하면서 작성할 예정입니다.

[코프링] Kotlin Spring Boot Api에서 파라미터 not null, null 체크

JaeSung Kim — Mon, 10 Feb 2025 10:33:24 +0900

package com.example.basic_kotlin_2025.controller.response

import com.example.basic_kotlin_2025.model.http.UserRequest
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.DeleteMapping
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.PutMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api/response")
class ResponseApiController {

    // 1. get 4xx
    // http://localhost:8080/api/response
    @GetMapping("/get-mapping")
    fun getMapping(@RequestParam age: Int?): ResponseEntity<String> {   //age 값이 없을수도 있다.

        // 1. age > 20 -> 400 error
        if(age == null){
            return ResponseEntity.status(400).body("age 값이 누락되었습니다.")
        }

        // 2. age < 20 -> 400 error
        if(age < 20){
            return ResponseEntity.status(400).body("age 값은 20보다 커야 합니다.")
        }
     
        //return ResponseEntity.ok("OK")
    }
}

- 만약 이러한 스타일의 api를 kotlin스럽게 코딩을 한다면 아래 코드 처럼 변경할수 있다.

package com.example.basic_kotlin_2025.controller.response

import com.example.basic_kotlin_2025.model.http.UserRequest
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.DeleteMapping
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.PutMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api/response")
class ResponseApiController {

    // 1. get 4xx
    // http://localhost:8080/api/response
    @GetMapping("/get-mapping")
    fun getMapping(@RequestParam age: Int?): ResponseEntity<String> {   //age 값이 없을수도 있다.

       return age?.let{

            if(age < 20){
                return ResponseEntity.status(400).body("age 값은 20보다 커야 합니다.")
            }

           ResponseEntity.ok("OK")
            // age not null
        }?: kotlin.run {
            //age is null
            return ResponseEntity.status(400).body("age 값이 누락되었습니다.")
        }
        
        //return ResponseEntity.ok("OK")
    }

}

return age?.let{

            if(age < 20){
                return ResponseEntity.status(400).body("age 값은 20보다 커야 합니다.")
            }

           ResponseEntity.ok("OK")
            // age not null
        }

- 이 코드는 age값이 null이 아닐경우 타는 부분

?: kotlin.run {
            //age is null
            return ResponseEntity.status(400).body("age 값이 누락되었습니다.")
        }

- 이 코드는 age값이 null일 경우 타는 부분

[코프링] 7. Spring Kotlin Jpa Querydsl BooleanExpression 동적쿼리 적용

JaeSung Kim — Fri, 7 Feb 2025 17:28:14 +0900

UserController.kt

@GetMapping("/paged")
fun getUsersWithPaging(pageable: Pageable, @RequestParam searchVal: String?): Page<UserDto> {
    // 페이징된 사용자 목록 반환
    return querydslUserService.getUsersWithPaging(pageable, searchVal)
}

-> 지난번에 추가한 controller 해당 api에 @RequestParam으로 검색어를 받는부분을 추가

QuerydslUserService.kt

package com.contact.management.service

import com.contact.management.dto.UserDto
import com.contact.management.entity.QUser
import com.contact.management.repository.UserRepository
import com.querydsl.core.types.dsl.BooleanExpression
import com.querydsl.jpa.impl.JPAQueryFactory
import org.springframework.data.domain.Page
import org.springframework.data.domain.PageImpl
import org.springframework.data.domain.Pageable
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
@Transactional
class QuerydslUserService(
    private val queryFactory: JPAQueryFactory
) {

    @Transactional(readOnly = true)
    fun getUsersWithPaging(pageable: Pageable, searchVal: String?): Page<UserDto> {
        val qUser = QUser.user
        var predicate: BooleanExpression = qUser.isNotNull

        searchVal?.let {
            predicate = predicate.and(qUser.name.containsIgnoreCase(searchVal))
        }

        // JPAQueryFactory를 사용하여 쿼리 작성
        val query = queryFactory
            .selectFrom(qUser)
            .where(predicate)
            .orderBy(qUser.id.asc()) // ID 기준으로 오름차순 정렬 (필요에 따라 변경 가능)

        // 실제 데이터 조회
        val users = query
            .offset(pageable.offset) // 페이지의 시작 인덱스
            .limit(pageable.pageSize.toLong()) // 페이지 크기
            .fetch() // 결과 가져오기

        // 총 개수를 구하는 쿼리 작성 (countQuery)
        val countQuery = queryFactory
            .select(qUser.count()) // 총 개수 계산
            .from(qUser)
            .where(predicate)
        val total = countQuery.fetchOne() ?: 0L // fetchOne()으로 단일 값 가져오기

        // Page 객체로 반환
        val userDtos = users.map { UserDto(it.id, it.name, it.email) }
        return PageImpl(userDtos, pageable, total)
    }

}

searchVal 값을 null 허용을 하고 searchVal?.let을 선언해서 검색어가 "" 이거나 null일때는 통과, 그 외는 containsIgnoreCase를 사용해서 이름 like 검색을 하게 추가 하였음

결과

searchVal null인경우

-> 모든 항목이 나옴

searchVal 빈값인 경우

-> 모든 항목이 나옴

searchVal -> aa로 보낸경우

aa@naver.com 데이터가 조회됨

[코프링] 6. Spring Kotlin Jpa Querydsl 적용, 페이징 예제

JaeSung Kim — Fri, 7 Feb 2025 16:51:10 +0900

build.gradle.kt

plugins {
	id("org.springframework.boot") version "3.4.2"
	id("io.spring.dependency-management") version "1.1.7"
	kotlin("jvm") version "1.9.25"
	kotlin("plugin.spring") version "1.9.25"
	kotlin("plugin.jpa") version "1.9.25"
	kotlin("kapt") version "1.9.25"
}

group = "com.contact"
version = "0.0.1-SNAPSHOT"

java {
	toolchain {
		languageVersion.set(JavaLanguageVersion.of(17))
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation("org.springframework.boot:spring-boot-starter-data-jpa")
	implementation("org.springframework.boot:spring-boot-starter-web")
	implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
	implementation("org.jetbrains.kotlin:kotlin-reflect")
	implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
	implementation("org.springframework.boot:spring-boot-starter-validation")

	// QueryDSL 의존성 추가
	implementation("com.querydsl:querydsl-jpa:5.1.0:jakarta")
	kapt("com.querydsl:querydsl-apt:5.1.0:jakarta")
	kapt("jakarta.annotation:jakarta.annotation-api")
	kapt("jakarta.persistence:jakarta.persistence-api")

	runtimeOnly("com.h2database:h2")
	testImplementation("org.springframework.boot:spring-boot-starter-test")
}

// Querydsl 설정부 추가 - start
val generated = file("src/main/generated")

// querydsl QClass 파일 생성 위치를 지정
tasks.withType<JavaCompile> {
	options.generatedSourceOutputDirectory.set(generated)
}

// kotlin source set 에 querydsl QClass 위치 추가
sourceSets {
	main {
		kotlin.srcDirs += generated
	}
}

// gradle clean 시에 QClass 디렉토리 삭제
tasks.named("clean") {
	doLast {
		generated.deleteRecursively()
	}
}
kapt {
	generateStubs = true
}

설명

1. Query-dsl 종속성 추가

implementation("com.querydsl:querydsl-jpa:5.1.0:jakarta")
kapt("com.querydsl:querydsl-apt:5.1.0:jakarta")
kapt("jakarta.annotation:jakarta.annotation-api")
kapt("jakarta.persistence:jakarta.persistence-api")

com.querydsl:querydsl-jpa: 이는 QueryDSL JPA 모듈로, QueryDSL을 사용하여 유형이 안전한 쿼리를 작성하기 위한 JPA 관련 기능을 제공
com.querydsl:querydsl-apt: 이 주석 프로세서는 빌드 프로세스 중에 QueryDSL Q-클래스(즉, JPA 엔터티를 나타내는 클래스)를 생성
jakarta.annotation-api&jakarta.persistence-api : JPA 엔터티를 처리하는 데 사용되는 Jakarta 지속성과 관련된 필수

2. Q-class 생성

val generated = file("src/main/generated")

tasks.withType<JavaCompile> {
	options.generatedSourceOutputDirectory.set(generated)
}

생성된 Q-클래스에 대한 디렉토리 설정 : 생성된 QueryDSL Q-클래스가 저장될 위치를 지정

3. 생성된 소스를 Kotlin 소스 세트에 추가

sourceSets {
	main {
		kotlin.srcDirs += generated
	}
}

이렇게 하면 생성된 QueryDSL Q-클래스가 Kotlin 소스 세트에 추가되어 프로젝트의 나머지 부분에서 사용 generatedKotlin이 코드를 컴파일할 때 고려하는 디렉토리 목록에 디렉토리를 추가

4. Gradle에서 생성된 파일 정리 Clean:

tasks.named("clean") {
	doLast {
		generated.deleteRecursively()
	}
}

gradle clean시 Qclass 디렉토리를 삭제

querydsl 패키지 생성후 QuerydslConfog.kt 생성

package com.contact.management.querydsl

import com.querydsl.jpa.impl.JPAQueryFactory
import jakarta.persistence.EntityManager
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class QueryDslConfig(
    val em: EntityManager
) {

    @Bean
    fun queryFactory(): JPAQueryFactory {
        return JPAQueryFactory(em)
    }
}

service 패키지에 QuerydslUserSerivce.kt 생성

package com.contact.management.service

import com.contact.management.dto.UserDto
import com.contact.management.entity.QUser
import com.contact.management.repository.UserRepository
import com.querydsl.jpa.impl.JPAQueryFactory
import org.springframework.data.domain.Page
import org.springframework.data.domain.PageImpl
import org.springframework.data.domain.Pageable
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
@Transactional
class QuerydslUserService(
    private val queryFactory: JPAQueryFactory
) {

    @Transactional(readOnly = true)
    fun getUsersWithPaging(pageable: Pageable): Page<UserDto> {
        val qUser = QUser.user

        // JPAQueryFactory를 사용하여 쿼리 작성
        val query = queryFactory
            .selectFrom(qUser)
            .orderBy(qUser.id.asc()) // ID 기준으로 오름차순 정렬 (필요에 따라 변경 가능)

        // 실제 데이터 조회
        val users = query
            .offset(pageable.offset) // 페이지의 시작 인덱스
            .limit(pageable.pageSize.toLong()) // 페이지 크기
            .fetch() // 결과 가져오기

        // 총 개수를 구하는 쿼리 작성 (countQuery)
        val countQuery = queryFactory
            .select(qUser.count()) // 총 개수 계산
            .from(qUser)
        val total = countQuery.fetchOne() ?: 0L // fetchOne()으로 단일 값 가져오기

        // Page 객체로 반환
        val userDtos = users.map { UserDto(it.id, it.name, it.email) }
        return PageImpl(userDtos, pageable, total)
    }

}

UserController.kt

package com.contact.management.controller

import com.contact.management.dto.UserDto
import com.contact.management.service.QuerydslUserService
import com.contact.management.service.UserService
import jakarta.validation.Valid
import org.springframework.data.domain.Page
import org.springframework.data.domain.Pageable
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/users")
class UserController(
     private val userService: UserService
    ,private val querydslUserService: QuerydslUserService
) {

    @GetMapping
    fun getUsers(): ResponseEntity<List<UserDto>> {
        val users = userService.getAllUsers()
        return ResponseEntity.ok(users)
    }

    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): ResponseEntity<UserDto> {
        return ResponseEntity.ok(userService.getUserById(id))
    }

    @PostMapping
    fun createUser(@Valid @RequestBody userDto: UserDto): ResponseEntity<UserDto> {
        val createdUser = userService.createdUser(userDto)
        return ResponseEntity
            .status(HttpStatus.CREATED) // 201 Created
            .header(HttpHeaders.LOCATION, "/api/users/${createdUser.id}") // 생성된 리소스의 URI 반환
            .body(createdUser)
    }

    @PutMapping("/{id}")
    fun updateUser(@PathVariable id: Long,@Valid @RequestBody userDto: UserDto): ResponseEntity<UserDto> {
        val updatedUser = userService.updateUser(id, userDto)
        return ResponseEntity.ok(updatedUser)
    }

    @DeleteMapping("/{id}")
    fun deleteUser(@PathVariable id: Long): ResponseEntity<Void> {
        userService.deleteUser(id)
        return ResponseEntity.noContent().build() // 204 No Content
    }

    @GetMapping("/paged")
    fun getUsersWithPaging(pageable: Pageable): Page<UserDto> {
        // 페이징된 사용자 목록 반환
        return querydslUserService.getUsersWithPaging(pageable)
    }
}

getUsersWithPaging 메소드 추가

데이터 미리 넣어보고 /api/users/paged 호출하면 아래형식으로 return됨

{
    "content": [
        {
            "id": 1,
            "name": "aa",
            "email": "aa@domain.com"
        },
        {
            "id": 2,
            "name": "bb",
            "email": "bb@domain.com"
        },
        {
            "id": 3,
            "name": "cc",
            "email": "cc@domain.com"
        },
        {
            "id": 4,
            "name": "dd",
            "email": "dd@domain.com"
        },
        {
            "id": 5,
            "name": "ee",
            "email": "ee@domain.com"
        },
        {
            "id": 6,
            "name": "ff",
            "email": "ff@domain.com"
        },
        {
            "id": 7,
            "name": "gg",
            "email": "gg@domain.com"
        },
        {
            "id": 8,
            "name": "hh",
            "email": "hh@domain.com"
        },
        {
            "id": 9,
            "name": "ii",
            "email": "ii@domain.com"
        },
        {
            "id": 10,
            "name": "jj",
            "email": "jj@domain.com"
        },
        {
            "id": 11,
            "name": "kk",
            "email": "kk@domain.com"
        },
        {
            "id": 12,
            "name": "ll",
            "email": "ll@domain.com"
        },
        {
            "id": 13,
            "name": "mm",
            "email": "mm@domain.com"
        },
        {
            "id": 14,
            "name": "nn",
            "email": "nn@domain.com"
        },
        {
            "id": 15,
            "name": "oo",
            "email": "oo@domain.com"
        },
        {
            "id": 16,
            "name": "pp",
            "email": "pp@domain.com"
        },
        {
            "id": 17,
            "name": "qq",
            "email": "qq@domain.com"
        },
        {
            "id": 18,
            "name": "rr",
            "email": "rr@domain.com"
        },
        {
            "id": 19,
            "name": "ss",
            "email": "ss@domain.com"
        },
        {
            "id": 20,
            "name": "tt",
            "email": "tt@domain.com"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "empty": true,
            "sorted": false,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": true,
    "totalElements": 20,
    "totalPages": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
    },
    "numberOfElements": 20,
    "empty": false
}

[코프링] 5. Spring Jpa Auditing 적용

JaeSung Kim — Fri, 7 Feb 2025 15:34:14 +0900

audit란?

엔터티(Entity)의 생성 및 변경 이력을 자동으로 감지. 이를 통해 데이터 변경 내역을 자동으로 기록할 수 있고, 수동으로 createdAt, updatedAt 등을 설정할 필요가 없음

예제

package com.contact.management.entity

import jakarta.persistence.*
import org.springframework.data.annotation.CreatedBy
import org.springframework.data.annotation.CreatedDate
import org.springframework.data.annotation.LastModifiedBy
import org.springframework.data.annotation.LastModifiedDate
import java.time.LocalDateTime

@Entity
@Table(name = "users")
class User2 (
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long?= null,
    var name: String,
    var email: String,
    @CreatedDate
    @Column(updatable = false)
    var createdAt: LocalDateTime,

    @LastModifiedDate
    var updatedAt: LocalDateTime,
    
    @CreatedBy
    @Column(updatable = false)
    var createdBy: String,
    
    @LastModifiedBy
    var updatedBy: String
)

-> entity를 생성할때 등록자, 수정자, 등록일, 수정일을 추가하고싶을때 수많은 entity에 동일한 코드가 들어가게 된다.

audit를 적용하면 중복된 코드들을 하나의 entity로 관리를 할수 있다.

audit 적용 예제

audit 패키지를 생성후 아래 .kt 파일들을 생성

AuditorAwareConfig.kt

package com.contact.management.audit

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.domain.AuditorAware
import java.util.Optional

@Configuration
class AuditorAwareConfig {
    @Bean
    fun auditorProvider(): AuditorAware<String> {
        return AuditorAware { Optional.of("system") } // 실제 환경에서는 SecurityContext에서 가져오기
    }
}

-> 아직 spring security를 적용하기 전이므로 system이라는 값을 하드코딩 하였음, security를 적용한 이후에는 로그인한 사용자의 아이디를 가져오게 변경해야함

BaseEntity.kt

package com.contact.management.audit

import jakarta.persistence.Column
import jakarta.persistence.EntityListeners
import jakarta.persistence.MappedSuperclass
import org.springframework.data.annotation.CreatedBy
import org.springframework.data.annotation.CreatedDate
import org.springframework.data.annotation.LastModifiedBy
import org.springframework.data.annotation.LastModifiedDate
import org.springframework.data.jpa.domain.support.AuditingEntityListener
import java.time.LocalDateTime

@EntityListeners(AuditingEntityListener::class)
@MappedSuperclass
abstract class BaseEntity {

    @CreatedDate
    @Column(updatable = false)
    lateinit var createdAt: LocalDateTime

    @LastModifiedDate
    lateinit var updatedAt: LocalDateTime

    @CreatedBy
    @Column(updatable = false)
    lateinit var createdBy: String

    @LastModifiedBy
    lateinit var updatedBy: String
}

Application.kt

package com.contact.management

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.data.jpa.repository.config.EnableJpaAuditing

@SpringBootApplication
@EnableJpaAuditing
class ManagementApplication

fun main(args: Array<String>) {
	runApplication<ManagementApplication>(*args)
}

처음 프로젝트를 생성할때 만들어지는 Application.kt 파일에 @EnableJpaAuditing을 추가한다.

User.kt

package com.contact.management.entity

import com.contact.management.audit.BaseEntity
import jakarta.persistence.Entity
import jakarta.persistence.GeneratedValue
import jakarta.persistence.GenerationType
import jakarta.persistence.Id
import jakarta.persistence.Table

@Entity
@Table(name = "users")
class User (
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long?= null,
    var name: String,
    var email: String
) : BaseEntity()

audit를 적용하고자 하는 entity 뒤에 : BaseEntity()를 추가해준다.

결과

-> 이전에 만든 사용자 등록 api를 호출

USERS 테이블을 조회하면 날짜와 하드 코딩한 system이 등록자, 수정자에 insert가 된것을 확인할수 있음

[코프링] 4. @Valid를 사용한 REST API validation 처리

JaeSung Kim — Thu, 6 Feb 2025 18:37:56 +0900

의존성 추가

build.gradle dependencies 안에 아래 코드 추가

implementation("org.springframework.boot:spring-boot-starter-validation")

build.gradle.kt

plugins {
	id("org.springframework.boot") version "3.4.2"
	id("io.spring.dependency-management") version "1.1.7"
	id("java")
	id("org.jetbrains.kotlin.jvm") version "1.9.25"
	id("org.jetbrains.kotlin.plugin.jpa") version "1.9.25"
	id("org.jetbrains.kotlin.plugin.spring") version "1.9.25"
	id("org.jetbrains.kotlin.kapt") version "1.9.25"
}

group = "com.contact"
version = "0.0.1-SNAPSHOT"

java {
	toolchain {
		languageVersion.set(JavaLanguageVersion.of(17))
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation("org.springframework.boot:spring-boot-starter-data-jpa")
	implementation("org.springframework.boot:spring-boot-starter-web")
	implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
	implementation("org.jetbrains.kotlin:kotlin-reflect")
	implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
	implementation("org.springframework.boot:spring-boot-starter-validation")
	runtimeOnly("com.h2database:h2")
	testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.withType<Test> {
	useJUnitPlatform()
}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
	kotlinOptions {
		jvmTarget = "17"
	}
}

UserDto.kt

package com.contact.management.dto

import jakarta.validation.constraints.Email
import jakarta.validation.constraints.Size

data class UserDto(
    val id: Long?= null,

    @field:Size(min = 2, max = 50, message = "이름은 2~50자 사이여야 합니다.")
    val name: String,

    @field:Email(message = "올바른 이메일 형식을 입력하세요.")
    val email: String
)

GlobalExceptionHandler.kt

package com.contact.management.exception

import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.MethodArgumentNotValidException
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.RestControllerAdvice

@RestControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(CommonException::class)
    fun handleCommonException(e: CommonException): ResponseEntity<ErrorResponse> {
        val errorResponse = ErrorResponse(
            status = e.exceptionCode.status.value(),
            error = e.exceptionCode.message,
            message = e.message ?: "예외 발생"
        )
        return ResponseEntity(errorResponse, e.exceptionCode.status)
    }

    @ExceptionHandler(MethodArgumentNotValidException::class)
    fun handleValidationExceptions(ex: MethodArgumentNotValidException): ResponseEntity<ErrorResponse> {
        val errors = ex.bindingResult.fieldErrors.associate { it.field to (it.defaultMessage ?: "잘못된 값") }

        val errorResponse = ErrorResponse(
            status = HttpStatus.BAD_REQUEST.value(),
            error = "Validation Failed",
            message = "입력값이 올바르지 않습니다.",
            errors = errors
        )

        return ResponseEntity(errorResponse, HttpStatus.BAD_REQUEST)
    }
}

-> handlerValdationExceptions를 추가함, vadliation에 걸렸을때 errorResponse에 400 BAD_REQUEST, 에러 내용을 return 하게 설정함

UserController.kt

package com.contact.management.controller

import com.contact.management.dto.UserDto
import com.contact.management.service.UserService
import jakarta.validation.Valid
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

    @GetMapping
    fun getUsers(): ResponseEntity<List<UserDto>> {
        val users = userService.getAllUsers()
        return ResponseEntity.ok(users)
    }

    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): ResponseEntity<UserDto> {
        return ResponseEntity.ok(userService.getUserById(id))
    }

    @PostMapping
    fun createUser(@Valid @RequestBody userDto: UserDto): ResponseEntity<UserDto> {
        val createdUser = userService.createdUser(userDto)
        return ResponseEntity
            .status(HttpStatus.CREATED) // 201 Created
            .header(HttpHeaders.LOCATION, "/api/users/${createdUser.id}") // 생성된 리소스의 URI 반환
            .body(createdUser)
    }

    @PutMapping("/{id}")
    fun updateUser(@PathVariable id: Long,@Valid @RequestBody userDto: UserDto): ResponseEntity<UserDto> {
        val updatedUser = userService.updateUser(id, userDto)
        return ResponseEntity.ok(updatedUser)
    }

    @DeleteMapping("/{id}")
    fun deleteUser(@PathVariable id: Long): ResponseEntity<Void> {
        userService.deleteUser(id)
        return ResponseEntity.noContent().build() // 204 No Content
    }
}

-> createUser, updateUser api에 @Valid를 추가

이름 길이가 2~50자가 아닌경우

이메일 형식을 벗어난 경우

만약 GlobalException에 handleValidationExceptions를 적용하지않았다면

-> GlobalExcpetionHandler에 등록했을때와 비교했을때 에러 메시지가 부족

[코프링] 3. GlobalException handler를 이용한 restApi 에러 처리

JaeSung Kim — Wed, 5 Feb 2025 18:10:03 +0900

프로젝트 구조

CommonException.kt

package com.contact.management.exception

class CommonException(val exceptionCode: CommonExceptionCode) : RuntimeException()

CommonExceptionCode.kt

package com.contact.management.exception

import org.springframework.http.HttpStatus

enum class CommonExceptionCode(
    val status: HttpStatus,
    val message: String,
) {
    USER_NOT_FOUND(HttpStatus.NOT_FOUND, "사용자를 찾을 수 없습니다."),
    EMAIL_ALREADY_EXISTS(HttpStatus.BAD_REQUEST, "이미 존재하는 이메일 입니다."),
}

ErrorResponse.kt

package com.contact.management.exception

import com.fasterxml.jackson.annotation.JsonInclude
import java.time.LocalDateTime

@JsonInclude(JsonInclude.Include.NON_NULL) // null 필드는 JSON 응답에서 제외
data class ErrorResponse(
    val timestamp: LocalDateTime = LocalDateTime.now(),
    val status: Int,
    val error: String,
    val message: String,
    val errors: Map<String, String>? = null // validation 에러 처리를 위한 필드 추가
)

GlobalExceptionHandler.kt

package com.contact.management.exception

import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.MethodArgumentNotValidException
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.RestControllerAdvice

@RestControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(CommonException::class)
    fun handleCommonException(e: CommonException): ResponseEntity<ErrorResponse> {
        val errorResponse = ErrorResponse(
            status = e.exceptionCode.status.value(),
            error = e.exceptionCode.message,
            message = e.message ?: "예외 발생"
        )
        return ResponseEntity(errorResponse, e.exceptionCode.status)
    }
}

-> api에서 CommonException을 throw 하였을때 선언한 httpStatus, message를 return 하게 설정

UserController.kt

package com.contact.management.controller

import com.contact.management.dto.UserDto
import com.contact.management.service.UserService
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

    @GetMapping
    fun getUsers(): ResponseEntity<List<UserDto>> {
        val users = userService.getAllUsers()
        return ResponseEntity.ok(users)
    }

    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): ResponseEntity<UserDto> {
        return ResponseEntity.ok(userService.getUserById(id))
    }

     @PostMapping
    fun createUser(@RequestBody userDto: UserDto): ResponseEntity<UserDto> {
        val createdUser = userService.createdUser(userDto)
        return ResponseEntity
            .status(HttpStatus.CREATED) // 201 Created
            .header(HttpHeaders.LOCATION, "/api/users/${createdUser.id}") // 생성된 리소스의 URI 반환
            .body(createdUser)
    }

    @PutMapping("/{id}")
    fun updateUser(@PathVariable id: Long, @RequestBody userDto: UserDto): ResponseEntity<UserDto> {
        val updatedUser = userService.updateUser(id, userDto)
        return ResponseEntity.ok(updatedUser)
    }

    @DeleteMapping("/{id}")
    fun deleteUser(@PathVariable id: Long): ResponseEntity<Void> {
        userService.deleteUser(id)
        return ResponseEntity.noContent().build() // 204 No Content
    }
}

rest api 설계 원칙

1. request, response 파라미터는 dto를 사용한다. (entity 사용 x)

why : entity는 테이블 생성에 영향을 주기때문에 분리함

2. 간혹 api를 전부 @PostMapping으로 모두 선언해서 설계하는 경우가 있는데, 이는 올바른 설계가 아님

3. api가 정상적인경우는 데이터를 return, 정상적이지 않는경우 status, message, timeStamp 등 에러메시지를 return

4. api는 버전을 통한 관리가 이뤄줘야함

why : 버전관리가 안되고 기존 api를 변경이되면 api를 사용하고 있던 client들에게 장애가 발생할수 있음

ex) 기존 api -> /api/v1/users

변경된 api -> /api/v2/users

5. api를 설계할때 명칭은 계층적으로 만들어야함

ex) /api/v1/car/suv/genesis

UserDto.kt

package com.contact.management.dto

data class UserDto(
    val id: Long?= null,
    val name: String,
    val email: String
)

UserRepository.kt

package com.contact.management.repository

import com.contact.management.entity.User
import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.stereotype.Repository
import java.util.Optional

@Repository
interface UserRepository : JpaRepository<User, Long>{
    fun findByEmail(username: String): User?
}

-> 사용자 등록시 이메일 중복 체크를 위해 findByEmail을 생성함

-> Kotlin에서는 Optional보다는 User?(nullable)로 반환, Optional 사용 시 let 블록 오작동

UserService.kt

package com.contact.management.service

import com.contact.management.dto.UserDto
import com.contact.management.entity.User
import com.contact.management.exception.CommonException
import com.contact.management.exception.CommonExceptionCode.EMAIL_ALREADY_EXISTS
import com.contact.management.exception.CommonExceptionCode.USER_NOT_FOUND
import com.contact.management.repository.UserRepository
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
@Transactional
class UserService(
    private val userRepository: UserRepository
) {

    @Transactional(readOnly = true)
    fun getAllUsers() : List<UserDto> {
        return userRepository.findAll().map { UserDto(it.id, it.name, it.email) }
    }

    @Transactional(readOnly = true)
    fun getUserById(id: Long): UserDto {
        val user = userRepository.findById(id).orElseThrow{ CommonException(USER_NOT_FOUND) }
        return UserDto(user.id, user.name, user.email)
    }

    fun createdUser(userDto: UserDto): UserDto {
        userRepository.findByEmail(userDto.email)?.let {
            throw CommonException(EMAIL_ALREADY_EXISTS)
        }

        val user = userRepository.save(User(name = userDto.name, email = userDto.email))
        return UserDto(user.id, user.name, user.email)
    }

    // 사용자 업데이트
    fun updateUser(id: Long, userDto: UserDto): UserDto{
        val updatedUser = userRepository.findById(id).orElseThrow{ CommonException(USER_NOT_FOUND) }

        // 엔티티의 속성 수정
        updatedUser.name = userDto.name
        updatedUser.email = userDto.email
        // DB에 업데이트 로직

        return UserDto(
            id = updatedUser.id,
            name = updatedUser.name,
            email = updatedUser.email
        )
    }

    fun deleteUser(id: Long){
        if(!userRepository.existsById(id)){
            throw CommonException(USER_NOT_FOUND)
        }
        userRepository.deleteById(id)
    }

}

-> 넘어온 id에 해당하는 사용자가 없을경우 CommonException(USER_NOT_FOUND)로 예외처리

-> 사용자 등록시 이메일 계정이 이미 등록되어있는경우 CommonException(EMAIL_ALREADY_EXISTS)로 예외처리

-> getAllUsers, getUserById는 데이터를 조회만 하기 떄문에 @Transactional(readOnly = true)를 적용

why : 이렇게 하면 변경감지를 하지않으므로 성능향상

주의!!

데이터를 추가/수정/삭제하는 메서드에 @Transactional(readOnly = true)를 적용을 하면 데이터 변경이 반영되지 않음

postman

사용자 등록

201 새로운 리소스(사용자)가 성공적으로 생성되었음을 명확하게 표시 또한 Location 헤더에 생성된 리소스의 URL을 포함

사용자 등록 (이메일 중복)

400 Bad Request	잘못된 요청 (유효성 검사 실패)	클라이언트가 유효하지 않은 데이터를 보냈을 때
409 Conflict	리소스 충돌 (중복 데이터)	데이터베이스의 고유 값 제약 조건을 위반할 때

사용자 전체조회

특정 사용자 조회

특정 사용자 조회 (없는 id)

404 Not Found는 요청한 리소스(사용자)가 존재하지 않을 때 사용하는 표준 상태 코드

사용자 변경

사용자 삭제

리소스를 삭제할 때 204 No Content 응답 코드를 사용하는 것이 일반적

204 No Content를 사용하는 이유
성공적으로 삭제되었음을 나타냄: 요청이 정상적으로 처리되었음을 의미함.
응답 본문이 필요 없음: 삭제된 리소스에 대한 추가적인 정보가 필요하지 않음.
클라이언트가 불필요한 데이터 처리를 하지 않음: 응답 본문이 없으므로 클라이언트가 불필요한 데이터를 처리할 필요가 없음.

사용자 삭제 (없는 사용자)

나만의 개발 기록

# Docker Compose로 Mattermost 사내 메신저 구축하기

Docker Compose로 Mattermost 사내 메신저 구축하기 (Teams 대체)

왜 Mattermost인가

docker-compose.yml 작성

포인트

트러블슈팅 1: 권한 에러 (permission denied)

초기 설정: 관리자 계정 & 팀 초대

트러블슈팅 2: 개인 메시지가 실시간으로 안 뜸

트러블슈팅 3: 모바일 푸시 알림이 안 옴

정리

# [Next.js + TS 실전] 9. FAQ · 시리즈 총정리

[Next.js + TS 실전] 9. FAQ · 시리즈 총정리

이 글에서 하는 일

시리즈 지도

입문 [Next.js + TS]

실전 [Next.js + TS 실전]

우리가 만든 것

스스로 점검 체크리스트

기본

서버·클라이언트

데이터·폼

인증·배포

FAQ (실제로 자주 막히는 것)

Q1. /memos가 404예요

Q2. package.json이 깨져서 npm이 안 돼요

Q3. userId 마이그레이션이 실패해요

Q4. 시드 메모가 로그인 목록에 안 보여요

Q5. createRouteMatcher가 deprecated래요

Q6. SignedOut / SignedIn을 찾을 수 없어요

Q7. parsed.error.flatten()이 deprecated래요

Q8. revalidatePath는 뭐예요?

Q9. Prisma를 루트에 설치하고 memo-app에서 import했어요

Q10. Vercel에 올렸더니 데이터가 안 남아요 / DB 에러

Q11. 티스토리에 붙였더니 코드 블록이 안 먹어요

한 줄로 다시 보는 핵심

다음에 공부하면 좋은 것

마치며

전체 목차 (다시)

# [Next.js + TS 실전] 8. 목록 검색과 정렬

[Next.js + TS 실전] 8. 목록 검색과 정렬

이 편에서 할 일

왜 URL에 두나

1) 데이터 함수에 옵션 추가

2) 목록 페이지에서 searchParams 읽기

동작 흐름

검색 폼이 GET인 이유

(선택) 디바운스 실시간 검색

자주 하는 실수

이 편에서 가져갈 것

다음으로 이어가면 좋은 것

시리즈 목차 (실전)

# [Next.js + TS 실전] 7. 삭제 확인 UI

[Next.js + TS 실전] 7. 삭제 확인 UI

이 편에서 할 일

지금 코드의 문제

접근 두 가지

1) DeleteMemoButton 만들기

2) 상세 페이지에 연결

동작 확인

(선택) 간단한 모달

왜 Action은 그대로인가

자주 하는 실수

이 편에서 가져갈 것

다음으로 이어가면 좋은 것

시리즈 목차 (실전)

# [Next.js + TS 실전] 6. Neon Postgres 연결하기

[Next.js + TS 실전] 6. Neon Postgres 연결하기

이 편에서 할 일

왜 Neon인가

전체 그림

1) Neon에서 DB 만들기

2) 로컬 .env 바꾸기

3) Prisma 스키마: provider 변경

4) 마이그레이션을 Neon에 적용

방법 A) 새 DB에 스키마만 밀어넣기 (가장 단순)

방법 B) migrate로 정식 적용

5) 동작 확인 (로컬)

6) Vercel에 DATABASE_URL 넣기

코드는 왜 거의 안 바꾸나

입문 `[Next.js + TS]`

실전 `[Next.js + TS 실전]`

Q1. `/memos`가 404예요

Q2. `package.json`이 깨져서 npm이 안 돼요

Q3. `userId` 마이그레이션이 실패해요

Q5. `createRouteMatcher`가 deprecated래요

Q6. `SignedOut` / `SignedIn`을 찾을 수 없어요

Q7. `parsed.error.flatten()`이 deprecated래요

Q8. `revalidatePath`는 뭐예요?

2) 로컬 `.env` 바꾸기

`proxy.ts` — Clerk 연결만

`app/memos/layout.tsx` — /memos 전체 보호

5) Prisma: 메모에 주인(`userId`) 붙이기

7) Action / 페이지에서 `auth()`로 userId

3) `createMemo`를 “결과 반환”형으로

`useActionState` 짧게

(3) 로컬 `.env`도 잠시 Postgres로