📘 Supabase 프로필 이미지 업로드: 서비스와 쿼리를 분리한 구조 설계

💡 개요

Supabase의 Storage를 이용해 프로필 이미지를 업로드하고 불러오는 기능을 구현하면서,
React Query와 Zustand Store, API 서비스 레이어를 역할별로 명확하게 분리한 구조를 소개합니다.

---

🧩 문제 인식

처음에는 컴포넌트 내부에서 Supabase API를 직접 호출하고,
업로드나 이미지 조회 상태도 모두 컴포넌트에서 관리하고 있었습니다.

하지만 다음과 같은 문제가 발생했죠:

• ✅ 컴포넌트가 너무 많은 책임을 가짐 (API 호출 + 상태 관리 + 로직)
• ✅ 다른 페이지에서 재사용하려면 같은 로직을 반복해야 함
• ✅ 테스트와 유지보수가 어려움

---

🛠 구조 설계 방향

이런 문제를 해결하기 위해 다음과 같이 역할을 분리했습니다.

책임	위치	설명
API 호출	profileService	Supabase 호출만 담당 (순수 함수)
React Query	useProfileImageSuspenseQuery, useUploadProfileImageMutation	상태·에러 처리·캐시 무효화 포함
UI 상태	컴포넌트 내부	파일 선택, 미리보기 등 UI 전용 상태
사용자 정보	useUserStore	상태 전역 저장소에서 관리

---

📦 1. 서비스 레이어 (profileService.ts)

export const profileService = {
  async uploadProfileImage(file: File, userId: string) {
    const { data, error } = await supabase.storage
      .from('images')
      .upload(`profile/${userId}`, file, { upsert: true })
    if (error) throw error
    return data
  },

  async getProfileImageUrl(userId: string): Promise<string> {
    const { data } = supabase.storage.from('images').getPublicUrl(`profile/${userId}`)
    if (!data?.publicUrl) throw new Error('이미지 URL이 없습니다.')
    return data.publicUrl
  },
}

• 👉 Supabase 호출만 담당
• 👉 캐시 무효화나 토스트는 하지 않음 (퓨어 로직만)

---

⚙️ 2. 쿼리 훅 (useProfileImageSuspenseQuery.ts, useUploadProfileImageMutation.ts)

export const useProfileImageSuspenseQuery = (profileId: string) =>
  useSuspenseQuery({
    queryKey: profileKeys.image(profileId),
    queryFn: () => profileService.getProfileImageUrl(profileId),
  })

export const useUploadProfileImageMutation = (profileId: string) => {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: ({ file }) => profileService.uploadProfileImage(file, profileId),
    meta: {
      toastError: true,
      toastSuccess: true,
      toastSuccessMessage: '프로필 이미지가 정상적으로 업로드되었습니다',
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: profileKeys.detail(profileId) })
      queryClient.invalidateQueries({ queryKey: profileKeys.image(profileId) })
    },
    retry: 0,
  })
}

• 👉 쿼리 로직은 여기서 끝
• 👉 캐시 무효화, 토스트 등 부가 처리도 훅 내부에서 관리

---

🎨 3. 사용 예시 (컴포넌트)

const profileId = useUserStore((s) => s.profileId)
const { data: uploadedUrl } = useProfileImageSuspenseQuery(profileId)
const uploadMutation = useUploadProfileImageMutation(profileId)

• ✅ 컴포넌트는 데이터를 가져오기만 하면 됨
• ✅ uploadedUrl만 있으면 이미지를 그릴 수 있고
• ✅ uploadMutation.mutate({ file })만 호출하면 끝

---

✅ 구조 리팩터링 후의 이점

항목	리팩터링 전	리팩터링 후
API 호출 위치	컴포넌트 내부	profileService
상태 관리	컴포넌트에서 직접	React Query가 캐시 관리
관심사 분리	혼재되어 있음	서비스 / 쿼리 / UI 명확 분리
재사용성	낮음	높음 (어디서든 훅만 호출하면 됨)
유지보수	중복 코드 많음	로직 한 곳에서 통합 관리

---

✍️ 마무리

이번 구조 리팩터링을 통해 컴포넌트는 순수 UI만 담당하도록 정리했고,
비즈니스 로직과 API 호출은 퓨어한 서비스 함수와 React Query 훅으로 분리했습니다.

👇 필요한 데이터만 넘기면 되니까…

const uploadMutation = useUploadProfileImageMutation(profileId)
uploadMutation.mutate({ file })

서비스의 규모가 커질수록 이런 구조가 협업과 유지보수에서 진가를 발휘합니다.
당신의 프로젝트에도 이 구조를 한번 적용해보세요! 😊