코드 한 줄

3분기 회고: 느리게, 그러나 꾸준히

윤서 — Sat, 26 Sep 2026 17:12:42 +0900

분기마다 한 번씩 회고를 쓴다. 이번 분기의 주제는 속도였다. 서비스를 빠르게, 그리고 나는 조금 느리게.

한 일

목표	결과	상태
주문 페이지 1초 이내	평균 0.16초	달성
복원 훈련 분기 1회	1회	달성
모바일 화면 개편	70%	진행 중
블로그 월 4편	월 3편	아쉬움

하지 않기로 한 일

주말 배포. 월요일 아침에 사고를 수습하는 건 이제 그만.
새 프레임워크 도입. 지금 것으로 충분하다.
알림 전부 켜 두기. 정말 중요한 알림만 남겼다.

더 많이 하지 말고, 덜 망가지게.
이번 분기 책상 메모

다음 분기

모바일 화면 개편 마무리
접근성 점검 10항목 모두 통과
필진 한결 님과 연재 하나 시작

읽어 주셔서 고맙습니다. 궁금한 점은 방명록에 남겨 주세요.

좋은 에러 메시지는 무엇을 말해야 할까

한결 — Mon, 21 Sep 2026 14:48:42 +0900

"알 수 없는 오류가 발생했습니다." 이 문장을 볼 때마다 사용자는 무력해진다. 좋은 에러 메시지는 세 가지를 말한다.

무엇이 안 됐는지
왜 안 됐는지 (알 수 있다면)
그래서 어떻게 하면 되는지

나쁜 예	좋은 예
오류가 발생했습니다.	사진을 올리지 못했습니다. 파일이 10MB를 넘습니다. 크기를 줄여 다시 올려 주세요.
잘못된 입력입니다.	전화번호는 숫자만 입력해 주세요. 예: 01012345678

throw new UserError( '사진을 올리지 못했습니다. 파일이 10MB를 넘습니다.', hint: '크기를 줄여 다시 올려 주세요.' );

개발자에게 필요한 정보(스택, 요청 번호)는 로그에 남기고, 사용자에게는 다음 행동만 알려 주자.

사용자 천 명이 되던 날

윤서 — Thu, 17 Sep 2026 17:12:42 +0900

가입자 수가 1,000을 넘었다. 대단한 숫자는 아니지만 둘이서 퇴근 후에 만든 서비스로는 꽤 멀리 왔다.

지표	석 달 전	지금
가입자	312	1,004
주간 활성 사용자	88	341
월 서버비	1만 8천 원	3만 2천 원
받은 문의	14건	96건

잘한 것

문의에는 하루 안에 답했다.
매주 금요일에 바뀐 점을 짧게 공지했다.
기능보다 속도를 먼저 챙겼다.

아쉬운 것

모바일 화면을 너무 늦게 다듬었다.
결제 기능을 서두르다 한 달을 버렸다.

천 명 중 한 명이 보낸 긴 메일이, 천이라는 숫자보다 오래 남는다.

다음 목표는 숫자가 아니라 속도다. 모든 페이지를 0.3초 안에.

다크 모드, 색만 뒤집으면 끝일까

한결 — Wed, 09 Sep 2026 19:36:42 +0900

다크 모드를 처음 만들 때 흰색을 검은색으로, 검은색을 흰색으로 바꾸면 된다고 생각했다. 결과는 눈이 아픈 화면이었다. 순수한 검정 위의 순수한 흰 글자는 대비가 너무 세다.

색은 변수로, 뜻은 이름으로

:root { --bg: #ffffff; --text: #1a1d23; --muted: #69717e; --line: #e8eaee; } @media (prefers-color-scheme: dark) { :root { --bg: #15171c; --text: #e6e8ec; --muted: #9aa2ae; --line: #2a2e36; } }

놓치기 쉬운 것

버튼 호버 색도 다크용으로 따로
그림자는 다크에서 거의 안 보인다. 테두리로 대신
흰 배경 로고 이미지
사용자가 고른 모드를 기억하기

color-scheme: light dark; 를 선언하면 스크롤바와 입력칸도 알맞은 색으로 바뀝니다.

결국 다크 모드는 색을 뒤집는 일이 아니라, 색마다 역할을 정해 두는 일이었다.

Nginx 설정 몇 줄로 첫 화면을 빠르게

윤서 — Sat, 05 Sep 2026 22:00:42 +0900

서버 코드만 빨라서는 부족하다. 정적 파일이 느리면 첫 화면이 늦게 뜬다. Nginx 설정에서 효과가 컸던 것만 모았다.

gzip on; gzip_types text/css application/javascript image/svg+xml application/json; location ~* \.(css|js|woff2|jpg|png|webp)$ { expires 30d; add_header Cache-Control "public, immutable"; } listen 443 ssl http2;

지표	전	후
첫 화면 표시	2.4초	1.1초
전송량	1.8MB	640KB

파일 이름에 버전이나 해시를 붙이지 않고 immutable 캐시를 걸면, 배포 뒤에도 옛 파일이 보입니다.

출시 전에 보는 접근성 체크리스트

한결 — Mon, 31 Aug 2026 12:24:42 +0900

접근성은 특별한 사람을 위한 기능이 아니다. 팔을 다친 사람, 햇빛 아래에서 휴대폰을 보는 사람, 모두가 언젠가는 쓴다. 출시 전에 보는 목록을 공유한다.

모든 이미지에 알맞은 대체 텍스트
키보드만으로 모든 기능 사용 가능
초점 표시가 보인다
글자와 배경 대비 4.5:1 이상
버튼과 링크의 이름이 뜻을 말한다
입력칸마다 label 연결
오류 메시지가 색에만 의존하지 않는다
확대 200%에서 가로 스크롤 없음
동영상 자막
화면 낭독기로 한 번 훑어보기

도구	용도
브라우저 개발자 도구	대비 · 접근성 트리 확인
화면 낭독기	실제 사용 흐름 확인
키보드	Tab, Shift+Tab, Enter, Esc 만으로 써 보기

접근성 점검의 절반은 마우스를 치우는 것으로 끝난다.

OPcache 설정, 기본값으로 두지 마세요

윤서 — Thu, 27 Aug 2026 14:48:42 +0900

쿼리를 고치고 나니 이번에는 PHP 자체가 보였다. 서버에 OPcache가 켜져 있긴 했지만 기본값 그대로였다. 파일 수가 많은 프레임워크에서는 기본 메모리가 금방 찬다.

opcache.enable=1 opcache.memory_consumption=256 opcache.interned_strings_buffer=32 opcache.max_accelerated_files=20000 opcache.validate_timestamps=1 opcache.revalidate_freq=60

확인하는 법

opcache_get_status() 로 캐시 적중률과 남은 메모리를 본다.
적중률이 99% 아래라면 메모리나 파일 수 한도를 늘린다.
배포 직후에는 FPM을 다시 불러와 캐시를 비운다.

항목	기본값	바꾼 값
memory_consumption	128	256
max_accelerated_files	10000	20000
캐시 적중률	96.2%	99.8%

응답 시간 평균이 210ms에서 160ms로 더 내려갔다. 코드 한 줄 안 건드리고 얻은 25%.

백업은 복원해 봐야 백업이다

윤서 — Sat, 22 Aug 2026 17:12:42 +0900

매일 밤 백업이 돌고 있었다. 그런데 한 번도 복원해 본 적이 없었다. 불안해서 주말에 새 서버를 하나 빌려 복원 훈련을 했다. 결과는 반쯤 실패였다.

발견한 문제

DB 덤프에 트리거가 빠져 있었다.
첨부 파일 백업이 권한 문제로 절반만 복사되고 있었다.
복원 절차를 아는 사람이 나 하나뿐이었다.

# 고친 백업 명령 mysqldump --single-transaction --routines --triggers mydb | gzip > db-$(date +%F).sql.gz tar --exclude='files/cache' -czf files-$(date +%F).tar.gz files

석 달에 한 번, 다른 서버에 실제로 복원해 보는 일정을 달력에 넣어 두었습니다.

복원 훈련을 한 뒤로 새벽 알림이 와도 덜 무섭다. 최악의 경우에도 어디까지 되돌릴 수 있는지 알기 때문이다.

커밋 메시지, 미래의 나에게 쓰는 편지

윤서 — Tue, 18 Aug 2026 19:36:42 +0900

"수정", "버그 고침", "ㅇㅇ". 석 달 전 내가 남긴 커밋 메시지다. 왜 고쳤는지 알 수 없어서 같은 버그를 두 번 고쳤다.

지키기로 한 규칙

첫 줄은 무엇을 바꿨는지 50자 안쪽으로
본문에는 왜 바꿨는지
관련 이슈 번호는 끝에

주문 목록 N+1 쿼리를 IN 조회로 바꿈 주문 200개 기준 쿼리가 201회에서 2회로 줄어 평균 응답이 1.8초에서 0.2초가 됨. 문의 #128

코드는 무엇을 하는지 말하고, 커밋은 왜 했는지 말한다.

N+1 쿼리를 한 번에 잡기

윤서 — Fri, 14 Aug 2026 22:00:42 +0900

지난 편에서 찾은 범인은 이런 코드였다. 주문 목록을 가져온 뒤, 주문마다 상품을 다시 조회한다.

foreach ($orders as $order) { // 주문마다 쿼리 한 번씩: 주문 200개면 쿼리 200번 $order->items = $db->query('SELECT * FROM order_items WHERE order_id = ?', [$order->id])->fetchAll(); }

IN 으로 한 번에 가져오기

$ids = array_column($orders, 'id'); $marks = implode(',', array_fill(0, count($ids), '?')); $rows = $db->query("SELECT * FROM order_items WHERE order_id IN ($marks)", $ids)->fetchAll(); $byOrder = []; foreach ($rows as $row) { $byOrder[$row->order_id][] = $row; } foreach ($orders as $order) { $order->items = $byOrder[$order->id] ?? []; }

결과

	고치기 전	고친 뒤
쿼리 수 (주문 200개)	201회	2회
평균 응답	1,840ms	210ms
최대 응답	5,210ms	380ms

IN 목록이 수천 개가 넘으면 오히려 느려질 수 있습니다. 페이지 단위로 나눠 가져오세요.

코드 열 줄 남짓 바꿨을 뿐인데 체감이 완전히 달라졌다. 메일을 보내 준 사용자에게 답장을 쓰면서 가장 뿌듯했던 순간.

키보드를 바꿨더니 코드가 달라졌다

윤서 — Fri, 07 Aug 2026 00:24:42 +0900

오 년 쓴 노트북 키보드를 떠나 기계식 키보드를 샀다. 타건감이 좋으니 코드도 잘 써질 거라는 기대가 있었다.

나무 책상 위의 새 키보드

항목	느낌
타건감	좋다. 오래 쳐도 손끝이 덜 아프다
소음	생각보다 크다. 밤에는 조심
생산성	변화 없음. 당연하다

결론은 이렇다. 장비는 기분을 바꾸고, 기분은 앉아 있는 시간을 늘린다. 그 정도면 충분히 좋은 투자다.

느린 페이지는 어디서 느린가

윤서 — Fri, 31 Jul 2026 19:36:42 +0900

사용자 한 분이 "주문 내역 페이지가 가끔 5초씩 걸려요"라는 메일을 보냈다. 로컬에서는 0.3초. 이런 문제는 대개 추측으로 고치려다 시간을 버린다. 이번에는 재는 것부터 시작했다.

1. 느린 요청부터 모은다

PHP-FPM의 슬로우 로그를 켜면 일정 시간 넘게 걸린 요청의 호출 스택을 남겨 준다. 설정은 두 줄이면 된다.

; /etc/php/8.1/fpm/pool.d/www.conf request_slowlog_timeout = 2s slowlog = /var/log/php-fpm/slow.log

하루 동안 모아 보니 느린 요청의 90%가 같은 함수에서 멈춰 있었다. 주문 목록을 돌면서 상품 정보를 하나씩 가져오는 곳이다.

2. 숫자로 확인한다

측정 지점	평균	최대
전체 요청	1,840ms	5,210ms
DB 쿼리 합계	1,520ms	4,800ms
템플릿 렌더링	95ms	160ms
나머지	225ms	250ms

평균만 보면 안 됩니다. 사용자가 느끼는 건 최댓값과 상위 5%입니다.

3. 범인은 반복문 속 쿼리

주문이 많은 사용자일수록 느렸다. 전형적인 N+1 문제다. 다음 편에서 이걸 어떻게 한 번의 쿼리로 줄였는지 적는다.

측정하지 않은 최적화는 기도와 같다.
어느 개발자의 책상 메모

첫 장애의 밤

윤서 — Thu, 23 Jul 2026 22:00:42 +0900

서비스를 연 지 석 달째 되던 날 새벽 두 시, 모니터링 알림이 울렸다. 사이트가 열리지 않는다. 침대에서 노트북을 열었을 때 손이 떨렸다.

타임라인

시각	일
02:04	응답 없음 알림
02:09	SSH 접속, 디스크 100% 확인
02:15	원인: 로그 파일 38GB
02:18	오래된 로그 압축 · 정리, 서비스 복구
02:40	로그 순환 설정 추가

로그 순환(logrotate)을 설정하지 않은 로그는 언젠가 반드시 디스크를 채웁니다.

배운 것

디스크 사용량 80% 알림 추가
애플리케이션 로그 순환 설정
장애 대응 절차 문서화
두 번째 담당자 정하기

장애는 기술 문제이기 전에 준비의 문제였다.

복구 뒤 공지를 올리고 잠들었더니 아침에 사용자 몇 분이 "고생하셨어요"라고 댓글을 달아 주셨다. 작은 서비스의 가장 큰 힘은 이런 사람들이다.

새 노트북에 개발 환경을 옮기며 정리한 것

윤서 — Tue, 14 Jul 2026 22:00:42 +0900

노트북을 바꾸면서 개발 환경을 옮기는 데 하루가 걸렸다. 다음에는 한 시간 안에 끝내려고 설치 목록과 설정을 저장소 하나에 모았다.

패키지 목록을 파일 하나로
셸 설정 · 별칭 저장소에 보관
편집기 설정 동기화
SSH 키는 새로 만들고 옛 키 폐기
로컬 DB 샘플 데이터 스크립트

#!/usr/bin/env bash set -e xargs -a packages.txt sudo apt-get install -y ln -sf "/.bashrc" ~/.bashrc ln -sf "/.gitconfig" ~/.gitconfig echo '준비 끝'

이 글을 쓰고 나서 동료에게 저장소를 보여 줬더니, 자기 것도 만들겠다며 가져갔다.