@api Decorator

@api 데코레이터는 Model 메서드를 HTTP API 엔드포인트로 자동 변환합니다. 메서드에 데코레이터를 추가하면 라우팅, 타입 검증, 클라이언트 코드가 자동 생성됩니다.

기본 사용법

import { api } from "sonamu";

class UserModelClass extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async findById(id: number): Promise<User> {
    return this.getPuri("r").table("users").where("id", id).first();
  }
}

생성되는 것들:

HTTP 엔드포인트: GET /user/findById?id=1
TypeScript 클라이언트 함수
TanStack Query hooks (선택 시)
API 문서

데코레이터 옵션

전체 옵션

@api({
  httpMethod: "GET",                    // HTTP 메서드
  contentType: "application/json",      // Content-Type
  clients: ["axios", "tanstack-query"], // 생성할 클라이언트
  path: "/custom/path",                 // 커스텀 경로
  resourceName: "Users",                // 리소스 이름
  guards: ["admin", "user"],            // 인증/권한 가드
  description: "사용자 조회 API",       // API 설명
  timeout: 5000,                        // 타임아웃 (ms)
  cacheControl: { maxAge: 60 },         // 캐시 설정
  compress: false,                      // 응답 압축 비활성화
})

httpMethod

HTTP 메서드를 지정합니다.

메서드	용도	예시
`GET`	데이터 조회	`findById`, `findMany`
`POST`	데이터 생성/수정	`save`, `login`
`PUT`	데이터 업데이트	`update`
`DELETE`	데이터 삭제	`del`, `remove`
`PATCH`	부분 업데이트	`updateProfile`

@api({ httpMethod: "GET" })
async findById(id: number): Promise<User> {
  // ...
}
// 엔드포인트: GET /user/findById?id=1

@api({ httpMethod: "POST" })
async save(params: UserSaveParams[]): Promise<number[]> {
  // ...
}
// 엔드포인트: POST /user/save
// Body: { params: [...] }

@api({ httpMethod: "DELETE" })
async del(ids: number[]): Promise<number> {
  // ...
}
// 엔드포인트: DELETE /user/del
// Body: { ids: [1, 2, 3] }

기본값: httpMethod를 생략하면 GET이 기본값입니다.

@api()  // httpMethod: "GET"
async findById(id: number) { }

clients

생성할 클라이언트 코드 타입을 지정합니다.

Client	설명	사용 예시
`axios`	Axios 기반 함수	일반 API 호출
`axios-multipart`	파일 업로드용 Axios	이미지 업로드
`tanstack-query`	Query hook	데이터 조회
`tanstack-mutation`	Mutation hook	데이터 변경
`tanstack-mutation-multipart`	파일 업로드용 Mutation hook	파일 업로드 변경
`window-fetch`	Fetch API	브라우저 네이티브

@api({
  httpMethod: "GET",
  clients: ["axios", "tanstack-query"],
})
async findById(id: number): Promise<User> {
  // ...
}

@api({
  httpMethod: "POST",
  clients: ["axios", "tanstack-mutation"],
})
async save(params: UserSaveParams[]): Promise<number[]> {
  // ...
}

@upload()
async uploadAvatar(): Promise<{ url: string }> {
  // clients: ["axios-multipart", "tanstack-mutation-multipart"] 자동 설정
  // ...
}

생성되는 클라이언트 코드:

// services/user.service.ts
export async function findUserById(id: number): Promise<User> {
  const { data } = await axios.get("/user/findById", { params: { id } });
  return data;
}

// hooks/useUserQuery.ts
export function useUserById(id: number) {
  return useQuery({
    queryKey: ["user", "findById", id],
    queryFn: () => findUserById(id),
  });
}

// 사용
const { data: user } = useUserById(1);

// hooks/useUserMutation.ts
export function useSaveUser() {
  return useMutation({
    mutationFn: (params: UserSaveParams[]) => saveUser(params),
  });
}

// 사용
const { mutate } = useSaveUser();
mutate([{ email: "test@test.com" }]);

기본값: clients를 생략하면 ["axios"]가 기본값입니다.

path

커스텀 API 경로를 지정합니다.

// 기본 경로
@api({ httpMethod: "GET" })
async findById(id: number) { }
// 경로: /user/findById

// 커스텀 경로
@api({ httpMethod: "GET", path: "/api/v1/users/:id" })
async findById(id: number) { }
// 경로: /api/v1/users/:id

경로 파라미터:

@api({ httpMethod: "GET", path: "/posts/:postId/comments/:commentId" })
async findComment(postId: number, commentId: number): Promise<Comment> {
  // ...
}
// 호출: GET /posts/123/comments/456

경로를 생략하면 /{model}/{method} 형식으로 자동 생성됩니다.

Model: UserModel → user
Method: findById → findById
결과: /user/findById

resourceName

API 리소스 이름을 지정합니다. TanStack Query의 queryKey에 사용됩니다.

@api({
  httpMethod: "GET",
  resourceName: "Users",  // 복수형
  clients: ["tanstack-query"],
})
async findMany(): Promise<User[]> {
  // ...
}

// 생성되는 Query Hook
export function useUsers() {
  return useQuery({
    queryKey: ["Users", "findMany"],  // resourceName 사용
    queryFn: () => findManyUsers(),
  });
}

네이밍 가이드:

API 타입	resourceName	예시
단일 조회	단수형	`User`
목록 조회	복수형	`Users`
생성/수정	단수형	`User`
삭제	복수형	`Users`

guards

인증 및 권한 검사를 설정합니다.

// 인증만 필요
@api({ guards: ["user"] })
async getMyProfile(): Promise<User> {
  // 로그인한 사용자만 접근 가능
}

// 관리자 권한 필요
@api({ guards: ["admin"] })
async deleteUser(id: number): Promise<void> {
  // 관리자만 접근 가능
}

// 여러 가드 조합
@api({ guards: ["user", "admin"] })
async someAdminAction(): Promise<void> {
  // user AND admin 모두 만족해야 함
}

Guard 종류:

Guard	설명	확인 내용
`user`	로그인 필요	`context.user` 존재 여부
`admin`	관리자 권한	`context.user.role === "admin"`
`query`	커스텀 검사	사용자 정의 로직

Guard 로직은 sonamu.config.ts의 guardHandler에서 정의합니다.

sonamu.config.ts

export default {
  guardHandler: (guard, request, api) => {
    if (guard === "user" && !request.user) {
      throw new UnauthorizedException("로그인이 필요합니다");
    }
    if (guard === "admin" && request.user?.role !== "admin") {
      throw new UnauthorizedException("관리자 권한이 필요합니다");
    }
  },
};

contentType

응답의 Content-Type을 지정합니다.

// JSON (기본값)
@api({ contentType: "application/json" })
async getUser(): Promise<User> {
  return { id: 1, name: "John" };
}

// HTML
@api({ contentType: "text/html" })
async renderProfile(): Promise<string> {
  return "<html><body>Profile</body></html>";
}

// Plain Text
@api({ contentType: "text/plain" })
async getLog(): Promise<string> {
  return "Log content...";
}

// Binary (파일 다운로드)
@api({ contentType: "application/octet-stream" })
async downloadFile(): Promise<Buffer> {
  return fileBuffer;
}

timeout

API 타임아웃을 밀리초 단위로 지정합니다.

@api({ 
  httpMethod: "GET",
  timeout: 5000,  // 5초
})
async longRunningQuery(): Promise<Result> {
  // 5초 이상 걸리면 타임아웃
}

타임아웃은 클라이언트 측 설정입니다. 서버에서는 계속 실행될 수 있으므로, 서버 측 타임아웃도 별도로 설정해야 할 수 있습니다.

cacheControl

HTTP Cache-Control 헤더를 설정합니다.

// 1분 캐싱
@api({
  cacheControl: {
    maxAge: 60,  // seconds
  },
})
async getStaticData(): Promise<Data> {
  // ...
}

// 캐싱 비활성화
@api({
  cacheControl: {
    maxAge: 0,
    noCache: true,
  },
})
async getDynamicData(): Promise<Data> {
  // ...
}

CacheControl 옵션:

옵션	타입	설명	예시
`maxAge`	number	최대 캐시 시간 (초)	`60`
`noCache`	boolean	캐시 사용 안함	`true`
`noStore`	boolean	저장 안함	`true`
`private`	boolean	사용자별 캐시	`true`
`public`	boolean	공용 캐시	`true`

compress

응답 압축 설정을 제어합니다.

// 압축 활성화 (기본값)
@api({ compress: true })
async getData(): Promise<LargeData> {
  // 응답이 gzip으로 압축됨
}

// 압축 비활성화
@api({ compress: false })
async streamData(): Promise<StreamData> {
  // 압축 없이 전송 (스트리밍에 적합)
}

여러 데코레이터 조합

@api + @transactional

트랜잭션 내에서 API를 실행합니다.

@api({ httpMethod: "POST" })
@transactional()
async updateUserAndProfile(
  userId: number,
  userData: UserData,
  profileData: ProfileData
): Promise<void> {
  await this.save([userData]);
  await ProfileModel.save([profileData]);
  // 자동 커밋 또는 롤백
}

@upload (독립 사용)

파일 업로드 API를 만듭니다. @upload는 @api 없이 독립적으로 사용합니다.

@upload()
async uploadAvatar(): Promise<{ url: string }> {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0]; // 첫 번째 파일 사용

  if (!file) {
    throw new BadRequestException("파일이 없습니다");
  }

  // 파일 처리...
  const url = await file.saveToDisk("fs", `avatars/${Date.now()}-${file.filename}`);

  return { url };
}

Upload 옵션:

옵션	설명	사용 예시
`limits.fileSize`	최대 파일 크기 (bytes)	`10 * 1024 * 1024` (10MB)
`limits.files`	최대 파일 개수	`5`

단일/다중 파일 여부는 파라미터 타입(UploadedFile vs UploadedFile[])으로 결정됩니다.

API 경로 규칙

기본 경로는 다음 규칙으로 생성됩니다:

/{modelName}/{methodName}

변환 규칙:

Model 이름: PascalCase → camelCase
- UserModel → user
- BlogPostModel → blogPost
Method 이름: 그대로 사용
- findById → findById

예시:

Model	Method	경로
`UserModel`	`findById`	`/user/findById`
`BlogPostModel`	`findMany`	`/blogPost/findMany`
`CommentModel`	`save`	`/comment/save`

실전 예제

기본 CRUD API

@api({
  httpMethod: "GET",
  clients: ["axios", "tanstack-query"],
  resourceName: "User",
})
async findById(id: number): Promise<User> {
  const user = await this.getPuri("r")
    .where("id", id)
    .first();
    
  if (!user) {
    throw new NotFoundException(`User not found: ${id}`);
  }
  
  return user;
}

@api({
  httpMethod: "GET",
  clients: ["axios", "tanstack-query"],
  resourceName: "Users",
  cacheControl: { maxAge: 30 },
})
async findMany(params: UserListParams): Promise<ListResult<UserListParams, User>> {
  const { qb } = this.getSubsetQueries("A");
  
  if (params.keyword) {
    qb.whereLike("email", `%${params.keyword}%`);
  }
  
  return this.executeSubsetQuery({
    subset: "A",
    qb,
    params,
  });
}

@api({
  httpMethod: "POST",
  clients: ["axios", "tanstack-mutation"],
})
async save(params: UserSaveParams[]): Promise<number[]> {
  // 검증
  for (const param of params) {
    const existing = await this.getPuri("r")
      .where("email", param.email)
      .whereNot("id", param.id ?? 0)
      .first();
      
    if (existing) {
      throw new BadRequestException("이미 사용중인 이메일입니다");
    }
  }
  
  // 저장
  const wdb = this.getPuri("w");
  params.forEach(p => wdb.ubRegister("users", p));
  
  return wdb.transaction(async (trx) => {
    return trx.ubUpsert("users");
  });
}

@api({
  httpMethod: "DELETE",
  clients: ["axios", "tanstack-mutation"],
  guards: ["admin"],
})
async del(ids: number[]): Promise<number> {
  const wdb = this.getPuri("w");
  
  await wdb.transaction(async (trx) => {
    await trx.table("users")
      .whereIn("id", ids)
      .delete();
  });
  
  return ids.length;
}

인증 API

Sonamu는 인증을 better-auth의 HTTP 엔드포인트로 처리합니다. 로그인(/api/auth/sign-in/email), 로그아웃(/api/auth/sign-out) 등은 Sonamu @api 데코레이터가 아닌 better-auth가 직접 제공하는 엔드포인트를 사용하세요.

로그인한 사용자 정보를 반환하는 me() API는 context.user를 통해 구현합니다.

@api({
  httpMethod: "GET",
  clients: ["axios", "tanstack-query"],
  guards: ["user"],
})
async me(): Promise<User | null> {
  const context = Sonamu.getContext();
  
  if (!context.user) {
    return null;
  }
  
  return this.findById(context.user.id);
}

다음 단계

Business Logic

비즈니스 로직 작성 패턴 배우기

Stream Decorator

@stream으로 실시간 이벤트 전송하기

Upload Decorator

@upload로 파일 업로드 처리하기

Guards

인증과 권한 검사 구현하기

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

기본 사용법

데코레이터 옵션

전체 옵션

httpMethod

clients

path

resourceName

guards

contentType

timeout

cacheControl

compress

여러 데코레이터 조합

@api + @transactional

@upload (독립 사용)

API 경로 규칙

실전 예제

기본 CRUD API

인증 API

다음 단계

Business Logic

Stream Decorator

Upload Decorator

Guards

​기본 사용법

​데코레이터 옵션

​전체 옵션

​httpMethod

​clients

​path

​resourceName

​guards

​contentType

​timeout

​cacheControl

​compress

​여러 데코레이터 조합

​@api + @transactional

​@upload (독립 사용)

​API 경로 규칙

​실전 예제

​기본 CRUD API

​인증 API

​다음 단계

Business Logic

Stream Decorator

Upload Decorator

Guards

기본 사용법

데코레이터 옵션

전체 옵션

httpMethod

clients

path

resourceName

guards

contentType

timeout

cacheControl

compress

여러 데코레이터 조합

@api + @transactional

@upload (독립 사용)

API 경로 규칙

실전 예제

기본 CRUD API

인증 API

다음 단계