설계 훈련 - 시퀀스 다이어그램
설계 훈련 - 시퀀스 다이어그램
배경
지금까지 개발자로 2년 반 가량의 경력을 쌓아왔습니다. 처음 1년간은 설계에 대한 복잡한 고민 없이 주어진 기능을 만들어내는 것에 급급했습니다. 그 후 1년간은 기능을 확장성 있게 유연하게 만드는 것에 대해 코드 레벨의 관심을 가졌습니다. 그리고 최근 반년은 요건에 대한 설계를 바탕으로, 코드를 짜는 것에 대한 훈련을 하고 있습니다.
이 포스트의 제목에 설계 훈련이 들어간 것도 위와 같은 이유 때문입니다. 설계를 잘 하기 위해서는 시스템에 대한 분석을 바탕으로, 새로운 기능에 대한 설계도를 그리고 그 후에 실제 코드를 작성하는 훈련이 있어야 합니다. 아직 설계를 잘 한다고는 할 수 없지만 지금까지의 경험을 바탕으로 가독성 좋은 시퀀스 다이어그램을 그리는 방법을 공유하고자 합니다.
시퀀스 다이어그램이 필요한 이유
도메인이 복잡한 상황에서는 섣불리 ‘기존에 잘 돌아가던 코드’ 를 손대기가 무섭습니다. 제가 팀에 합류한 직후의 상황을 생각해보면 도메인에 대한 이해도가 낮기 때문에 새로운 기능의 개발을 위해서 기존의 코드를 손대는 작업에 언제나 두려움이 동반됐던 것 같습니다.
이런 상황에서 기존의 작동은 이러한데, 주어진 요건을 위해서 제가 이렇게 개발해도 될까요? 라고 팀의 리뷰를 받을 수 있다면 개발에 있어서 자신감도 생기고, 코드를 작성하기 전에 시행착오를 줄일 수도 있겠죠. 혹은 팀에 새로운 개발자가 합류했는데 도메인에 대한 이해도를 높이기 위해서 코어 로직을 설명할 때도 우리의 플로우가 어떻게 흐르는지 보여줄 수 있으면 좋을 것 같습니다.
물론, 개발자는 코드로 말하는 법이고 코드 안에 모든 요건과 로직이 녹아있을 테지만, 다른 사람의 코드를 보는 것은 때로는 어려운 일이기도 합니다. 이런 상황들 속에서 로직에 대한 시퀀스 다이어그램이 있다는 것은 다른 사람에게 무언가를 설명할 때 큰 도움이 됩니다.
실제 경험
사실 제가 팀에 합류한 직후만 해도, 저희 팀은 시퀀스 다이어그램을 적극적으로 그리고 있지는 않았습니다. 그럼에도 저는 시퀀스 다이어그램을 그려야만 한다고 마음을 먹었는데요, 그 이유는 제가 기존에 파이썬으로 된 코어 로직을 코프링으로 마이그레이션하는 업무를 맡게됐기 때문입니다. 당시에 도메인에 대한 이해도가 높지 않았기에 기존의 로직을 잘 분석해서, 코프링에 ‘잘 마이그레이션’ 했는지 팀원들의 리뷰가 절실했습니다. 그 과정에서 코드와, 테스트 코드만으로는 충분하지 않다고 느꼈고, 시퀀스 다이어그램을 그리게 됐습니다.
위의 그림은 그 당시 제가 실제로 그렸던 다이어그램의 일부를 캡쳐해서 가져왔습니다. 어떤 꼴로 그려졌는지 참고를 하기 위한 목적이고, 회사의 코어 로직을 담고 있는 부분이라 저화질로 보여드리는 점은 양해 부탁드립니다.
가장 상단을 보시면 노란색 사각형과 보라색 사각형을 보실 수 있습니다. 사진으로는 잘 보이지 않지만 사각형들 사이에는 화살표로 연결되어 있습니다. 따라서 파이썬 장고의 로직이 코프링의 어떤 로직으로 정확히 매핑됐는지를 확인할 수 있습니다. 팀의 리뷰를 통해서 모든 as-is 로직이 to-be 로직으로 마이그레이션됐다는 점을 확인받을 수 있을 겁니다.
실제 예시
그러면 이제 다음과 같은 로직을 시퀀스 다이어그램으로 직접 그려보면서 저는 어떻게 다이어그램을 그리는지 공유해드리고자 합니다. 대상이 되는 로직은 ‘회원 가입 시, 인증 메일 전송’입니다. 글로 적어보면 이런 요건이겠네요.
- 회원 가입 과정에서 사용된다.
- 사용자가 메일 주소를 입력하고, 인증 요청을 보낸다.
- 3분안에 해당 메일로 보낸 이력이 있으면 메일함을 확인해달라는 응답을 보낸다.
- 랜덤한 번호 6자리가 생성되고, 메일 본문에 실린다. 해당 번호는 앞으로 3분간 유효하다.
- 메일 발송을 위한 외부 api 를 호출한다.
- 메일 발송이 성공처리되면 응답한다.(보통 외부 api 를 호출하는 경우는 비동기로 구성하지만, 이 예시에서는 동기로 처리하도록 하겠습니다.)
자 이 요건을 만족시키기 위해서는 어떻게 시퀀스 다이어그램을 그려야할까요? 가장 먼저 엔드포인트를 잡습니다.
이 경우엔 사용자가 입력한 메일 주소를 request body 에 받는 편이 좋겠네요. request body 가 필요하다고 추가해줍니다.
메일 주소가 valid 한 형식인지 검증이 필요하겠네요. 또한 3분 안에 보낸 이력이 있는지 확인도 필요할 것 같습니다. 이 작업들을 수행해줄 MailService 를 만듭니다.
이렇게 추가하면 이메일 포멧을 검증하고, 조건에 따라서 어떤 일이 일어나는지 설명이 될 것 같습니다. 같은 형식으로 3분안에 메일을 보낸 이력이 있는지도 확인하는 로직을 추가할 수 있을 겁니다. 해당 부분은 유사한 형태니 이미지로 첨부하진 않겠습니다.
이제 메일을 보내기 위한 sendAuthenticationEmail 메서드를 구현해봅시다.
초록색 바는 변수에 대한 할당을 의미합니다. 그리고 지금은 6자리 랜덤 번호 생성하는 부분에 대해서는 내용을 묘사하지 않았지만 추후 요건에 따라서는 해당 부분을 구현한 후, 화살표로 연결해주면 될 것 같습니다. 보라색은 외부 서비스로 나가는 부분입니다. 이제 해당 로직이 궁금하면 보라색 로직을 따라가서 구현부를 확인할 수 있을겁니다.
전체적인 완성된 플로우는 위와 같을 것입니다. 본 도식에서는 이해를 돕기 위해 실무와는 달리 축약된 부분이 있음을 감안해주시면 감사하겠습니다.
결론
시퀀스 다이어그램은 단순한 문서화 도구 이상의 가치를 지닙니다. 제가 경험한 마이그레이션 프로젝트에서처럼, 복잡한 도메인 로직을 다루거나 기존 시스템을 변경할 때 매우 강력한 커뮤니케이션 도구가 됩니다. 시퀀스 다이어그램을 그리는 과정은 개발자에게 다음과 같은 이점을 제공합니다:
기존 시스템의 동작 방식을 더 깊이 이해할 수 있습니다 새로운 기능 개발 전에 설계상의 문제점을 미리 발견할 수 있습니다 팀원들과 효과적으로 의사소통하며 피드백을 받을 수 있습니다 새로 합류하는 팀원들의 온보딩을 돕는 좋은 문서가 됩니다
물론 시퀀스 다이어그램을 그리는 데는 시간과 노력이 필요합니다. 하지만 이는 결코 낭비가 아닙니다. 오히려 복잡한 도메인에서 발생할 수 있는 시행착오를 줄이고, 팀의 생산성을 높이는 투자라고 할 수 있습니다. 앞으로도 새로운 기능을 개발하거나 기존 시스템을 개선할 때, 시퀀스 다이어그램을 활용한 설계 단계를 거치는 것을 적극 추천드립니다. 이는 단순히 ‘동작하는 코드’를 넘어 ‘이해하기 쉽고 유지보수가 용이한 시스템’을 만드는 첫걸음이 될 것입니다.