프론트엔드 버그는 대개 화면 하나가 깨지는 걸로 끝나고, 사용자가 새로고침하면 다시 처음부터 시작한다. 백엔드에서 잘못 쓴 데이터는 새로고침해도 그대로 남아 있고, 누가 손으로 고치기 전까지 여러 사람이 그 데이터를 동시에 읽고 쓴다. 화면을 만들 때는 사용자 한 명만 떠올리면 됐다. 서버는 두 사람이 같은 순간에 같은 버튼을 누르는 상황까지 견뎌야 한다.
이 글은 그 차이에서 생기는 일들을 DB, 인프라, 보안 세 갈래로 나눠 정리했다.
DB
DB는 서버 개발에서 가장 중요하다. 서버 코드는 다시 배포하면 바뀌지만 한번 잘못 들어간 데이터는 누가 손으로 고칠 때까지 남으니, 실수를 막는 장치는 되도록 DB 가까이에 둔다.
제약조건은 DB 에 건다
회원가입에서 이메일 중복을 막는 코드를 흔히 이렇게 짠다.
const exists = await db.user.findUnique({ where: { email } })
if (exists) throw new Error("이미 가입된 이메일입니다")
await db.user.create({ data: { email, name } })
로컬에서 테스트하면 잘 된다. 사용자가 가입 버튼을 빠르게 두 번 누르면 얘기가 달라진다. 요청 두 개가 거의 동시에 들어오고, 둘 다 조회하는 시점에는 아직 아무도 없으니 함께 통과해서 같은 이메일로 계정이 두 개 생긴다.
앱 코드에서 확인하고 쓰는 방식으로는 그 사이의 틈을 막을 수 없다. 이건 DB 제약조건이 할 일이다.
ALTER TABLE users ADD CONSTRAINT users_email_key UNIQUE (email);
이제 두 번째 INSERT는 DB가 거부한다. 앱 코드는 그 에러를 잡아서 "이미 가입된 이메일"이라고 알려 주기만 하면 된다. 앞의 조회는 친절한 에러 메시지를 위해 남겨 둬도 괜찮지만, 중복을 실제로 막는 건 제약조건이다.
제약조건은 UNIQUE 말고도 몇 가지가 더 있다. 비어 있으면 안 되는 컬럼에는 NOT NULL을, 다른 테이블을 가리키는 컬럼에는 외래 키를 걸고, 값의 범위가 정해진 컬럼에는 CHECK를 쓴다. 재고가 음수가 되면 안 된다면 CHECK (stock >= 0) 한 줄로 충분하다. 코드에 버그가 있어도 마지막에 DB가 막아줄 수 있다.
ORM을 쓴다면 스키마에 선언하는 걸로 된다. 마이그레이션을 돌리면 선언이 그대로 DB 제약조건이 된다.
model User {
id Int @id @default(autoincrement())
email String @unique // UNIQUE
name String // ?가 없으면 NOT NULL
}
헷갈리기 쉬운 건 이름만 비슷한 앱 단 검증이다. Sequelize의 validate나 클래스 검증 데코레이터는 앱 코드 안 에서 값을 확인할 뿐이라, 앞의 이메일 중복처럼 동시에 들어온 요청은 둘 다 통과시킨다. Prisma는 스키마로 CHECK를 선언할 수 없어서 마이그레이션 SQL 파일에 직접 추가해야 하고, relationMode = "prisma"를 쓰면 DB에 외래 키가 아예 생기지 않는다. 제약이 실제로 걸렸는지는 생성된 마이그레이션 SQL을 통해 확인할 수 있다.
함께 바뀌어야 하는 건 트랜잭션으로 묶는다
포인트로 결제하는 기능이 있다. 포인트를 차감하고, 주문을 만든다.
await db.user.update({ where: { id: userId }, data: { points: { decrement: price } } })
await db.order.create({ data: { userId, productId, price } }) // 여기서 실패하면?
두 번째 줄에서 에러가 나면 포인트만 빠지고 주문은 없다. 그 사이에 서버가 재시작돼도 마찬가지다. 둘 다 되거나 둘 다 안 돼야 하는 작업은 트랜잭션으로 묶는다.
await db.$transaction(async (tx) => {
await tx.user.update({ where: { id: userId }, data: { points: { decrement: price } } })
await tx.order.create({ data: { userId, productId, price } })
})
트랜잭션 안에서 에러가 나면 앞에서 한 변경까지 전부 되돌아간다. 예시는 Prisma지만 어느 ORM이든 비슷한 기능이 있다.
트랜잭션 안에서 외부 API는 부르지 않는다. 결제 대행사 응답을 기다리는 몇 초 동안 DB 락과 커넥션을 붙잡고 있게 되고, 외부 호출은 롤백되지도 않는다.
동시에 들어오는 요청
한정판 상품의 재고를 줄이는 코드다.
const product = await db.product.findUnique({ where: { id } })
if (product.stock <= 0) throw new Error("품절")
await db.product.update({ where: { id }, data: { stock: product.stock - 1 } })
재고가 1개 남았을 때 두 사람이 동시에 주문하면 둘 다 stock = 1을 읽고 통과한 뒤 stock = 0을 쓴다. 물건은 하나인데 주문은 두 개다.
읽고 계산해서 쓰는 사이에 다른 요청이 끼어든 것이다. 읽기와 쓰기를 쿼리 하나로 합치면 끼어들 틈이 없어진다.
UPDATE products SET stock = stock - 1 WHERE id = $1 AND stock > 0;
DB는 이 문장을 한 번에 처리한다. 바뀐 행이 0개면 품절이다. 계산이 복잡해서 쿼리 하나로 안 되면 트랜잭션 안에서 SELECT ... FOR UPDATE로 행을 잠그고 처리하고, 앞에서 건 CHECK (stock >= 0)가 마지막 안전망 노릇을 한다.
이런 버그는 로컬에서 테스트하면 절대 안 보인다. 읽은 값으로 다시 쓰는 코드가 보이면 일단 의심부터 한다.
중복 요청은 한 번만 처리한다
결제 요청 하나가 서버에 두 번 들어오는 일은 생각보다 흔하다. 사용자가 결제 버튼을 두 번 누르거나, 모바일 네트워크가 끊겨 앱이 같은 요청을 자동으로 다시 보내거나, 응답이 늦어 사용자가 새로고침하는 경우다. 아무 대비가 없으면 서버는 이걸 서로 다른 주문 두 건으로 처리하고, 결제도 두 번 된다.
조회는 두 번 해도 상관없다. 결제나 송금처럼 두 번 처리되면 안 되는 요청은 멱등성(idempotency) 을 보장해야 한다. 같은 요청을 몇 번 보내도 결과가 한 번 보낸 것과 같다는 뜻이다.
흔히 쓰는 방법은 클라이언트가 요청마다 고유한 키를 만들어 같이 보내게 하는 것이다.
// 결제 화면에 들어올 때 한 번 만들고, 재시도할 때도 같은 값을 보낸다
const idempotencyKey = crypto.randomUUID()
fetch("/api/orders", {
method: "POST",
headers: { "Idempotency-Key": idempotencyKey },
body: JSON.stringify({ productId }),
})
서버는 이 키를 UNIQUE 제약이 걸린 컬럼에 주문과 함께 저장한다. 같은 키로 두 번째 요청이 오면 INSERT가 실패하니, 새로 처리하지 않고 처음 만든 주문을 돌려준다. 여기서도 일을 하는 건 DB 제약조건이다. Stripe 같은 결제 API가 이 방식을 쓴다.
프론트에서 버튼을 비활성화해도 막을 수 있는 건 더블클릭 정도고, 네트워크 재시도는 그대로 들어온다.
N+1 쿼리
게시글 목록에 작성자 이름을 같이 보여 주려고 이렇게 짜기 쉽다.
const posts = await db.post.findMany({ take: 20 })
for (const post of posts) {
post.author = await db.user.findUnique({ where: { id: post.authorId } })
}
목록 조회 1번에 작성자 조회 20번, 쿼리가 21번 나간다. 글이 20개일 때는 티가 안 나도 목록이 길어지고 댓글과 좋아요까지 붙으면 페이지 하나에 쿼리가 수백 번 나간다. 이걸 N+1 문제라고 부른다.
JOIN을 쓰거나 ORM이 제공하는 방법으로 한 번에 가져온다.
const posts = await db.post.findMany({ take: 20, include: { author: true } })
ORM을 쓰면 코드만 봐서는 쿼리가 몇 번 나가는지 알기 어렵다. 개발 환경에서는 쿼리 로그를 켜 둔다. 페이지 하나 열었는데 로그가 화면을 넘어간다면? 거의 N+1이다.
인덱스
데이터가 1000건일 때는 무슨 쿼리를 짜도 빠르다. 10만 건, 100만 건이 되면 어느 날 갑자기 느려지는데, 대부분 인덱스가 없어서다.
인덱스가 없으면 DB는 WHERE email = ...를 처리하려고 테이블을 처음부터 끝까지 읽는다. 인덱스는 책 뒤의 찾아보기처럼 원하는 행으로 바로 가게 해 준다.
CREATE INDEX posts_author_id_created_at_idx ON posts (author_id, created_at);
어디에 걸지는 쿼리를 보고 정한다. WHERE, JOIN, ORDER BY에 자주 나오는 컬럼이 후보다. 기본 키와 UNIQUE 컬럼에는 인덱스가 자동으로 생기지만 PostgreSQL은 외래 키 컬럼에는 만들어 주지 않으니 직접 건다. 쿼리가 느리면 앞에 EXPLAIN ANALYZE를 붙여 실행해 본다. 결과에 Seq Scan이 보이면 테이블 전체를 읽고 있다는 뜻이다.
인덱스는 쓰기마다 같이 갱신해야 해서, 많이 걸수록 INSERT와 UPDATE가 느려진다. 느린 쿼리를 찾아서 그 쿼리에 맞게 건다.
목록에는 끝이 있어야 한다
조건 없이 findMany()를 부르는 API는 처음엔 문제가 없다. 데이터가 50건이니까. 1년 뒤 50만 건이 되면 응답 하나에 수십 MB가 실리고 서버 메모리가 터진다. 목록 API에는 처음부터 개수 제한과 페이지네이션을 넣는다.
OFFSET으로 페이지를 넘기는 방식은 간단하다. 하지만 DB가 앞의 행을 다 세고 버려야 해서 뒤쪽 페이지로 갈수록 느려진다. 무한 스크롤이라면 마지막으로 받은 항목을 기준으로 다음 묶음을 가져오는 커서 방식이 낫다. 커서는 어디까지 받았는지 알려 주는 값으로, 보통 마지막 항목의 id를 쓴다.
첫 요청은 커서 없이 보내고, 서버는 목록과 함께 다음 요청에 쓸 커서를 돌려준다. 더 가져올 게 없으면 null이다.
GET /api/posts?limit=20
→ { "items": [...20개], "nextCursor": 981 }
GET /api/posts?limit=20&cursor=981
→ { "items": [...20개], "nextCursor": 958 }
GET /api/posts?limit=20&cursor=12
→ { "items": [...7개], "nextCursor": null }
서버는 커서보다 작은 id만 골라 최신순으로 자른다.
const limit = Math.min(Number(req.query.limit) || 20, 100)
const cursor = req.query.cursor ? Number(req.query.cursor) : undefined
const posts = await db.post.findMany({
where: cursor ? { id: { lt: cursor } } : undefined,
orderBy: { id: "desc" },
take: limit + 1, // 하나 더 가져와서 다음 묶음이 있는지 본다
})
const hasNext = posts.length > limit
const items = posts.slice(0, limit)
res.json({ items, nextCursor: hasNext ? items[items.length - 1].id : null })
SQL로는 이렇게 나간다.
SELECT * FROM posts
WHERE id < 981 -- 이전 묶음의 마지막 id
ORDER BY id DESC
LIMIT 21;
id는 기본 키라 인덱스가 이미 있어서 몇 번째 묶음이든 속도가 같다. 스크롤하는 사이 새 글이 올라와도 OFFSET처럼 목록이 한 칸씩 밀려 같은 글이 두 번 보이는 일이 없다.
created_at처럼 값이 겹칠 수 있는 컬럼으로 정렬한다면 (created_at, id)를 함께 커서로 쓴다. 그래야 경계에서 항목이 빠지거나 겹치지 않는다.
WHERE (created_at, id) < ($1, $2)
ORDER BY created_at DESC, id DESC
돈과 시간
돈은 float로 계산하지 않는다. 자바스크립트에서 0.1 + 0.2는 0.30000000000000004다. 원화라면 원 단위 정수로, 소수점이 있는 통화라면 센트 같은 가장 작은 단위의 정수나 DB의 NUMERIC 타입으로 저장한다.
시간은 UTC로 저장한다. PostgreSQL이라면 timestamptz 타입을 쓴다. 서버가 어느 지역에 떠 있든 사용자가 어디서 접속하든 기준이 하나로 맞춰지고, 한국 시간으로 바꾸는 건 화면에 보여 줄 때 한다. "오늘 가입자 수" 같은 통계는 어느 시간대의 오늘인지부터 정해야 한다. 안 그러면 날짜가 매일 아침 9시에 바뀐다.
마이그레이션은 되돌리기 어렵다
프론트엔드는 잘못 배포하면 이전 버전으로 돌리면 끝이다. DB 스키마는 사정이 다르다. 컬럼을 지우면 그 안의 데이터도 같이 사라지고, 배포를 되돌려도 데이터는 돌아오지 않는다.
배포하는 동안에는 이전 버전 서버와 새 버전 서버가 잠깐 같이 돌기 때문에, 컬럼 이름을 바꾸거나 지울 때는 단계를 나눈다.
- 새 컬럼을 추가한다.
- 코드가 두 컬럼에 모두 쓰도록 바꿔 배포하고, 기존 데이터를 새 컬럼으로 옮긴다.
- 읽기를 새 컬럼으로 바꿔 배포한다.
- 이전 컬럼을 아무 코드도 쓰지 않는 걸 확인한 다음에 지운다.
번거로워도 이렇게 해 두면 어느 시점에 배포를 되돌려도 서버가 에러를 내지 않는다.
컬럼을 추가할 때도 순서가 있다. users 테이블에 필수 값인 nickname 컬럼을 넣는다고 해 보자. 처음부터 NOT NULL로 추가하면 기존 행에 넣을 값이 없어서 마이그레이션이 실패한다. 실무에서는 보통 이렇게 나눈다.
-
비어 있어도 되는(nullable) 컬럼으로 먼저 추가한다. 이전 버전 코드는 이 컬럼을 모르니 그대로 돌아간다.
ALTER TABLE users ADD COLUMN nickname text; -
가입하거나 프로필을 수정할 때
nickname을 채우는 코드를 배포한다. -
기존 행을 채운다(백필). 수백만 건을
UPDATE한 번으로 바꾸면 그동안 행이 잠기고 DB 부하가 치솟으니, 몇천 건씩 나눠서 돌린다.UPDATE users SET nickname = split_part(email, '@', 1) WHERE id BETWEEN 1 AND 5000 AND nickname IS NULL; -- 5001~10000, 10001~15000 ... 끝까지 반복 -
빈 값이 남지 않은 걸 확인하고
NOT NULL을 건다.SELECT count(*) FROM users WHERE nickname IS NULL; -- 0이어야 한다 ALTER TABLE users ALTER COLUMN nickname SET NOT NULL;
PostgreSQL의 SET NOT NULL은 테이블 전체를 훑는 동안 쓰기를 막는다. 테이블이 크다면 CHECK (nickname IS NOT NULL) NOT VALID로 제약만 먼저 걸고 VALIDATE CONSTRAINT로 따로 검증한다. 검증하는 동안에도 읽기와 쓰기는 계속된다.
모든 컬럼을 이렇게 네 단계로 나눌 필요는 없다. plan text NOT NULL DEFAULT 'free'처럼 고정된 기본값이 자연스러운 컬럼은 한 번에 추가한다. PostgreSQL 11부터는 이런 컬럼을 추가해도 테이블을 다시 쓰지 않아서 금방 끝난다. 다만 gen_random_uuid()처럼 행마다 값이 달라지는 기본값은 테이블 전체를 다시 쓴다.
컬럼 하나 추가하다 서비스가 멈추는 일도 있다. ALTER TABLE은 아주 짧게라도 테이블 전체 잠금을 잡아야 하는데, 그 테이블에 오래 걸리는 쿼리가 돌고 있으면 그게 끝날 때까지 기다린다. 그사이 뒤로 들어오는 평범한 SELECT까지 전부 ALTER 뒤에 줄을 서면서 서비스가 멈춘다. 마이그레이션 앞에 잠금 대기 시간을 걸어 두고, 실패하면 한가한 시간에 다시 돌린다.
SET lock_timeout = '5s';
ALTER TABLE users ADD COLUMN nickname text;
마이그레이션은 새 코드보다 먼저 실행한다. Prisma라면 CI에서 앱 배포 앞 단계에 prisma migrate deploy를 둔다. 스키마에 필수 필드를 바로 추가하면 Prisma가 기존 행 때문에 경고를 띄우는데, prisma migrate dev --create-only로 SQL 파일만 만든 다음 위 순서대로 마이그레이션을 나눠 고친다.
큰 테이블에 인덱스를 만들거나 컬럼 타입을 바꾸면 그동안 테이블이 잠길 수 있다. 수백만 건짜리 테이블이라면 운영 중에 바로 실행하지 말고, 쓰는 DB에서 잠금 없이 하는 방법(PostgreSQL의 CREATE INDEX CONCURRENTLY 같은)부터 찾아본다.
백업도 챙긴다. 자동 백업이 켜져 있는지 확인하고 실제로 복구를 한 번 해 본다. 복구해 본 적 없는 백업은 있는지 없는지 모르는 것과 같다. RDS 같은 관리형 DB에는 보통 특정 시점으로 복구하는 기능이 있으니 쓰는 법을 미리 알아 둔다.
인프라
인프라라고 하면 쿠버네티스나 오토스케일링이 먼저 떠오른다. 처음 백엔드를 맡은 사람에게 필요한 건 훨씬 기본적인 것들이다. 서버가 어떤 환경에서 돌고 어떻게 죽는지, 죽었을 때 어떻게 알아차리는지.
서버는 언제든 사라진다
브라우저에서는 전역 변수나 메모리에 상태를 두는 게 자연스럽다. 탭이 살아 있는 동안은 그대로 있으니까. 서버에서 같은 습관대로 하면 탈이 난다.
const sessions = new Map() // 로그인 세션을 메모리에
const uploadDir = "./uploads" // 업로드 파일을 서버 디스크에
다시 배포하면 메모리는 비워진다. 서버를 두 대로 늘리면 같은 사용자의 첫 요청은 1번 서버로, 다음 요청은 2번 서버로 가서 세션이 없다고 나온다. Vercel이나 AWS Lambda 같은 서버리스 환경에서는 요청마다 다른 인스턴스가 뜰 수 있고 디스크도 임시다.
서버는 상태를 들고 있지 않게(stateless) 만든다. 세션과 캐시는 Redis나 DB에, 업로드 파일은 S3 같은 오브젝트 스토리지에 두면 어느 서버가 요청을 받아도 결과가 같다. 이렇게 해 두면 서버를 늘리거나 재시작해도 아무 일이 없다.
환경을 나눈다
최소한 로컬과 운영은 분리하고, 가능하면 운영과 똑같이 구성한 스테이징을 하나 더 둔다. DB도 환경마다 따로 쓴다.
로컬에서 운영 DB에 직접 붙어 개발하는 건 피한다. 테스트 데이터를 지운다는 게 실제 사용자 데이터를 지울 수 있다. 운영 DB 접속 정보는 아는 사람이 적을수록 좋다. 운영 데이터를 직접 고쳐야 할 때는 같은 조건으로 SELECT를 먼저 돌려서 몇 건이 바뀌는지 확인하고, 트랜잭션 안에서 실행한다.
외부 호출에는 타임아웃을 건다
결제, 메일 발송, LLM API, 지도 API까지, 서버 는 생각보다 많은 외부 서비스를 부른다. 그리고 외부 서비스는 언젠가 느려지거나 응답하지 않는다.
타임아웃이 없으면 상대가 응답을 안 줄 때 내 서버의 요청도 같이 멈춘다. 그런 요청이 쌓여 커넥션과 메모리가 바닥나면 외부 서비스 하나 때문에 내 서비스 전체가 죽는다. Node.js의 fetch는 기본으로 응답 헤더를 5분까지 기다린다. 사용자를 5분 세워 둘 수는 없으니 직접 건다.
const res = await fetch(url, { signal: AbortSignal.timeout(5000) }) // 5초
실패하면 다시 시도할 수 있다. 바로 연달아 재시도하면 이미 힘든 상대 서버를 더 두드리게 되니, 1초, 2초, 4초처럼 간격을 늘려 가며(exponential backoff) 몇 번만 시도한다.
여기서 앞의 멱등성 문제가 다시 나온다. 결제 요청이 타임아웃 났다고 그대로 재시도했는데 첫 요청이 실제로는 처리됐다면 두 번 결제된다. 타임아웃이 났다는 건 결과를 모른다는 뜻이다. 상대 API가 멱등성 키를 지원하는지 확인하고 재시도한다.
오래 걸리는 일은 요청 밖으로 뺀다
가입하면 환영 메일을 보내고 이미지를 올리면 썸네일을 만든다. 매일 밤 리포트를 만드는 일도 있다. 이걸 API 요청 안에서 다 끝내려고 하면 응답이 느려진다. 중간에 실패하면 사용자는 가입이 된 건지 안 된 건지 모르는 에러를 보고, 서버리스 환경이라면 함수 실행 시간 제한에도 걸린다.
사용자가 결과를 바로 볼 필요가 없는 일은 작업 큐에 넣고 응답부터 돌려준다. 큐에 쌓인 작업은 별도의 워커가 꺼내 처리하고, 실패하면 재시도한다. BullMQ(Redis 기반)나 AWS SQS를 쓰거나 Inngest, Trigger.dev 같은 서비스를 쓴다. 처음엔 DB 테이블 하나를 큐처럼 써도 충분하다.
DB 커넥션은 한정돼 있다
DB가 동시에 받을 수 있는 커넥션 수는 정해져 있고, PostgreSQL 기본값은 100개다. 일반 서버는 커넥션 풀을 만들어 몇 개를 돌려 쓰지만 서버리스 함수는 인스턴스마다 새 커넥션을 연다. 트래픽이 몰려 함수가 수백 개 뜨면 DB가 커넥션을 더 받지 못하고 에러를 낸다.
서버리스에서 DB를 쓴다면 앞단에 커넥션 풀러(PgBouncer 등)를 두거나 HTTP로 붙는 서버리스용 드라이버를 쓴다. 쓰고 있는 DB 서비스 문서에서 "serverless"나 "connection pooling"을 찾아보면 대개 권장 설정이 나와 있다.
로그는 나중의 나를 위해 남긴다
로컬에서는 console.log를 찍고 터미널을 보면 됐다. 운영 서버의 로그는 어딘가에 모이고, 문제가 생긴 다음에야 열어 본다. 그때 원인을 찾을 수 있어야 한다.
- 에러를 삼키지 않는다.
catch (e) {}나catch (e) { return null }은 장애가 나도 흔적이 남지 않는다. 그 자리에서 처리할 수 없는 에러라면 로그를 남기고 다시 던진다. - 사용자에게는 "문제가 생겼습니다" 정도만 보여 주고, 로그에는 스택트레이스와 요청 정보까지 남긴다. SQL 에러 메시지를 사용자에게 그대로 보여 주면 테이블 구조까지 알려 주게 된다.
- 요청이 들어올 때 고유한 ID를 만들어 그 요청에서 나오는 로그에 모두 찍는다. 에러 화면에 이 ID를 보여 주면 사용자 문의가 왔을 때 해당 로그를 바로 찾는다.
- 로그는 JSON처럼 구조화해서 찍는다. 문자열로 이어 붙인 로그는 사람만 읽을 수 있지만 구조화된 로그는 필드로 검색하고 집계할 수 있다.
logger.error({ requestId, userId, err }, "order creation failed")
로그에 무엇을 찍으면 안 되는지는 보안 쪽에서 다시 다룬다.
상태코드를 제대로 쓴다
모든 응답을 200으로 내려 주고 body에 success: false를 담는 API가 꽤 많다. 프론트에서는 어차피 body를 보니 상관없어 보인다. 문제는 로드밸런서, 모니터링 도구, CDN, 재시도 로직이 상태코드만 본다는 데 있다. 전부 200이면 에러율 그래프는 늘 0이고, 장애가 나도 알람이 울리지 않는다.
| 코드 | 뜻 | 예 |
|---|---|---|
| 400 | 요청이 잘못됐다 | 필수 값이 빠짐, 형식이 틀림 |
| 401 | 누군지 모른다 | 로그인 안 함, 토큰 만료 |
| 403 | 누군지는 아는데 권한이 없다 | 관리자 기능 호출 |
| 404 | 없다 | 존재하지 않는 리소스 |
| 409 | 현재 상태와 충돌한다 | 이미 가입된 이메일 |
| 429 | 요청이 너무 많다 | 요청 횟수 제한 초과 |
| 500 | 서버 잘못이다 | 처리하지 못한 예외 |
4xx는 클라이언트가, 5xx는 서버가 고쳐야 하는 문제다. 알람은 5xx에 건다.
사용자보다 먼저 알아야 한다
장애를 사용자 문의로 처음 알게 되면 이미 늦었다. 최소한 이 정도는 갖춘다.
- 에러 추적. Sentry 같은 도구를 붙이면 처리되지 않은 예외가 스택트레이스와 함께 모이고 새 에러가 생길 때마다 알림이 온다.
- 헬스체크.
/health같은 엔드포인트를 만들고 외부 모니터링 서비스(UptimeRobot, Better Stack 등)가 1분마다 찔러 보게 한다. 응답이 없으면 알림이 온다. - 기본 지표. 응답 시간, 5xx 비율, DB 커넥션 수, CPU와 메모리 정도는 클라우드 대시보드에 대부분 이미 있다. 평소 값을 알아 둬야 이상한 값을 알아본다.
배포는 되돌릴 수 있어야 한다
배포는 언젠가 실패한다. 이전 버전으로 돌리는 버튼이나 명령이 어디 있는지, 몇 분이 걸리는지 미리 알아 둔다. Vercel이나 Railway 같은 플랫폼은 이전 배포로 바로 돌아가는 기능이 있다.
DB 마이그레이션은 코드처럼 되돌아가지 않는다. 새 스키마 위에서 이전 버전 코드가 돌아도 문제가 없어야 롤백이 되니, 앞에서 마이그레이션을 단계로 나눈 이유가 여기서도 나온다.
금요일 저녁 배포를 피하라는 말은 농담이 아니다. 배포한 뒤 30분쯤은 에러 추적 도구와 지표를 지켜볼 수 있을 때 배포한다.
보안
로그인 다음 단계를 본다. 로그인한 사용자가 보낸 요청을 서버가 어떻게 다뤄야 하는지.
클라이언트에서 온 값은 믿지 않는다
프론트엔드에서 폼 검증을 꼼꼼히 했으니 서버에서는 안 해도 될 것 같다. 하지만 서버로 오는 요청이 우리가 만든 화면에서 왔다는 보장이 없다. 개발자 도구를 열거나 curl 한 줄이면 아무 값이나 보낼 수 있다.
curl -X POST https://example.com/api/orders \
-H "Cookie: sid=..." \
-d '{"productId": 1, "price": 1, "quantity": -5}'
프론트의 검증은 사용자 편의를 위한 것이고 서버의 검증은 시스템을 지키기 위한 것이다. 서버로 들어오는 입력은 모두 타입과 범위를 다시 확인한다. 프론트에서 zod 같은 스키마 라이브러리를 이미 쓰고 있다면 같은 스키마를 서버에서도 쓴다.
const CreateOrder = z.object({
productId: z.number().int().positive(),
quantity: z.number().int().min(1).max(10),
})
const input = CreateOrder.parse(await req.json()) // 형식이 틀리면 여기서 에러, 400으로 응답
위 curl의 price처럼 서버가 이미 아는 값은 클라이언트에서 받지 않는다. 가격은 상품 ID로 DB에서 조회하고 사용자 ID는 세션에서 꺼낸다. 요청 body에 든 userId는 누구든 바꿔 보낼 수 있다.
요청마다 "이 사람 것인가"를 확인한다
처음 백엔드를 만들 때 가장 많이 나오는 보안 사고다.
// GET /api/orders/:id
const order = await db.order.findUnique({ where: { id: params.id } })
return Response.json(order)
로그인 체크는 미들웨어에서 했다. 그런데 누군가 주소의 /api/orders/123을 124로 바꾸면 남의 주문이 보인다. 로그인한 사용자인지만 보고 이 주문이 그 사용자의 것인지는 확인하지 않아서다. 이런 취약점을 IDOR(Insecure Direct Object Reference)라고 부르며, OWASP Top 10에서 첫 번째로 꼽는 "접근 통제 실패"의 대표적인 예다.
조회 조건에 소유자를 같이 넣는다.
const order = await db.order.findFirst({
where: { id: params.id, userId: session.userId },
})
if (!order) return new Response(null, { status: 404 })
남의 주문이어도 403보다는 404를 돌려주는 경우가 많다. 403을 받으면 그 번호의 주문이 있다는 사실은 알게 된다.
수정과 삭제, 목록 API, 파일 다운로드 URL 모두 같은 확인이 필요하다. ID를 UUID로 매기면 추측은 어려워진다. 그래도 ID는 URL이나 공유 링크로 언제든 새어 나가니 권한 확인은 그대로 해야 한다.
버튼을 숨기는 건 보안이 아니다. 관리자가 아니면 "삭제" 버튼을 안 보여 주는 건 화면 처리일 뿐이고, 그 버튼이 부르는 API가 관리자인지 확인하지 않으면 누구나 직접 호출할 수 있다. 권한 확인은 서버에서, 요청마다 한다.
받을 것만 받고, 줄 것만 준다
프로필 수정 API를 이렇게 짜면 편하다.
await db.user.update({ where: { id: session.userId }, data: await req.json() })
화면에는 이름과 소개만 있다. 그런데 요청 body에 "role": "admin"이나 "points": 999999를 끼워 보내면 그것도 같이 저장된다. 이런 걸 mass assignment라고 한다. 바꿔도 되는 필드만 골라서 넘겨야 하는데, 앞의 스키마 검증이 이 일도 해 준다. zod의 z.object는 정의하지 않은 키를 기본으로 버린다.
응답도 마찬가지다.
const user = await db.user.findUnique({ where: { id } })
return Response.json(user) // passwordHash, email, phone까지 전부 나간다
화면에서 이름만 쓰더라도 네트워크 탭을 열면 응답 전체가 보인다. 응답에는 필요한 필드만 담는다. ORM의 select로 처음부터 필요한 컬럼만 가져오는 게 가장 확실하다.
쿼리에 문자열을 이어 붙이지 않는다
db.$queryRawUnsafe(`SELECT * FROM users WHERE email = '${email}'`)
email에 ' OR '1'='1을 넣으면 모든 사용자가 나온다. SQL 인젝션이다. 사용자 입력은 항상 파라미터로 넘긴다.
db.$queryRaw`SELECT * FROM users WHERE email = ${email}` // 태그드 템플릿은 값을 파라미터로 바꿔 준다
ORM의 일반 메서드를 쓰면 대개 안전하다. 위험한 건 ORM으로 표현하기 어려운 쿼리를 raw SQL로 쓸 때라서, 이름에 Unsafe나 raw가 붙은 메서드에 사용자 입력이 들어가는지 확인한다. 정렬 기준처럼 컬럼 이름을 사용자 입력으로 받아야 하면 파라미터로는 안 되니, 허용할 컬럼 목록을 정해 두고 그 안에 있는지 본다.
비밀 키는 코드와 번들 밖에 둔다
DB 비밀번호, 결제 API 키, JWT 서명 키는 코드에 직접 적지 않고 환경 변수로 넣는다. .env 파일은 .gitignore에 넣는다. 실수로 커밋했다면 파일을 지워도 git 히스토리에 남아 있으니 키를 새로 발급해서 교체한다. 공개 저장소라면 몇 분 안에 봇이 긁어 간다.
프론트엔드 개발자가 특히 조심할 곳이 있다. Next.js의 NEXT_PUBLIC_, Vite의 VITE_처럼 접두사가 붙은 환경 변수는 빌드할 때 자바스크립트 번들에 그대로 들어가서 누구나 브라우저에서 볼 수 있다. 여기에는 공개돼도 괜찮은 값만 넣는다.
로그로도 비밀이 샌다. 요청 body나 헤더를 통째로 찍으면 비밀번호와 토큰이 같이 남는다. 로그는 여러 사람이 보고 외부 수집 서비스로도 넘어가니, 민감한 필드는 남기기 전에 가린다. 로깅 라이브러리 대부분에 이런 기능(redact)이 있다.
CORS는 서버를 지켜 주지 않는다
프론트엔드 개발자가 가장 자주 만지는 서버 설정이 CORS다 보니 CORS를 보안 장치로 여기기 쉽다. CORS는 다른 사이트의 스크립트가 우리 API 응답을 읽어도 되는지를 브라우저가 판단하는 규칙이다. curl이나 다른 서버에서 보내는 요청은 CORS와 상관없이 그대로 들어온다.
"CORS를 우리 도메인으로 막았으니 안전하다"는 말은 그래서 성립하지 않는다. API를 지키는 건 인증과 권한 확인이다. 반대로 CORS 에러가 귀찮다고 요청의 Origin을 검사 없이 그대로 돌려주면서 Access-Control-Allow-Credentials: true까지 걸면, 아무 사이트나 로그인한 사용자의 권한으로 API 응답을 읽어 갈 수 있다. 허용할 출처는 목록으로 고정한다.
요청 횟수와 크기에 상한을 둔다
제한이 없는 API는 누가 마음먹으면 얼마든지 두드릴 수 있다. 로그인 API에는 비밀번호 대입이 들어오고, 회원가입 API에는 봇이 몰린다. 인증 문자 발송 API가 제일 아프다. 문자는 건당 돈이 나가서 하룻밤 사이에 청구서가 쌓인다.
LLM API를 서버에서 대신 불러 주는 기능이라면 더 위험하다. 인증 없이 열어 둔 엔드포인트 하나가 남들의 무료 LLM 프록시가 되고, 토큰 비용은 내 카드로 나간다.
- IP나 사용자 단위로 요청 횟수를 제한하고(rate limit), 넘으면 429를 돌려준다.
- 문자, 메일, LLM처럼 호출마다 돈이 드는 기능은 사용자별 하루 한도를 따로 둔다.
- 요청 body와 업로드 파일 크기에 상한을 둔다.
- 클라우드 계정에 예산 알림을 걸어 둔다. 사고가 나도 한 달 뒤 청구서보다 먼저, 그날 안에 알 수 있다.
Cloudflare 같은 CDN이나 API 게이트웨이를 앞에 두면 상당 부분을 설정만으로 처리할 수 있다.
업로드 파일
사용자가 올리는 파일은 사용자 입력 중에서도 다루기 까다롭다.
- 확장자와
Content-Type은 클라이언트가 정하는 값이라 믿을 수 없다. 이미지만 받는다면 서버에서 실제로 이미지로 열어 보거나 다시 인코딩한다. - 파일 이름을 그대로 저장 경로에 쓰지 않는다.
../../etc/passwd같은 이름이 들어올 수 있으니 저장할 때는 서버가 UUID 같은 새 이름을 붙인다. - 업로드된 파일은 서비스와 다른 도메인에서 내려준다. 사용자가 올린 HTML이나 SVG가 우리 도메인에서 열리면 그 안의 스크립트가 우리 사이트 권한으로 실행된다. S3 같은 스토리지의 도메인을 그대로 쓰면 자연스럽게 해결된다.
의존성도 내 코드다
npm install 한 번에 수백 개의 패키지가 들어온다. 그 코드는 내 서버에서 내 DB 비밀번호를 들고 실행된다.
- lock 파일(
package-lock.json등)을 커밋해서 모든 환경에 같은 버전이 깔리게 한다. - Dependabot이나
npm audit으로 알려진 취약점이 있는 패키지를 확인한다. - 이름이 비슷한 가짜 패키지를 조심하고, 별로 쓰이지 않는 패키지는 들이기 전에 한 번 더 본다. 몇 줄이면 직접 짤 수 있는 기능이라면 패키지를 안 쓰는 것도 방법이다.
체크리스트
DB
- 중복, 빈 값, 범위 같은 규칙은
UNIQUE,NOT NULL,CHECK, 외래 키로 DB에 건다. ORM이라면 마이그레이션 SQL에 실제로 들어갔는지 본다. - 함께 성공하거나 함께 실패해야 하는 작업은 트랜잭션으로 묶는다. 트랜잭션 안에서 외부 API를 부르지 않는다.
- 읽은 값으로 다시 쓰는 코드는 동시 요청에서 깨진다. 쿼리 하나로 합치거나 행을 잠근다.
- 두 번 처리되면 안 되는 요청은 멱등성 키로 막는다.
- 쿼리 로그로 N+1을 확인하고, 느린 쿼리는
EXPLAIN ANALYZE로 보고 인덱스를 건다. - 목록 API에는 개수 제한과 페이지네이션을 넣는다.
- 돈은 정수나
NUMERIC으로, 시간은 UTC(timestamptz)로 저장한다. - 스키마 변경은 이전 버전 코드와 호환되게 단계를 나눈다. 백업은 복구까지 해 본다.
인프라
- 서버는 상태를 들고 있지 않는다. 세션은 Redis나 DB에, 파일은 오브젝트 스토리지에 둔다.
- 로컬, 스테이징, 운영의 DB를 나눈다.
- 외부 호출에는 타임아웃을 걸고, 재시도는 간격을 늘려 가며 멱등한 요청에만 한다.
- 오래 걸리는 일은 작업 큐로 뺀다.
- 서버리스라면 DB 커넥션 풀러를 쓴다.
- 에러는 삼키지 않고, 로그는 요청 ID와 함께 구조화해서 남긴다.
- 상태코드를 뜻대로 쓰고, 5xx에 알람을 건다.
- 에러 추적, 헬스체크, 기본 지표를 갖추고, 롤백 방법을 미리 안다.
보안
- 모든 입력은 서버에서 다시 검증한다. 가격이나 사용자 ID처럼 서버가 아는 값은 받지 않는다.
- 모든 요청에서 이 리소스가 이 사용자의 것인지 서버가 확인한다.
- 바꿔도 되는 필드만 받고, 보여 줘도 되는 필드만 응답한다.
- SQL에는 사용자 입력을 파라미터로 넘긴다.
- 비밀 키는 git, 프론트 번들, 로그에 남기지 않는다.
- CORS는 허용 출처를 목록으로 고정하고, API는 인증과 권한 확인으로 지킨다.
- 요청 횟수와 크기, 돈이 드는 호출에 상한을 둔다.
- 업로드 파일은 내용을 확인하고, 새 이름으로 저장하고, 다른 도메인에서 내려준다.
- lock 파일을 커밋하고 의존성 취약점 알림을 켠다.
참고 자료
- OWASP Top 10 – 웹 애플리케이션 보안 위험 목록
- OWASP Cheat Sheet Series – 인가, 입력 검증, 파일 업로드, 로깅 항목
- Use The Index, Luke – 개발자 관점에서 SQL 인덱스를 설명한 무료 책
- Stripe API: Idempotent requests – 멱등성 키를 실제로 어떻게 쓰는지