API 응답을 위한 TypeScript 타입을 구성하여 훌륭한 개발 경험, 코드 유지 및 명백한 코딩 오류를 피하세요.

클라이언트 애플리케이션 개발자들은 매일 API와 작업합니다. 작업의 성공 또는 비즈니스 로직에 따라 API 응답을 표준화하는 것이 좋은 습관입니다. 일반적으로 응답은 상태, 오류 등과 같은 표준 필드를 포함합니다.

이러한 표준 필드를 사용하면 개발자들이 작업 상태에 대응하고 애플리케이션과의 추가 사용자 상호작용을 구축할 수 있습니다. 등록이 성공하면 폼이 닫히고 성공 메시지가 표시되어야 합니다. 그러나 데이터 형식이 잘못된 경우 유효성 검사 오류가 폼에 표시되어야 합니다.

프로젝트에서 응답 유형을 편리하고 빠르게 유연하게 설명하는 방법에 대한 질문이 발생합니다.

마주한 문제

가끔 프로젝트에서 응답 유형은 하나의 유형만 사용하여 여러 선택적 매개변수로 설명됩니다. 대부분의 경우 이것만으로 충분할 수도 있고, TypeScript는 코드를 작성할 때 이러한 매개변수를 제안해 줄 것입니다. 그러나 이러한 매개변수의 존재를 확인하는 추가적인 검사가 필요할 수도 있습니다. 이것이 그러한 유형의 예입니다:

이 접근 방식의 유일한 장점은 단순성입니다. 우리는 ApiData 유형을 어떤 응답 유형에 추가해도 충분합니다.

그러나 내가 생각하기론, 한 가지 장점은 상당한 단점에 비해 상쇄된다고 믿습니다. 이 방식의 단점은 투명성의 부족입니다.

또한, 이러한 유형을 응답 유형에 추가함으로써 특정 요청의 응답이 정확히 무엇인지 알 수 없게 됩니다. 예를 들어, POST 요청에 대해 API로부터 제한된 응답 시나리오가 나올 수 있다고 상상해봅시다.

다음과 같은 시나리오들이 있을 수 있습니다:

• 상태가 ok이고 일부 데이터를 가진 성공한 작업
• 상태가 form_errors이고 오류가 ['', '']인 유효성 오류, 그게 전부입니다

이 경우에는 redirect 상태가 가능한 응답 시나리오로 나타나지 않을 것이에요. 또한 GET 요청의 응답에 왜 errors 매개변수가 필요한지 궁금할 수도 있겠죠?

응답 유형을 보고 정확한 응답 옵션을 알 수 없다는 점이 밝혀졌어요. 모든 가능한 응답 변형을 이해하려면 요청을 보내고 응답을 처리하는 함수의 코드를 열어봐야 해요.

응답 유형을 위한 유틸리티 타입

위에서 설명한 단점은 사용자 정의 유틸리티 타입을 사용하여 해결할 수 있어요. 각 시나리오마다 별도의 타입이 있습니다: 성공적인 작업, 서버 오류, 유효성 검사 오류 또는 강제 리디렉션을 위한 개별 타입이 있답니다.

각 유형은 특정 응답에 대한 모든 가능한 응답 옵션을 반영하기 위해 개별적으로 또는 결합하여 사용할 수 있습니다. 각 유형은 해당 응답에 해당하는 데이터 유형을 전달할 수 있도록 일반 사항을 갖게 될 것입니다.

게다가, 제가 일반적인 ApiRespinse 유형을 만들었습니다. 이 유형에는 여러 유틸리티 유형이 포함되어 있습니다. 각 POST 요청에 대한 모든 시나리오를 추가하는 데 시간을 절약할 수 있게 될 것입니다.

아래는 다양한 시나리오에 대해 이러한 유틸리티 유형을 사용하는 예시입니다:

실용적인 차이

아래는 사용자 프로필의 유형과 사용자 프로필 업데이트 기능에서 반환된 응답의 예시입니다.

이 코드를 TypeScript로 어떻게 린트하는지 보여주는 이미지가 있습니다:

그림에서 TypeScript가 하이라이트한 대로, 표준 응답의 기대 값 중 일부인 오류, 오류 또는 URL과 같은 값들은 일반적으로 정의되지 않을 수 있다고 linter가 고려합니다. 이는 상태와 함께 추가로 체크가 필요하지만, 이미 이 접근 방식의 문제를 보여줍니다.

테이블 태그를 마크다운 형식으로 변경해주세요.

이 경우에는 모든 것이 예상대로 작동합니다:

• TypeScript는 해당 상태에 대응하는 표준 필드가 있을 것이라고 이해합니다.
• 사용자 값이 성공적인 경우를 제외한 모든 응답 유형에서 정의되지 않을 수 있음을 나타냅니다. 그러나 응답의 성공을 확인한 후에는 이 값이 강조되지 않고 정의됩니다.

결론

이 유틸리티 타입을 프로젝트에 구현한 후 개발자 경험이 크게 향상되었습니다. 이제 타입이 API가 제공할 수 있는 가능한 응답 시나리오와 완전히 일치합니다.

위에 표 표시 형식을 Markdown 형식으로 변경하면 특정 응답 유형에서 사용할 수 없는 값이 사용되어 잠재적인 오류를 방지할 수 있습니다. 사용자 값과 같은 경우가 있습니다.

또한 코드에서 응답 처리 구현을 살펴 볼 필요가 없습니다. 실제 응답 유형을 이해하려면 코드를 참고하면 됩니다. 전체 그림을 즉시 확인할 수 있습니다.

이 유틸리티 유형의 작동 방식에 관심이 있다면 Typescript Playground 페이지를 확인해보세요.