00 | 참고자료
[KREW INSIDE] 신입 개발자의 좌충우돌 문제 해결기
01 | 참고자료 내용 정리
0. Troubleshooting 가이드 톺아보기
시작하며
Troubleshooting이란?
: 문제가 발생했을 때 그 원인을 규명하고 문제를 복구하는 일련의 작업을 의미. 개발 중에 발생할 수 있는 다양한 문제와 그 해결 방법을 체계적으로 정리한 것이 Troubleshooting 가이드이다다. 이러한 가이드는 내부 및 외부 개발자 모두에게 유용한 자료가 된다.
- 내부 개발자에게는 반복적인 문제 해결과 리소스 관리에 큰 도움이 됨
- 외부 개발자 입장에서도 쉽게 해결책을 찾아 빠르게 문제를 해결할 수 있게 도와줌
따라서 Troubleshooting 가이드는 문제를 신속히 해결할 수 있도록 돕는 필수적인 문서이다.
💥Troubleshooting 가이드의 중요성
특정 문제에 대해 여러 번 동일한 답변을 반복하거나, 같은 내용의 문서를 여러 개발자가 각각 작성하는 경우가 발생할 수 있다. 이러한 반복 작업은 개발자들의 본래 일정에 차질을 줄 뿐만 아니라, 효율적인 리소스 관리에도 부담을 준다.
만약 오류 상황과 해결 방법을 한데 모아 정리해둔 문서가 있었다면, 고객 지원(CS) 처리에 필요한 리소스를 크게 줄일 수 있었을 것이다.
→ 이러한 필요성에서 Troubleshooting 가이드의 중요성이 부각됨.
Troubleshooting 가이드 구성 요소
오류 상황을 나타내는 ⓵오류 코드 혹은 오류 메시지, ⓶문제 원인 및 증상, ③해결책으로 구성.
각각의 구성 요소를 나타내는 세부 방법은 회사별로 조금씩 다를 수 있지만, 대부분 구성 요소는 비슷하다
오류 코드
: 오류 코드는, 오류 발생 상황을 세 자리 숫자 코드로 정리한 것이다.일반적으로 오류 코드는 400, 401과 같은 HTTP 상태코드로 표기. HTTP 상태코드의 첫 번째 숫자는 응답의 클래스를 정의한다. 하지만 HTTP 상태코드가 아닌 다른 방식으로도 오류 코드가 존재할 수도 있는데요. 예를 들어 400번 대나 500번 대에 해당하지 않는 오류가 발생했다면, 상황에 맞게 KIE001와 같은 고유한 오류 코드를 새로 정의하기도 한다.
| 분류 | 설명 |
|---|---|
| 1xx (정보) | 요청을 받았으며 프로세스를 계속 진행 |
| 2xx (성공) | 요청을 성공적으로 받았으며 인식했고 수용함 |
| 3xx (리다이렉션) | 요청 완료를 위해 추가 작업 조치가 필요 |
| 4xx (클라이언트 오류) | 요청의 문법이 잘못되었거나 요청을 처리할 수 없음 |
| 5xx (서버 오류) | 서버가 명백히 유효한 요청에 대해 충족을 실패 |
-
오류 메시지: 상황에 따라 오류 코드와 함께 문장 형식으로 오류를 정의하기도 하며, 이를 오류 메시지라고 한다.
오류 메시지는 해당 오류를 쉽고 빠르게 이해하고 해결하는 데 목적이 있으므로, 최대한 쉽고 간결하게 쓰는 것이 좋다. 이때 중요한 점은 오류 메시지를 읽는 독자가 개발자, 운영 담당자, IT 부서 직원, 최종 사용자 등이 될 수 있다고 가정하고 오류에 대응할 수 있도록 메시지를 작성해야 한다.
또한 개발자들은 오류 메시지를 그대로 복사하여 검색하려는 경향이 있기 때문에, Troubleshooting 가이드에서도 화면에 표시되는 오류 메시지를 그대로 인용하는 것이 좋다.
-
원인/증상: 문제를 해결하기 전에 문제 원인이나 증상을 명확하게 파악하는 것 또한 문제 해결만큼이나 중요한 항목이다다. 따라서 Troubleshooting 가이드에 오류 코드나 오류 메시지뿐만 아니라 독자에게 명확한 문제 상황을 안내하는 것이 더 근본적인 문제 해결에 도움이 될 것이다다. 또한 개발 환경 등에 따라 동일 오류가 다른 증상으로 나타날 수도 있기 때문에, 해당 증상들을 정확하게 문서화하는 작업도 필요하다.
-
해결책: Troubleshooting 가이드의 최종 목적은 결국 문제 상황의 해결이므로, 해결책 부분이 가장 중요한 항목이라고도 볼 수 있다. 가장 중요한 항목인 만큼 해결 방안을 정확하고 명확하게 안내하여 독자가 문제를 해결할 수 있도록 도와야 한다. 넘버링 등으로 사용자가 취해야 하는 액션을 안내하거나 실제 코드를 제시하는 것도 좋은 방법이다. 또한 독자가 다시 작업해야 하는 부분이 있다면 관련 문서에 링크를 연결하는 방법도 생각해 볼 수 있다.
Troubleshooting 가이드 작성 Tip
-
정확한 원인을 파악하도록 도와라
아마 오류 상황을 마주한 개발자가 가장 궁금한 것은 해당 오류가 왜 발생했는지 그 원인일 것이다. 실제로 똑같은 증상임에도 상황과 환경에 따라 그 원인이 달라지기도 한다. 원인이 다르면 당연히 해결 방법도 달라지기 때문에 독자로 하여금 문제의 원인을 정확하게 파악하도록 돕는 것이 중요하다. 이를 위해 문제에 대한 다양한 상황을 제공하여 독자가 본인의 상황에 해당하는 부분을 따라가도록 유도한다. 또한 진단 테스트 방법 등을 안내하여 여러 가지 경우를 테스트하여 오류의 원인을 더 명확하게 파악하도록 할 수도 있다.
-
다양한 케이스를 제공하라
개발 중 발생하는 오류는 정말 다양하다. 증상이 같지만 원인이 다른 경우도 있고 같은 오류 메시지가 나타난 경우라도 서비스에 따라 그 해결 방법이 다르기도 하다. Troubleshooting 가이드에는 가능한 이런 경우들을 최대한 고려하여 문서화하는 것이 중요하다. 처음부터 모든 오류 케이스들을 제시하는 것이 어려울 수 있지만, 오류 관련 CS가 들어올 때마다 지속적인 문서화와 업데이트를 통해 보다 풍부한 Troubleshooting 가이드를 작성할 수 있다.
-
링크를 활용하라
Troubleshooting 가이드는 다른 가이드와는 달리 처음부터 끝까지 읽을 필요가 없다. 본인이 마주한 특정한 오류에 대한 정보를 빠르게 찾는 것이 중요하다.
가이드 내에 링크 연결을 활용하면 독자가 필요한 정보를 빠르게 찾을 수 있도록 도울 수 있다. 가이드 상단에 테이블 혹은 목차 형태로 링크 연결을 제공하면 원하는 부분으로 바로 이동할 수 있어 편리하다. 또한 어떤 작업을 다시 해야 한다면, Troubleshooting 가이드에 모든 시퀀스를 적기보다는 해당하는 문서로 이동하여 작업을 수행할 수 있도록 링크 연결로 안내하는 것 역시 좋은 방법이다다.
-
잘 보이는 곳에 위치시켜라
개발 중 오류가 발생했는데 'Troubleshooting 가이드가 어디 있지?' 하고 기술문서 사이트를 이리저리 살펴본 경험이 있는가? 일부 문서 사이트에서는 Troubleshooting 가이드가 잘 보이지 않는 곳에 있어서 독자들이 Troubleshooting 가이드를 신속히 찾을 수 없는 상황이 발생한다. 시급히 오류 상황을 해결해야 하는 개발자 입장에서 이렇게 Troubleshooting 가이드가 안 보이는 곳에 숨어 있다면 여간 불편하지 않을 수 없다. 따라서 Troubleshooting 가이드를 잘 보이는 곳에 위치시키고, 또한 본문 중간에 Troubleshooting 가이드에 대한 링크를 안내 메시지 등으로 제공하는 것도 하나의 팁이 될 수 있을 것이다다.
02 | 트러블슈팅 템플릿 및 트러블 슈팅 가이드 템플릿 만들기
제목 : [서비스명/기능명/문제명] 프로젝트 - 번호
1. 문제 개요
- 오류 상황: 문제 발생 상황과 영향 범위 (예: 특정 코드 실행 시 발생, 특정 라이브러리 버전 호환 문제 등)
- 발생 배경: 문제를 접하게 된 상황 또는 초기 문제 발견 경위 (예: 코드 테스트 중, 배포 중 문제 발견 등)
2. 오류 코드 및 오류 메시지
- 오류 코드: 발생한 오류 코드 또는 HTTP 상태코드(예: 404, 500 등)
- 오류 메시지: 화면이나 로그에 출력된 구체적인 오류 메시지 (에러 복사 가능하도록 작성)
- 관련 로그: 에러 로그를 분석하는 데 필요한 구체적인 로그 (예: 에러 발생 시점, 관련 라이브러리 호출 정보 등)
3. 원인 분석
- 오류 원인: 문제 발생 원인에 대한 설명 (예: Spring IoC Container의 작동 방식, Jupiter의 관리 주체 등)
- 문제 해결 과정에서 이해한 추가적인 원인이나 근본적인 이유를 포함
- 에러 로그 해석: 로그 메시지를 통해 확인한 중요한 단서나 인사이트 (예: “ParameterResolver를 찾지 못한 경우…” 등)
- 구조적 이해: 문제 해결을 위해 필요한 프레임워크나 라이브러리의 구조적 이해를 간단히 설명 (예: JUnit 5의 아키텍처와 Jupiter 역할)
4. 해결책
- 단계별 조치 방법: 문제 해결을 위한 구체적인 단계별 절차 안내
- Step 1: [구체적인 조치] (예: 특정 애노테이션 추가, 라이브러리 버전 조정 등)
- Step 2: [구체적인 조치] (예: 환경 재설정, 설정 파일 수정 등)
- (필요 시 단계 추가)
- 코드 예시: 문제 해결에 필요한 코드 예시가 있다면 추가
// 예시 코드 @Autowired constructor - 추가 자료: 에러 발생 원인이나 해결 과정에서 참고한 자료 또는 문서 링크 (예: 관련 공식 문서, 개발자 커뮤니티 게시물)
5. 교훈 및 주의 사항
- 주의할 점: 유사한 문제를 방지하기 위해 주의할 점 (예: 애노테이션 명시 여부, 프레임워크 업데이트 주기 확인 등)
- 배운 점: 문제 해결 과정에서 배운 점이나 중요한 교훈을 공유 (예: 로그 분석 중요성, 프레임워크의 구조적 이해 필요성 등)
템플릿 예시
Troubleshooting Guide - Spring Bean 주입 문제
1. 문제 개요
- 오류 상황: Spring 테스트 코드에서 Bean 주입 실패로 인해 테스트가 실패함
- 발생 배경: 생성자 주입을 통해 Bean을 주입받으려 했으나, 테스트 코드에서 주입되지 않음
2. 오류 코드 및 오류 메시지
- 오류 코드: FileNotFoundError (예시 코드에 맞춰 구체화)
- 오류 메시지:
No ParameterResolver found for parameter - 관련 로그: 해당 오류 발생 시점의 로그와 Jupiter의 파라미터 처리 관련 로그
3. 원인 분석
- 오류 원인: Spring IoC Container가 아닌 Jupiter가 테스트 클래스의 인스턴스를 관리하는 구조적 이유로, @Autowired 애노테이션을 명시하지 않으면 Bean 주입이 불가
- 에러 로그 해석: ParameterResolver가 없어 Bean을 주입할 수 없다는 오류를 통해 Jupiter의 역할과 한계를 확인
- 구조적 이해: JUnit 5 아키텍처에서 Jupiter가 어떻게 작동하는지와 Spring IoC Container가 아닌 Jupiter가 테스트 인스턴스를 관리하는 이유 설명
4. 해결책
- Step 1: 테스트 클래스의 생성자에 @Autowired 애노테이션 추가
class MyTestClass @Autowired constructor(val myBean: MyBean) { ... } - Step 2: 테스트 실행 후 Bean 주입이 정상적으로 이루어졌는지 확인
- 추가 자료: JUnit 5 구조 설명 링크, Spring Framework 공식 문서
5. 교훈 및 주의 사항
- 주의할 점: 테스트 코드에서 IoC Container가 아닌 Jupiter가 관리 주체임을 명심하고, 필요시 애노테이션을 명시
- 배운 점: 로그 해석의 중요성과 프레임워크 구조에 대한 이해 필요성
03 | 통합 가이드 문서
통합 Troubleshooting 가이드 문서 템플릿
문서 개요
- 문서 목적: 이 문서는 개발 중 발생할 수 있는 주요 문제 상황과 해결 방법을 체계적으로 정리한 통합 가이드이다다. 이를 통해 동일한 문제에 대한 반복적인 질문과 응답을 줄이고, 빠른 문제 해결을 지원하다.
- 대상 독자: 내/외부 개발자, IT 지원 팀, 고객 서비스 담당자
목차
Troubleshooting 가이드 개요
문제 상황의 목록과 간략한 설명을 제공한다.
| 문제 상황 | 간략 설명 | 대상 기능/서비스 | 관련 코드 |
|---|---|---|---|
| 문제 상황 1 | 문제 설명 | 기능/서비스 이름 | 관련 오류 코드 |
| 문제 상황 2 | 문제 설명 | 기능/서비스 이름 | 관련 오류 코드 |
| 문제 상황 3 | 문제 설명 | 기능/서비스 이름 | 관련 오류 코드 |
문제 상황별 Troubleshooting 가이드
문제 상황 1: [문제 제목]
1. 문제 개요
- 오류 상황: 구체적인 발생 상황과 범위
- 발생 배경: 문제를 접하게 된 경위나 초기 증상
2. 오류 코드 및 메시지
- 오류 코드: 관련 오류 코드 또는 상태 코드 (예: 404, 500 등)
- 오류 메시지: 발생 시 출력된 구체적인 메시지
- 관련 로그: 로그 분석에 필요한 구체적인 정보
3. 원인 분석
- 오류 원인: 문제 발생 원인과 구조적 이해
- 에러 로그 해석: 로그에서 확인한 핵심 단서
4. 해결책
- 단계별 조치 방법: 문제 해결을 위한 구체적인 절차
- 코드 예시: 해결에 필요한 코드나 설정 예시
- 참고 자료: 해결 과정에서 유용했던 추가 자료 링크
문제 상황 2: [문제 제목]
1. 문제 개요
- 오류 상황: 발생 상황 및 범위
- 발생 배경: 문제 발생 배경
2. 오류 코드 및 메시지
- 오류 코드: 관련 오류 코드
- 오류 메시지: 발생 시 출력된 메시지
- 관련 로그: 로그 분석에 필요한 정보
3. 원인 분석
- 오류 원인: 문제 발생 원인
- 에러 로그 해석: 로그에서 확인한 단서
4. 해결책
- 단계별 조치 방법: 단계별 해결 절차
- 코드 예시: 코드 예시
- 참고 자료: 추가 자료 링크
추가 정보
Troubleshooting 작성 시 주의 사항
- 일관성 유지: 각 문제 상황의 템플릿 형식을 유지하여, 독자가 원하는 문제를 빠르게 찾아볼 수 있도록 구성하다.
- 업데이트 기록: 문서가 최신 정보로 유지되도록 주기적으로 검토하고 수정 사항을 기록하다.
- 문서 위치 안내: Troubleshooting 가이드의 위치를 기술문서나 내부 인트라넷에서 쉽게 찾을 수 있도록 안내하다.
