[나만의 게시판] | 기본기부터 배우는 똑똑한 설계법 | ERD & RESTful

1. 왜 ‘똑똑한 설계법’을 배우는가?

크래프톤 정글 입학시험 때,
댓글 기능을 구현하는데
deletecomment/, makecomment/ 이런식으로 라우트를 만들었다.
당시엔 HTTP 메서드(GET‧POST‧PUT‧DELETE 등)의 의미도, RESTful 원칙도 잘 몰랐다.

시험이 끝난 후 코드 리뷰를 받았는데, “URI는 데이터(리소스) 를 가리켜야 하고, 행위 는 HTTP 메서드로 구분해야 한다”는 지적을 받았다.
그때 설계하는 방법을 배워야함을 처음 깨달았다.

---

1-1. 명확하지 않은 설계는 곧 기술 부채가 된다.

기능이 늘어날수록 URI는 점점 복잡해지고, 관리가 어려워진다.
예를 들어 댓글 기능을 구현할 때, 내가 처음 했던 것처럼

• /makecomment
• /deletecomment
• /editcomment

처럼 행위(action) 중심으로 각각의 URI를 따로 만들면,
시간이 지나고 기능이 많아지면 API가 불필요하게 늘어나고 중복된다.

특히, 수정할 때 마다 관련된 URI들을 모두 확인하며 바꿔야 해서 유지보수가 어려워진다.

이처럼 처음 설계를 잘못하면, 시간이 지날수록 빚처럼 누적이 되는 현상이 나타나는데
이것을 기술 부채 라고 한다.

---

1-2. 표준을 지키는 설계는 배우기도 쉽고 협업도 쉽다.

RESTful 설계는 어떤 규칙을 따르고 있어서
처음엔 좀 엄격하고 불편해 보일 수도 있지만, 쓰면 쓸수록 훨씬 더 명확하다.

기능	URI	HTTP 메서드
댓글 조회	/recipes/{id}/comments	GET
댓글 작성	/recipes/{id}/comments	POST
댓글 수정	/recipes/{id}/comments/{commentId}	PUT
댓글 삭제	/recipes/{id}/comments/{commentId}	DELETE

이렇게 구조가 깔끔하니까
나중에 코드를 보는 나도, 함께 일하는 다른 사람도 “이건 뭐 하는 API다”라는 게 바로 보인다.

온보딩이란?

‘온보딩(onboarding)’이란 말은 원래 신입사원이 회사에 적응하는 걸 말하는데,
개발에서는 새로운 팀원이 프로젝트에 들어와서 구조를 익히는 과정을 말한다.

설계가 제각각이면, 처음 보는 사람은 어디서 뭘 고쳐야 할지 몰라서
이해하는 데 시간도 오래 걸리고, 실수도 잦아진다.

반대로 설계가 표준적이고 일관성 있게 잘 돼 있으면
새로운 사람이 금방 이해하고, 바로 기여할 수 있다.
이번 프로젝트도 나 혼자 했지만,
“내가 나중에 봐도 이해할 수 있을까?” 를 계속 생각하면서 설계하려고 했다.

---

‘똑똑한 설계’가 주는 이점

유지보수성

버그가 생겨도 구조가 정리돼 있으니까 금방 원인을 찾고 고칠 수 있다.

확장성

리소스 중심으로 설계해 두면, /recipes/{id}/likes 같은 새로운 기능도 쉽게 추가할 수 있다.

협업 효율

URI, 메서드, 상태코드 같은 공통 언어가 있으니까
프론트, 백엔드, 기획자, 디자이너도 더 쉽게 소통할 수 있다.

표준 도구 활용

Swagger, Spring REST Docs 같은 문서화 도구도 표준 설계에 맞춰 자동으로 API 문서를 만들어준다.

---

마무리하며

처음 개발을 시작할 땐, 기능을 빠르게 구현하는 게 중요하다고 생각했다.
근데 이번 게시판 프로젝트를 하면서 느낀 건,
“빠르게”보다 “제대로” 만드는 게 훨씬 더 오래 가는 힘이라는 거다.

기능은 단순했지만
왜 이렇게 설계해야 하는지,
이 방식이 어떤 의미가 있는지를 생각하면서 만들었던 경험이
나중에 어떤 프로젝트를 하든 내 기준이 돼줄 거라 믿는다.

이게 바로 내가 생각하는 ‘똑똑한 설계법’이고,
앞으로 더 성장하기 위해 꼭 붙잡고 가야 할 기본기라고 생각한다.