> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Service 사용하기
> 자동 생성된 Service로 API 호출하기
생성된 Namespace Service를 사용하여 타입 안전하게 API를 호출하는 방법을 알아봅니다.
## Service 사용 개요
UserService.getUser() 간결한 문법
자동 완성 컴파일 검증
필요한 필드만 성능 최적화
useUser Hook 자동 캐싱
## 기본 사용법
### Service Import
생성된 Service는 `services.generated.ts`에서 Namespace로 export됩니다.
```typescript theme={null}
// ✅ 올바른 import 방식
import { UserService, PostService } from "@/services/services.generated";
```
**단일 파일 import의 장점**:
1. **일관성**: 모든 Service가 한 곳에서 관리됨
2. **간편한 import**: 파일 경로 찾을 필요 없음
3. **자동 업데이트**: `pnpm generate` 시 자동으로 동기화
4. **명확한 네이밍**: Namespace로 그룹화되어 충돌 없음
### 기본 API 호출
Service의 정적 함수를 직접 호출합니다.
```typescript theme={null}
import { UserService } from "@/services/services.generated";
// 사용자 조회 (Subset "A"로 기본 정보만)
const user = await UserService.getUser("A", 123);
console.log(user.username); // 타입 안전!
// 사용자 수정
await UserService.updateProfile({
username: "newname",
bio: "Hello, World!",
});
```
**특징**:
* `await`으로 비동기 호출
* 응답은 자동으로 파싱됨 (fetch 함수 내부 처리)
* 타입이 완전히 보장됨
* **Subset 파라미터 필수** (getUser 등)
**Namespace 기반 구조**: - ❌ 클래스 인스턴스: `new UserService()` 불필요 - ✅ 정적 함수:
`UserService.getUser()` 직접 호출 - 모든 함수가 독립적으로 동작
### Subset 시스템 이해하기
Sonamu의 핵심 기능인 Subset 시스템입니다.
```typescript theme={null}
// Subset "A": 기본 정보
const basicUser = await UserService.getUser("A", 123);
console.log(basicUser.id); // ✅ OK
console.log(basicUser.username); // ✅ OK
console.log(basicUser.bio); // ❌ 컴파일 에러 (Subset A에 없음)
// Subset "B": bio 포함
const userWithBio = await UserService.getUser("B", 123);
console.log(userWithBio.bio); // ✅ OK
// Subset "C": 전체 필드
const fullUser = await UserService.getUser("C", 123);
console.log(fullUser.createdAt); // ✅ OK
```
**Subset을 사용하는 이유**:
1. **성능**: 필요한 필드만 조회하여 네트워크 비용 절감
2. **타입 안전**: 각 Subset마다 정확한 타입 반환
3. **명시성**: 어떤 데이터가 필요한지 코드에서 명확히 표현
## React에서 사용하기
### TanStack Query Hook (권장)
가장 간편한 방법은 자동 생성된 TanStack Query Hook을 사용하는 것입니다.
```typescript theme={null}
import { UserService } from "@/services/services.generated";
function UserProfile({ userId }: { userId: number }) {
// 자동 생성된 Hook 사용
const { data: user, error, isLoading } = UserService.useUser("A", userId);
if (isLoading) return Loading...
;
if (error) return Error: {error.message}
;
if (!user) return User not found
;
return (
{user.username}
{user.email}
);
}
```
**TanStack Query Hook의 장점**:
* 자동 캐싱 (같은 userId 재사용)
* 자동 재검증 (포커스 시, 재연결 시)
* 로딩/에러 상태 자동 관리
* 중복 요청 자동 제거
### 함수 컴포넌트 (useEffect)
Hook을 사용하지 않고 직접 호출할 수도 있습니다.
```typescript theme={null}
import { useState, useEffect } from "react";
import { UserService } from "@/services/services.generated";
import type { User } from "@/services/services.generated";
function UserProfile({ userId }: { userId: number }) {
const [user, setUser] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
async function fetchUser() {
try {
setLoading(true);
// Subset "C"로 전체 필드 조회
const userData = await UserService.getUser("C", userId);
setUser(userData);
} catch (err) {
setError(err instanceof Error ? err.message : "Failed to load user");
} finally {
setLoading(false);
}
}
fetchUser();
}, [userId]);
if (loading) return Loading...
;
if (error) return Error: {error}
;
if (!user) return User not found
;
return (
{user.username}
{user.email}
);
}
```
**권장**: 가능하면 TanStack Query Hook을 사용하세요. 자동 캐싱, 재검증, 상태 관리를 모두 제공하여
코드가 훨씬 간결해집니다.
### 이벤트 핸들러
사용자 액션에 따라 API를 호출합니다.
```typescript theme={null}
import { useState } from "react";
import { UserService } from "@/services/services.generated";
function EditProfile({ userId }: { userId: number }) {
const [username, setUsername] = useState("");
const [bio, setBio] = useState("");
const [saving, setSaving] = useState(false);
async function handleSubmit(e: React.FormEvent) {
e.preventDefault();
try {
setSaving(true);
await UserService.updateProfile({
username,
bio,
});
alert("Profile updated!");
} catch (error) {
alert("Failed to update profile");
console.error(error);
} finally {
setSaving(false);
}
}
return (