백엔드와 데이터, 타입 주고받기

안녕하세요. 노머스 프론트엔드 팀 황호찬입니다.

오늘은 개발팀에서 프론트엔드팀과 백엔드팀간에 API 통신에 대해서 소개해보려고 합니다. 단순히 API를 통해 데이터를 주고받는것 뿐이 아니라 어떤식으로 두 팀이 논의를 하고, 저희 팀 내에서 어떤식으로 타입을 관리하는지에 대한 이야기를 예시 코드와 함께 개발 진행 순서대로 진행해보려 합니다.

1. API 인터페이스 작성

우선 프로젝트의 기획, 디자인에 대한 논의가 종료된 후 API 인터페이스를 작성합니다. 작성 주체는 백엔드 개발 담당자가 아닌 프론트 개발 담당자가 작성합니다.

처음에는 백엔드팀에서 인터페이스 작성까지 담당했었는데요, 막상 개발이 시작하고 보면 프론트팀에서만 인지할수 있는 데이터들이 있어 해당 정보가 누락되고 개발 중에 변경이 발생하는 일이 잦았습니다.

이후로는 프론트엔드 팀에서 인터페이스 작성을 통해 필요한 데이터의 누락을 최소화 하고, 백엔드와의 회의를 통해 백엔드 팀 내에서 관리하는 네이밍이나 컨벤션을 적용시켜 최종적으로 인터페이스가 작성되고 프론트 팀에서는 백엔드의 API 작성을 기다리지 않고 개발을 시작하게 됩니다.

아래는 저희가 개발시 사용되었던 인터페이스의 일부인데요, 처음에 arti의 값은 객체가 아니라 artiId, artiName이라는 각각의 키로 작성되었지만 논의 과정에서 arti라는 객체안에서 묶어 사용하는걸로 논의되어 변경되었습니다.

// GET /post/:postId
{
	id: number;
	type?: 'image' | 'video';
	arti: {
		id: string;
		name: string;
    }
}

2. Mock 데이터를 통한 개발

해당 인터페이스가 정해지고 나면 프론트엔드 팀은 해당 인터페이스를 기반으로 하는 mock 데이터를 작성하고 개발을 시작합니다. 이때, 해당 개발 방식의 목표는 최종 API 연동시 별도의 작업 없이 API 엔드포인트와 타입을 정의해주는 작업만으로 연동 완료되는것을 목표로 합니다. 실제 코드를 먼저 한번 봐볼까요?

// post.api.ts
export type GetPostResponse = {
	id: number;
	type?: 'image' | 'video';
	arti: {
		id: string;
		name: string;
	}
}
const getPost = ({postId}: {postId: number}) => {
	return fetch<GetPostResponse>({ baseUrl: `/post/${postId}`});
}

// post.vo.ts
export class PostVo {
	id: number;
	type: 'text' | 'image' | 'video';
	arti: {
		id: string;
		name: string;
	}

	static from(response: GetPostResponse) {
		return new PostVo(response);
	}

	constructor(response: GetPostResponse) {
		this.id = response.id;
		this.type = response.type ?? 'text';
		this.arti = response.arti;
	}
}

// post.query.ts
const useGetPost = (postId: number) => {
	return useQuery({
        queryKey: ['getPost'],
        queryFn: () => {
	        getPost({postId}).then(PostVo.from)
        }
    })
}

이러한 흐름의 코드를 저희는 작성하고 있는데, api.ts는 해당 api의 호출을 위한 코드이고 query.ts는 react-query를 사용하는 부분으로 나름 익숙한 코드라고 생각하지만 vo.ts 파일은 조금 생소한 개념이라고 생각합니다.
저희가 사용하는 vo.ts 파일은 DB에 어느정도 의존적인 API의 리턴 타입을 프론트에서 더 입맛에 맞춰 사용하기 위한 컨버터 개념으로 이해해주시면 좋을것 같습니다.

예를 들어, 위에서 인터페이스를 정의할때 type이라는 키의 타입은 image, video 두가지 형식만 가질수 있는데 vo에서는 해당 값이 없을때 text라는 값으로 변경하여 사용하고 있는걸 확인할 수 있습니다. 이는 사실 type이 undefined 일때 text 형식의 데이터가 넘어오기로 되어 있었고 프론트에서 가독성을 더 챙기기 위해서 해당 데이터를 한번 더 가공해주고 있는 것입니다.

덕분에 저희는 아래처럼 가독성이 향상된 개발이 가능해졌습니다.
왜 type이 없는데 text 연관 로직이 나오나요? 가 아니라 type에 맞는 text 연관 로직이 나오는구나! 라고 생각할수 있어진것입니다.

// X
if (!type) {
	// text 연관 로직 및 UI
}

// O
if (type === 'text') {
	// text 연관 로직 및 UI
}

3. 실 API와의 연동

저희가 2번에서 설명드린 방식으로 개발을 진행하고 있으면 백엔드팀에서 개발 완료에 대한 알림이 옵니다.

음.. 그런데 어차피 배포했으면, 해당 인터페이스 기준으로 작성이 되었을테고 프론트에서 해당 정보 기준으로 호출하면 되는 일인데 왜 배포 버전까지 공유를 해주시는 걸까요?
그건 바로 백엔드에서 해당 publish를 통해서 API의 타입을 같이 넘겨주기 때문입니다.

저희 백엔드에서는 nestjs + typescript를 이용하여 개발을 진행하고 있는데 프론트와 같이 타입스크립트를 사용하고 있다보니, 백엔드가 정의한 타입을 배포하고 저희에게 공유해주는걸로 저희는 그 타입을 간단히 받아서 사용할수 있게 됩니다.

간단히 위에서 정의했던 api.ts 파일이 아래처럼 바뀌게 됩니다.

// post.api.ts

// before
export type GetPostResponse = {
	id: number;
	type?: 'image' | 'video';
	arti: {
		id: string;
		name: string;
	}
}
const getPost = ({postId}: {postId: number}) => {
	return fetch<GetPostResponse>({ baseUrl: `/post/${postId}`});
}

// after
import {GetPostResponse} from '@knowmerce/fromm-channel-post';

const getPost = ({postId}: {postId: number}) => {
	return fetch<GetPostResponse>({ baseUrl: `/post/${postId}`});
}

해당 방식을 사용했을때 느껴지는 장점으로는

• 백엔드가 전달해주는 타입을 사용하기 때문에 휴먼에러로 인한 타입 오차가 발생하지 않습니다.
• 백엔드가 배포시 전달해주는 버전을 통해 타입을 사용하기 때문에 백엔드 내부에서 버전이나 타입의 변경에 영향을 받지않습니다.
• 해당 버전에서 변경된 타입이 있다면 어디서 에러가 발생하고 있는지 바로바로 인지할수 있어 변경된 부분을 빠르게 적용할 수 있습니다.

마무리

이처럼 저희 팀은 프론트엔드와 백엔드 간의 효율적인 협업과 개발 속도 향상을 위해 인터페이스 작성부터 Mock 데이터 활용, VO 패턴 도입, 그리고 타입스크립트 기반의 타입 공유까지 일련의 프로세스를 체계적으로 관리하고 있습니다.

이러한 방식은 데이터 누락이나 타입 불일치로 인한 오류를 최소화하고, 개발 초기 단계부터 명확한 기준을 세워 효율적인 협업 환경을 조성하는 데 큰 도움을 주고 있습니다.

이 글이 여러분의 협업과 API 통신 및 타입 관리에 참고가 되기를 바랍니다!