개발을 하다 보면 이런 경험이 한 번쯤 있을 것 같다.
분명히 코드는 맞는 것 같고, GPT, 구글, 스택오버플로우도 뒤졌는데 해결이 안되는 경우. 그러다 몇 시간 뒤에 알고 보면 너무 단순한 이유였던 경우.
실수는 실력과 무관하게 반복될 수 있다는 걸, 개발하면서 점점 실감하게 된다.
이런 상황을 줄여주는 게 체크리스트다.
왜 체크리스트일까
항공이나 의료 분야에서는 체크리스트가 이미 표준으로 자리 잡혀 있다. 실수나 문제가 발생하는건 전문가가 몰라서가 아니라, 명시적으로 점검하지 않으면 당연히 됐겠지하고 넘어가기 때문이라고 한다.
개발도 비슷한 것 같다. 단 한 줄의 점검이 몇 시간의 삽질을 막아줄 수 있다.
막막할 때 꺼내볼 체크리스트
1. 운영체제를 재시작해봤는가?
생각보다 재시작 한 번으로 해결되는 경우가 생각보다 많다. (서버는 예외입니다 허허)
포트가 이미 사용 중이라는 오류, 환경변수를 분명히 설정했는데 인식이 안 되는 경우, 데몬이 떠 있어야 하는데 안 떠 있는 경우 등이 대표적이다. IDE나 터미널을 껐다 켜는 것만으로도 해결되는 경우도 있다. 원인을 찾기 전에 재시작부터 한 번 해보는 게 오히려 빠를 때가 있다.
2. 지금 보고 있는 코드와 실제 실행 중인 코드가 같은가?
빌드를 안 했거나 배포가 안 됐거나 다른 서버를 보고 있는 경우.
특히 서버 환경에서는 코드를 수정하고 저장했더라도 빌드·배포 과정을 거치지 않으면 변경사항이 반영되지 않는다.
로컬에서 핫리로드에 익숙해져 있으면 더 놓치기 쉽다. 배포 파이프라인이 정상적으로 돌았는지, 실행 중인 프로세스가 최신 빌드를 바라보고 있는지 확인해보는 게 좋다.
3. 환경 설정 파일에 한글이 들어가 있지는 않은가?
아직 한글을 제대로 처리하지 못하는 프로그램들이 있다.
application.yml이나 .env 같은 설정 파일에 한글 주석이나 경로가 포함되어 있으면, 일부 환경에서 파일 자체를 읽지 못하거나 파싱 오류가 발생할 수 있다. 특히 Windows 환경에서 개발하다가 Linux 서버에 올릴 때 이 문제가 불거지는 경우가 있다. 경로, 파일명, 환경변수 키 등 주요 네이밍에는 처음부터 한글을 쓰지 않는 게 나중에 편하다.
4. 대소문자 또는 공백 문자 문제는 아닌가?
userId와 userid는 다르고, "test"와 "test "도 다르다.
JSON 키나 API 파라미터를 다룰 때, 헤더 이름이나 쿼리 파라미터를 직접 입력할 때 이 실수가 자주 발생한다. 특히 공백 문자는 눈으로 보면 구분이 안 되기 때문에 더 찾기 어렵다. Postman이나 curl로 직접 요청을 보내보면서 값을 하나씩 확인하거나, 코드에서 값을 출력해 길이까지 같이 찍어보면 빠르게 잡을 수 있다. DB 컬럼명이나 테이블명도 대소문자를 구분하는 DB가 있으니 주의가 필요하다.
5. OS, 언어 버전, 라이브러리, 프레임워크 버전이 서로 맞는가?
특정 버전에는 특정 함수가 없거나, 동작이 다를 수 있다.
예를 들어 Java 17에서 되는 문법이 Java 11에서는 안 된다거나, 라이브러리 메이저 버전이 올라가면서 기존 API가 deprecated되거나 제거되는 경우가 있다. 로컬에서는 잘 되는데 서버에서만 안 된다면 이 부분을 가장 먼저 의심해보는 편이다. java -version, node -v, pip show 같은 명령어로 환경을 빠르게 확인할 수 있다. 버전은 프로젝트 시작 시점에 팀원 간에 맞춰두고, .nvmrc나 .java-version 같은 파일로 명시해두면 나중에 훨씬 수월하다.
6. 네트워크 연결은 정상인가?
코드 문제가 아니라 네트워크 문제인 경우, 코드를 아무리 봐도 원인을 찾기 어렵다.
방화벽 규칙, 보안 그룹 설정, VPN 연결 여부, 인바운드/아웃바운드 포트 허용 여부 등을 확인해볼 필요가 있다. AWS를 쓴다면 EC2 보안 그룹이나 RDS 인바운드 규칙이 막혀 있는 경우가 꽤 있다. ping, telnet, curl 명령어로 대상 호스트와 포트까지 연결이 되는지 먼저 확인해보는 습관이 도움이 된다. 연결 자체가 안 된다면 코드보다 인프라 설정을 먼저 살펴봐야 한다.
7. 캐릭터 인코딩 문제는 아닌가?
한글이 깨지거나, 특수문자가 이상하게 표시된다면 인코딩 문제일 가능성이 높다.
가능하면 모든 구간을 UTF-8로 통일해두는 걸 권장한다. WAS, DB 커넥션 설정, IDE 파일 인코딩, 편집기 설정까지 전부. MySQL이라면 character_set_server=utf8mb4로 설정하고, JDBC URL에도 characterEncoding=UTF-8을 명시하는 식이다. 한 군데라도 인코딩이 다르면 특정 환경에서만 깨지는 현상이 발생하고, 어디서 깨지는지 추적하는 게 꽤 번거로워진다. 프로젝트 초반에 한 번 쭉 맞춰두는 게 가장 좋다.
8. 해당 시스템의 로그를 확인했는가?
내가 작성한 코드만 실행되는 게 아니다. 프레임워크, 미들웨어, 인프라도 전부 로그를 남긴다.
에러 메시지가 있다면 첫 줄만 보지 말고 스택 트레이스 전체를 읽어보는 게 좋다. 실제 원인은 중간이나 아래쪽에 있는 경우도 많다. Spring이라면 Caused by: 이하를 주의 깊게 보고, 서버 로그나 DB 슬로우 쿼리 로그, nginx 접근 로그 등 내가 직접 작성하지 않은 시스템의 로그도 같이 확인해보면 원인을 찾는 시간이 많이 줄어든다.
마치며
사람이라면 누구나 놓칠 수 있는 것이기에 명시적으로 점검하기 위해선 체크리스트를 만들어 점검하는게 중요하다고 생각한댜