게시판 API 서버: 설계부터 배포까지

1. 작업 소개

도메인 정의부터 배포·운영까지 아홉 단계를 순서대로 밟아 게시판 API 를 만들었다. 서버는 Express 5 와 Prisma, PostgreSQL 18.6 이고 클라이언트는 Next.js 16 이다.

교육용이라 코드 파일마다 해설 문서가 하나씩 있고 서로를 가리킨다. 소스 첫 줄에 짝이 되는 문서 경로가, 문서 첫 줄에 소스 경로가 적혀 있다. 단계 문서 15편과 코드 문서 40여 편이 그렇게 붙어 있다.

배포된 게시판 첫 화면이다. 글 목록은 로그인하지 않아도 보이고, 글을 쓰거나 댓글을 달 때만 로그인을 요구한다.

2. 아키텍처

밖으로 열린 주소는 Next.js 로 만든 web 서비스 하나다. 브라우저는 이 서비스의 세 경로만 부른다.

• /api/graphql — 화면이 쓰는 거의 모든 요청이 여기로 온다. GraphQL BFF(화면 전용으로 둔 중간 서버)가 요청을 REST 호출로 바꿔 Express 에 넘긴다.
• /api/auth/* — 로그인·재발급·로그아웃만 따로 받는다. Express 가 심은 리프레시 토큰 쿠키를 브라우저까지 그대로 옮기는 것이 이 경로가 하는 일이다.
• /docs — Swagger 명세 화면이다. 화면은 Express 가 만들고 web 은 내부 주소에서 받아 전달만 한다.

Express 와 PostgreSQL 은 Railway 내부 주소로만 통신하고 공개 도메인이 없다.

3. 비즈니스 로직 구성

게시판의 규칙은 Express 의 라우터 핸들러에 모여 있다. 서비스 계층을 따로 두지 않았다. 핸들러가 하는 일은 저장소 호출, 소유권 판단, 성공 응답 세 가지로 줄였고, 형식 검사와 에러 응답은 앞뒤의 미들웨어가 맡는다.

요청 하나는 server/src/app.ts 에 등록한 미들웨어와 각 라우트에 끼운 미들웨어를 이 순서로 지나간다.

라우터 밑으로는 역할별로 파일을 나눴다.

• store/ — Prisma 쿼리만 둔다. 목록은 limit + 1 건을 가져와 다음 페이지가 있는지 판단하고, 글은 최신순, 댓글은 오래된 순으로 정렬한다.
• views.ts — 응답 모양을 만든다. 필요한 필드만 골라 담기 때문에 비밀번호 해시가 응답에 섞일 수 없다. 목록 항목에는 본문을 넣지 않는다.
• errors.ts — AppError 를 상속한 에러 클래스와 에러 코드 9가지를 정해 둔다. 라우터는 "무엇이 잘못됐는지" 만 던지고 상태 코드는 이 파일이 정한다.

규칙

클라이언트 쪽 규칙

Next.js 쪽은 domain · application · infrastructure · presentation 네 층으로 나누고, 층끼리 잇는 일은 composition/container.ts 가 한다.

• domain/*/policy.ts — canEdit, canDeleteComment 와 제목 200자·댓글 1,000자 같은 입력 검사가 있다. 서버와 같은 값을 쓰지만 화면에 수정 버튼을 보여 줄지 정하는 용도일 뿐이고, 실제 판정은 서버의 403 이다.
• application/usecase/ — 입력 검사를 먼저 하고 포트(저장소 인터페이스)를 부른다. 요청을 보내기 전에 막아 입력란 옆에 바로 메시지를 띄우려는 것이고, 서버 검사를 대신하지는 않는다. React 도 Next 도 import 하지 않는다.
• infrastructure/ — 포트를 GraphQL 호출로 구현한다. 로그인·재발급·로그아웃만 REST 로 부른다.

BFF 리졸버에는 규칙이 없다. GraphQL 과 REST 사이의 모양만 맞춘다. 정렬값 createdAt_desc 를 createdAt:desc 로 되돌리고, 본문 없는 204 응답을 true 로 바꾸고, 서버의 error.code 를 GraphQL 에러의 extensions 에 실어 화면이 코드로 분기하게 한다.

4. 인증 아키텍처와 구현

로그인은 회원가입, 로그인, 토큰 재발급, 로그아웃 네 가지 요청으로 이뤄진다. 서버가 직접 토큰을 발급하고 검증하며, 외부 인증 서비스는 쓰지 않는다.

설계: 토큰을 두 개로 나눴다

둘로 나눈 이유는 토큰이 새어 나갔을 때의 피해를 줄이기 위해서다. 액세스 토큰은 자바스크립트가 읽을 수 있는 곳에 있어서, 페이지에 악성 스크립트가 끼어들면(XSS) 가져갈 수 있다. 대신 15분이 지나면 쓸모가 없다. 오래 사는 리프레시 토큰은 httpOnly 쿠키에 둔다. 자바스크립트가 아예 읽지 못하는 쿠키라서 같은 방법으로는 가져갈 수 없다.

쿠키는 브라우저가 요청에 자동으로 실어 보낸다. 그래서 다른 사이트가 사용자 브라우저를 시켜 요청을 보내게 하는 공격(CSRF)을 따로 막아야 하고, SameSite=Strict 가 그 일을 한다. 쿠키 경로도 Path=/auth 로 좁혀서 재발급·로그아웃 요청에만 실린다.

서버 구현

비밀번호는 argon2id 해시로만 저장한다. SHA-256 같은 빠른 해시는 GPU 로 초당 수십억 번을 돌릴 수 있어서, 사람이 고른 짧은 비밀번호는 금방 맞힌다. argon2id 는 일부러 느리고 메모리를 많이 쓰게 만든 함수다. 라이브러리 기본값(메모리 64MiB, 반복 3, 병렬 4)을 그대로 쓰고, salt 도 라이브러리가 넣는다. 그래서 같은 비밀번호라도 저장되는 값이 매번 다르다. 컬럼 이름도 password 에서 passwordHash 로 바꿨다. 이름만 보고 평문인 줄 알고 비교하는 실수를 막으려는 것이다.

로그인 실패는 이유를 알려 주지 않는다. 없는 이메일과 틀린 비밀번호 모두 같은 401 INVALID_CREDENTIALS 를 돌려준다. 다른 응답을 주면 그 이메일이 가입돼 있다는 사실이 드러나기 때문이다. 응답 시간도 맞췄다. 없는 이메일일 때 해시 검증을 건너뛰면 응답이 눈에 띄게 빨라지므로, 사용자가 없어도 더미 해시로 검증을 한 번 돌린다.

토큰에는 최소한만 담는다. server/src/auth/tokens.ts 가 jose 로 HS256 서명을 한다. 페이로드에는 sub(사용자 id), typ, iat, exp 만 넣는다. JWT 는 서명된 것이지 암호화된 것이 아니어서 누구나 내용을 읽을 수 있다. 그래서 이메일이나 닉네임은 넣지 않는다. 검증할 때는 알고리즘을 HS256 으로 못 박는다. 토큰이 스스로 밝힌 알고리즘을 믿으면 alg: "none" 같은 바꿔치기가 통하기 때문이다. typ 을 확인해서 리프레시 토큰으로 API 를 부르는 것도 막는다. 서명 키 JWT_SECRET 은 서버가 뜰 때 env.ts 가 32자 이상인지 확인하고, 기본값은 두지 않는다.

라우터는 사용자 id 하나만 안다. middleware/currentUser.ts 가 Authorization 헤더의 토큰을 검증해 req.user 를 채운다. 토큰이 없거나 망가져도 여기서는 막지 않는다. 글 목록처럼 로그인 없이 보는 요청이 있기 때문이다. 로그인이 필요한 라우트에만 requireAuth 를 끼워 401 을 낸다. 라우터는 req.user.id 가 어디서 왔는지 모른다. 그 덕에 사용자 id 를 헤더에 그대로 싣던 임시 방식에서 JWT 로 바꿀 때 고친 파일은 currentUser.ts 하나였고, 글·댓글 라우터는 한 줄도 바뀌지 않았다.

401 과 403 을 구분한다. 401 은 누군지 모른다는 뜻이고, 403 은 누군지는 알지만 권한이 없다는 뜻이다. 화면은 401 이면 로그인 화면으로 보내고 403 이면 보내지 않는다. 다시 로그인해도 남의 글을 고칠 수는 없기 때문이다.

재발급할 때마다 리프레시 토큰을 바꾼다. POST /auth/refresh 는 쿠키가 없으면 401 이다. 쿠키가 있으면 typ: "refresh" 인지 검증한다. 서명이 맞더라도 그사이 계정이 지워졌을 수 있어서 DB 에서 한 번 더 확인한다. 통과하면 새 액세스 토큰을 돌려주고, 쿠키도 새 리프레시 토큰으로 바꿔 심는다.

쿠키를 심는 옵션과 지우는 옵션을 한 곳에서 만든다. 브라우저는 이름이 같아도 path·sameSite·secure 까지 같아야 같은 쿠키로 본다. 두 옵션을 따로 적어 두면 한쪽만 고치는 날 로그아웃이 204 를 주면서도 쿠키가 남는다. 그래서 cookieScope 하나(httpOnly, sameSite: "strict", 운영에서만 secure, path: "/auth")를 두고, 심을 때는 수명(maxAge)만 더한다.

로그아웃은 로그인을 요구하지 않는다. 액세스 토큰이 만료된 사람에게 401 을 주면 쿠키를 지울 방법이 없다. 그래서 쿠키가 있든 없든 쿠키를 지우고 204 를 돌려준다.

BFF 를 지나는 쿠키

브라우저는 Next.js 와만 통신하고, 쿠키를 심는 것은 Express 다. 그래서 중간에서 쿠키를 옮겨 줘야 한다. GraphQL 리졸버가 응답 헤더를 다루게 하면 스키마만 보고 계약을 알 수 없게 된다. 그래서 로그인·재발급·로그아웃만 /api/auth/* 라는 REST 경로로 뺐다.

web/src/app/api/auth/proxy.ts 는 세 가지 일을 한다.

1. 브라우저가 보낸 cookie 헤더를 Express 로 그대로 넘긴다. 이 줄이 없으면 재발급이 "리프레시 토큰이 없습니다" 로 끝난다.
2. Express 가 보낸 Set-Cookie 의 Path=/auth 를 Path=/api/auth 로 고쳐 브라우저에 전한다. 브라우저 입장에서 재발급 주소는 /api/auth/refresh 이기 때문이다.
3. 로그아웃의 204 는 본문 없이 돌려준다. 빈 문자열이라도 본문을 넣으면 Response 가 거부한다.

나머지 요청은 GraphQL BFF 가 받는다. BFF 는 브라우저가 보낸 Authorization 헤더에서 토큰을 꺼내 Express 호출에 그대로 싣는다.

클라이언트 구현

• 토큰 저장소 — infrastructure/auth/tokenStorage.ts 가 액세스 토큰을 localStorage 에 둔다. localStorage 는 같은 탭에서 값이 바뀌면 이벤트를 보내지 않아서, 같은 탭에는 직접 알리고 다른 탭의 변경은 storage 이벤트로 받는다. 한 탭에서 로그아웃하면 다른 탭도 로그아웃 상태가 된다.
• 로그인 — 유스케이스(application/usecase/auth.ts)가 토큰 저장까지 맡는다. 화면이 저장을 챙기게 하면 로그인 경로가 늘어날 때마다 빠뜨릴 곳이 생긴다.
• 자동 재발급 — GraphQL 클라이언트가 UNAUTHENTICATED 를 받으면 재발급을 한 번 시도하고, 성공하면 같은 요청을 한 번만 다시 보낸다. 재발급까지 401 이면 재시도를 반복하지 않고 에러를 던진다. 재발급에 실패하면 저장된 토큰도 지운다.
• 로그인 여부 판단 — 토큰이 없으면 서버에 묻지 않고 바로 로그아웃 상태로 본다. 예전에는 토큰이 없을 때 쿼리가 계속 대기 상태로 남아서, 로그아웃한 사람에게 글쓰기 폼이 보였다.
• 로그아웃 — 쿼리 캐시를 먼저 비우고, 로컬 토큰을 지운 다음, 쿠키를 지우러 서버에 요청한다. 서버 응답을 기다리지 않으므로 버튼을 누르면 화면이 바로 바뀐다.
• 401·403 처리 — useAuthGuard 가 401 이면 /login?returnTo=<현재 경로> 로 보내고, 403 이면 서버가 준 문구("내 글만 삭제할 수 있습니다.")를 그대로 보여 준다.

검증과 한계

인증을 붙인 단계의 검사 24가지가 모두 통과했다. 토큰 없음, 만료, 남의 키로 서명, 서명 잘라냄 네 경우 모두 401 이 나왔다. DB 의 passwordHash 는 모두 $argon2id$ 로 시작했고, 같은 비밀번호로 만든 두 계정의 해시는 서로 달랐다. 리프레시 쿠키 없이 재발급하거나 액세스 토큰을 쿠키 자리에 넣어도 401 이었다.

남은 한계는 이렇다.

• 서버가 리프레시 토큰을 기록하지 않는다. 그래서 특정 토큰만 취소할 수 없다. 로그아웃이 지우는 것은 그 브라우저의 쿠키뿐이고, 이미 새어 나간 리프레시 토큰은 만료까지 14일 동안 쓸 수 있다. 재발급 때 새 토큰으로 바꾸기는 하지만, 옛 토큰을 기록해 두지 않으므로 옛 토큰도 만료 전까지는 통한다. 막으려면 users 에 시각 컬럼을 두고 토큰의 iat 와 비교하는 식으로 서버가 상태를 가져야 한다. 이번 범위에서는 하지 않았다.
• 액세스 토큰이 localStorage 에 있다. XSS 가 생기면 가져갈 수 있다. 수명을 15분으로 짧게 둔 것으로 피해를 줄였을 뿐 막지는 못한다.

토큰이 이어지는 원리는 액세스 토큰과 리프레시 토큰은 어떻게 이어지나에 더 자세히 적었다.

5. 구현 과정과 선택 기준

REST 서버를 두고 GraphQL 은 Next 안에 BFF 로 넣었다. 서버를 GraphQL 로 바꾸면 명세를 프론트엔드에 보여주기 어려워지고, 화면이 필요로 하는 모양은 화면 쪽에서 정하는 편이 맞다고 봤다. 다만 로그인·재발급·로그아웃만 REST 한 겹으로 남겼다 — 리프레시 토큰이 httpOnly 쿠키인데 쿠키는 HTTP 의 것이고 GraphQL 은 그것을 모른다.

목록은 커서 페이지네이션이다. 글 1만 건에서 오프셋은 뒤로 갈수록 느려지고(0.053 → 1.504 ms) 커서는 위치와 무관하게 일정했다. (createdAt desc, id desc) 복합 인덱스를 붙이니 Seq Scan + Sort 가 Index Only Scan 으로 바뀌면서 1.922 ms 가 0.049 ms 가 됐다.

400 과 422 를 가르는 기준을 값으로 정했다. 쿼리·경로는 무조건 400, 본문은 zod 의 issue code 로 나눈다. 형식이 틀린 것과 값이 범위를 벗어난 것은 고쳐야 할 곳이 다르다.

배포에서 밖으로 나가는 것은 클라이언트 하나뿐이다. API 서버와 DB 는 공개 도메인이 없다. 그래서 명세 화면(/docs)도 클라이언트가 대신 받아 내부 주소로 넘긴다.

6. 현재 상태와 남은 작업

배포되어 있고 API 명세는 Swagger UI 로 열려 있다.

main 에 푸시하면 검사 43가지가 돌고, 통과해야만 배포로 넘어간다. 올라간 뒤에는 공개 주소를 5가지로 불러 전 구간이 이어졌는지 확인한다 — 플랫폼 헬스체크는 컨테이너가 떴는지만 보기 때문이다.

만들면서 정한 것들은 아홉 단계로 만들면서 정한 것들에, 토큰이 이어지는 방식은 액세스 토큰과 리프레시 토큰은 어떻게 이어지나에 따로 적었다.

되돌리기는 아직 자동이 아니다. 스테이징 환경도 없어서 main 에 들어오면 바로 운영이다. 검사는 모두 HTTP 를 통과하는 것이라 단위 테스트는 없다.