api/endpoint 폴더 구조 관련 의견

[NamJwong]

요약

1. 서버 리스폰스가 매우 크고 복잡할 경우 스키마 선언을 분리하자.
2. endpoint 함수의 선언을 파일 별로 분리하자.

1번 의견은 트레이드 오프가 있어 상대적으로 중요도가 낮다 생각하며, 2번 의견은 중요도가 높다고 생각함.

해당 Discussion을 이해하기 위한 히스토리

최근 새롭게 도입한 api 타입 검증 및 컴포넌트 타입과의 분리를 위한 아키텍처

의견 1. 서버 리스폰스가 매우 크고 복잡할 경우 스키마 선언을 분리하자.

endpoint 중 /api/v1/members/profile/${id}(getMemberProfileById)의 서버 리스폰스는 매우 크고 복잡합니다.
필드의 개수가 아주 많고 그 중 객체 타입의 필드도 많습니다.

따라서 이런 경우에는 createEndPoint에서 요구하는 serverResponseSchema에 스키마 선언을 한 번에 하는 것보다는 project, link, career와 같은 객체 타입 필드는 따로 스키마 선언을 하는 것이 가독성과 유지보수에 좋겠다는 것이 첫 번째 의견입니다.

이에 따라 다음과 같이 해볼 수 있습니다.
한 도메인의 모든 endpoint 함수를 선언하는 api/endpoint/[도메인]/index.ts에 이 스키마들을 선언하는 것은 곤란하니,
api/endpoint/[도메인]/schema/[endpoint 함수명].ts 형태로 파일을 만들어 객체 타입 필드 스키마 선언을 분리했습니다.

그런데 이 방법에는 다음과 같은 두 가지 문제점이 있습니다.

1. 이렇게 분리했음에도 불구하고 getMemberProfileById의 serverResponseSchema는 매우 길어질 것이다. 객체 타입 필드가 여러 개 있을 뿐만 아니라 애초에 필드 개수가 너무 많기 때문이다. 이런 경우가 반복될 경우 api/endpoint/[도메인]/index.ts는 매우 복잡해져 각 endpoint 함수를 관리하기 어려워질 것이다.
2. 객체 타입 필드 스키마 선언을 다른 파일에 함으로써 export가 가능해졌기에 이번에 새로 설계한 이 아키텍처에서 해결하려고 했던 문제인 타입 간 '우발적 중복'이 발생할 위험이 생긴다. getMemberProfileById가 아닌, 변경이 방향성이 다른 endpoint 함수에서 해당 스키마들을 가져다 쓸 가능성이 생기기 때문이다.

의견 2. endpoint 함수의 선언을 파일 별로 분리하자.

따라서 두 번째 의견으로 다음을 제시합니다.
api/endpoint/[도메인]/index.ts를 사용하지 않고, api/endpoint/[endpoint 함수명].ts 형식으로 함수 별로 파일을 분리해서 선언하는 것이 어떨까요?
이렇게 하면 getMemberProfileById 같은 경우에는 최상단에 endpoint 함수를 선언하고 그 아래에 객체 타입 필드의 스키마를 따로 선언할 수 있을 것입니다.

이 방식의 장점은 다음과 같습니다.

1. api/endpoint/[도메인]/index.ts을 눌러보지 않아도 어떤 endpoint 함수가 있는지 한눈에 보여서 접근성이 매우 좋아질 것이다.
2. getMemberProfileById 경우처럼 스키마 선언을 나눠서 하는 것이 좋을 때 해당 선언을 endpoint 함수와 같은 파일에 함으로써 각 스키마 선언에 대한 접근성을 높이고, endpoint 함수 간의 잘못된 스키마 공유를 막을 수 있다. (우발적 중복 방지)

위에서 언급한 두 가지 문제점을 해결할 수 있는 장점들입니다.

각 의견에 대해 스스로 생각하는 중요도

그런데 사실 1번 의견 즉, 스키마 선언 분리는 (저번에 @Tekiter 가 언급했던 것처럼) 선언 앞에 누군가 export 하나만 달면 바로 우발적 중복의 위험이 높아집니다.
그렇기에 우발적 중복을 완전히 회피하려면 스키마를 따로 '선언'하지 않고 바로 serverResponseSchema에 할당하는 것이 가장 좋다고 생각합니다.
(애초에 @Tekiter 가 이러한 의도로 createEndPoint를 설계한 것 같습니다.)
하지만 serverResponseSchema의 복잡성이 높아지는 경우 관리하기 어려워지므로 트레이드 오프가 있는 것 같습니다.

이렇게 1번 의견은 이렇게 트레이드 오프가 있기 때문에 필수라고 생각하진 않습니다.
하지만 이 serverResponseSchema의 복잡성이 매우 올라갈 수 있다는 문제는 2번 의견으로도 조금이나마 해결할 수 있는 것 같습니다.
아무래도 endpoint 함수 자체가 파일로 분리되면 serverResponseSchema의 가독성이 좋지 않은 상황에서 위 아래 endpoint 함수들과 헷갈리는 일까지는 생기지 않기 때문입니다.

따라서 1번 의견은 가져가지 않더라도 2번 의견의 중요도는 높여서 고려해봤으면 좋겠습니다.

[NamJwong]

최대한 읽기 좋게 쓰려고 노력했는데 깃허브 폰트 스타일이 음슴체로 구조화 해서 쓰지 않은 글은 눈에 잘 안 들어오는 것 같아요 .. 혹시 이해하는 데에 시간 오래 걸리면 디스코드에서 마주쳤을 때 3분컷 설명하겠습니다!

[NamJwong]

endpoint 함수 별로 파일을 분리(2번 의견)하지 않으면 api/endpoint/[도메인]/index.ts 파일이 다음과 같이 복잡해질 수 있습니다.
제가 약 1년 간 참여한 프로젝트인데, 이러한 구조 때문에 유지보수 하는 데에 다소 어려움이 있었습니다.
그런데 구조 상 저희 파일이 더 복잡해질 것입니다 ..
이 사례들은 사실 transform만 해주고 있는 셈이지만 우리는 서버 타입 검증 + transform 이니까요.

https://github.com/Neogasogaeseo/Naega-Web/blob/dev/src/infrastructure/remote/team.ts
https://github.com/Neogasogaeseo/Naega-Web/blob/dev/src/infrastructure/remote/neoga.ts

[Tekiter]

스키마의 타입이 굉장히 복잡한 API가 많기 때문에, serverResponse 필드가 너무 복잡해져서 읽기 힘들 수 있다는 점에 공감해요!
저도 같은 이유로 2번이 더 나을 것 같다는 생각인데, 그냥 /api/endpoint 디렉터리 밑에 다 배치시키면 API가 많아질수록 보기 힘들어질 것 같아요.
/api/endpoint/[도메인]/[endpoint 함수명].ts 이렇게 배치하는건 어떨까요?

[NamJwong]

넵 딱 그 폴더 구조를 제안한 것이어요! 도메인으로는 구분돼야 할 것 같아요 👍👍

[juno7803]

저도 2번 내용 공감하고, 건영이가 제시해준 방법으로 폴더를 한 뎁스 더 가져가더라두 도메인 별로 나눠두는게 찾기 더 좋을 것 같아요!
기본적으로 폴더구조를 정한게 도메인 맥락이 같은 파일들을 co-location 하고 싶었던 것이라서 좀 더 의도에 맞는 방향 같습니다.

그리고 한 가지 질문이 있는데요, 여기서 말하는 우발적 중복이란, 같은 도메인에서 서버 스키마 끼리도 export를 막아야 한다고 보는 걸까요?
zod의 extend, pick, omit 등등은 같은 파일에서만 허용하는 걸까요?

원래 이 의도가 컴포넌트 타입과 분리하기 위함으로 이해했어서 해당 부분도 제한하려는 건지 궁금합니다. @NamJwong

[NamJwong]

컴포넌트 타입과 분리하기 위함도 있었지만, 타입 우발적 중복이 여기저기서 발생하고 있는 것도 문제점이었어요! 같은 도메인이라고 무조건 타입을 공유하면 안된다고 생각해요. 프로필의 경우만 봐도 업로드에 필요한 타입, 상세 페이지 조회에 필요한 타입이 달라요. 업로드는 새로운 데이터가 추가될 때마다 타입이 변경될 수 있고, 조회는 상세 페이지 UI에 따라 변경될 수 있어요. 이렇게 변경의 방향성이 다르면 지금 당장은 모양이 비슷해도 중복이 아니라고 생각해요.

물론 지금 당장 너무 비슷한 것들이 많아서 비효율적이라 생각할 수도 있지만 장기적으로 생각하면 api 함수 별로 각 객체 스키마를 분리해두는 게 좋다고 생각합니다!

[juno7803]

아하 완전 공감하고 이해했습니다~!
그럼 아예 막는건 아니구 제가 말한것 처럼 같은 파일에선 괜찮은 거겠죵?!

zod의 extend, pick, omit 등등은 같은 파일에서만 허용하는 걸까요?

[NamJwong]

넵 같은 파일 내에선 상관 없을 것 같아요! 다만 omit은 실제로 타입으로 정의되는 속성들이 직관적으로 보이지 않아 원본 타입의 변경에 잘 대처하기가 어렵다는 @Tekiter 선생님의 말씀을 참고해도 좋을 것 같습니다!