findById

findById는 ID로 단일 레코드를 조회하는 메서드입니다. 지정된 서브셋으로 데이터를 로드하며, 레코드가 없으면 NotFoundException을 발생시킵니다.

findById는 BaseModelClass에 정의되어 있지 않습니다. Entity를 생성하면 Syncer가 각 Model 클래스에 자동으로 생성하는 표준 패턴입니다.

타입 시그니처

async findById<T extends SubsetKey>(
  subset: T,
  id: number
): Promise<SubsetMapping[T]>

자동 생성 코드

Sonamu는 Entity를 기반으로 다음 코드를 자동으로 생성합니다:

// src/application/user/user.model.ts (자동 생성)
class UserModelClass extends BaseModelClass {
  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "User" })
  async findById<T extends UserSubsetKey>(subset: T, id: number): Promise<UserSubsetMapping[T]> {
    const { rows } = await this.findMany(subset, {
      id,
      num: 1,
      page: 1,
    });
    if (!rows[0]) {
      throw new NotFoundException(`존재하지 않는 User ID ${id}`);
    }

    return rows[0];
  }
}

내부 동작:

findMany를 호출하여 ID로 조회
num: 1, page: 1로 단건만 가져옴
결과가 없으면 NotFoundException 발생
첫 번째 레코드 반환

매개변수

subset

조회할 데이터의 서브셋을 지정합니다. 타입: SubsetKey (예: "A", "B", "C") 서브셋은 Entity 정의에서 설정한 데이터 형태를 결정합니다. 각 서브셋은 다른 필드와 관계를 포함할 수 있습니다.

// 기본 정보만 조회
const user = await UserModel.findById("A", 1);

// 관계 데이터 포함 조회
const user = await UserModel.findById("B", 1);

id

조회할 레코드의 ID입니다. 타입: number

const user = await UserModel.findById("A", 123);

반환값

타입: Promise<SubsetMapping[T]> 지정된 서브셋 타입의 레코드를 반환합니다. 타입은 서브셋에 따라 자동으로 추론됩니다.

// user의 타입은 자동으로 UserSubsetMapping["A"]로 추론됨
const user = await UserModel.findById("A", 1);

console.log(user.id); // number
console.log(user.email); // string
console.log(user.name); // string

예외

NotFoundException

ID에 해당하는 레코드가 없으면 NotFoundException이 발생합니다.

try {
  const user = await UserModel.findById("A", 999);
} catch (error) {
  if (error instanceof NotFoundException) {
    console.error("사용자를 찾을 수 없습니다");
  }
}

HTTP 상태 코드: 404

기본 사용법

단순 조회

import { UserModel } from "./user/user.model";

class UserService {
  async getUser(userId: number) {
    // ID로 사용자 조회 (서브셋 A)
    const user = await UserModel.findById("A", userId);

    return {
      id: user.id,
      email: user.email,
      name: user.name,
    };
  }
}

API에서 사용

findById는 자동으로 @api 데코레이터가 적용되어 REST API로 노출됩니다:

// 자동 생성된 코드
@api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "User" })
async findById<T extends UserSubsetKey>(
  subset: T,
  id: number
): Promise<UserSubsetMapping[T]> {
  // ...
}

생성된 클라이언트 코드:

// services.generated.ts (자동 생성)
import { UserService } from "@/services/UserService";

// ID로 사용자 조회
const user = await UserService.getUser("A", 123);

서브셋별 사용

서브셋 A (기본)

const user = await UserModel.findById("A", 1);

// 사용 가능한 필드
user.id; // number
user.email; // string
user.name; // string
user.created_at; // Date

서브셋 B (관계 포함)

const user = await UserModel.findById("B", 1);

// 관계 데이터 자동 로드
user.id; // number
user.email; // string
user.name; // string
user.posts; // Post[] (1:N 관계)
user.profile; // Profile (1:1 관계)

서브셋 C (중첩 관계)

const user = await UserModel.findById("C", 1);

// 중첩 관계까지 로드
user.posts[0].comments; // Comment[] (중첩 관계)
user.profile.images; // Image[] (중첩 관계)

실전 예시

사용자 프로필
주문 상세
권한 확인
에러 처리

import { UserModel } from "./user/user.model";
import { api } from "sonamu";

class ProfileFrame {
  @api({ httpMethod: "GET" })
  async getProfile(userId: number) {
    // ID로 사용자 조회 (프로필 정보 포함)
    const user = await UserModel.findById("Profile", userId);

    return {
      id: user.id,
      email: user.email,
      name: user.name,
      avatar: user.profile?.avatar_url,
      bio: user.profile?.bio,
      posts_count: user.posts?.length ?? 0
    };
  }
}

import { OrderModel } from "./order/order.model";
import { api } from "sonamu";

class OrderFrame {
  @api({ httpMethod: "GET" })
  async getOrderDetail(orderId: number) {
    // 주문 상세 조회 (상품, 배송 정보 포함)
    const order = await OrderModel.findById("Detail", orderId);

    return {
      id: order.id,
      status: order.status,
      total_amount: order.total_amount,
      items: order.items.map(item => ({
        product_name: item.product.name,
        quantity: item.quantity,
        price: item.price
      })),
      shipping: {
        address: order.shipping_address,
        status: order.shipping_status,
        tracking_number: order.tracking_number
      },
      customer: {
        name: order.user.name,
        email: order.user.email
      }
    };
  }
}

import { UserModel } from "./user/user.model";
import { Sonamu, api, UnauthorizedException } from "sonamu";

class PostFrame {
  @api({ httpMethod: "POST" })
  async deletePost(postId: number) {
    const { user } = Sonamu.getContext();

    // 게시물 작성자 확인
    const post = await PostModel.findById("A", postId);

    if (post.user_id !== user.id) {
      throw new UnauthorizedException("본인의 게시물만 삭제할 수 있습니다");
    }

    await PostModel.del([postId]);

    return { success: true };
  }
}

import { UserModel } from "./user/user.model";
import { NotFoundException, api } from "sonamu";

class UserFrame {
  @api({ httpMethod: "GET" })
  async getUserSafely(userId: number) {
    try {
      // ID로 사용자 조회
      const user = await UserModel.findById("A", userId);

      return {
        exists: true,
        user: {
          id: user.id,
          name: user.name,
          email: user.email
        }
      };
    } catch (error) {
      if (error instanceof NotFoundException) {
        return {
          exists: false,
          user: null
        };
      }
      throw error;
    }
  }

  @api({ httpMethod: "GET" })
  async getMultipleUsers(userIds: number[]) {
    const users = [];

    for (const id of userIds) {
      try {
        const user = await UserModel.findById("A", id);
        users.push(user);
      } catch (error) {
        // 존재하지 않는 사용자는 건너뜀
        if (error instanceof NotFoundException) {
          continue;
        }
        throw error;
      }
    }

    return users;
  }
}

findById vs findOne vs findMany

ID로 단일 레코드 조회
레코드가 없으면 예외 발생
가장 간단하고 빠름
자동 생성됨

// ID로 조회 (없으면 예외)
const user = await UserModel.findById("A", 1);

findOne

조건으로 단일 레코드 조회
레코드가 없으면 null 반환
복잡한 조건 가능
직접 구현 필요 (선택적)

// 조건으로 조회 (없으면 null)
const user = await UserModel.findOne("A", {
  email: "user@example.com",
});

findMany

조건으로 여러 레코드 조회
페이지네이션 지원
총 개수 반환
자동 생성됨

// 리스트 조회 (페이지네이션)
const { rows, total } = await UserModel.findMany("A", {
  status: "active",
  num: 20,
  page: 1,
});

타입 안정성

서브셋에 따라 반환 타입이 자동으로 추론됩니다:

// 서브셋 A: 기본 필드만
const userA = await UserModel.findById("A", 1);
userA.posts; // ❌ 타입 에러: Property 'posts' does not exist

// 서브셋 B: posts 포함
const userB = await UserModel.findById("B", 1);
userB.posts; // ✅ Post[]

클라이언트 사용

React (TanStack Query)

import { useQuery } from "@tanstack/react-query";
import { UserService } from "@/services/UserService";

function UserProfile({ userId }: { userId: number }) {
  const { data: user, isLoading, error } = useQuery({
    queryKey: ["user", userId],
    queryFn: () => UserService.getUser("A", userId)
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>User not found</div>;

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

Vue

import { UserService } from "@/services/UserService";

export default {
  data() {
    return {
      user: null,
      loading: false,
      error: null,
    };
  },
  async mounted() {
    this.loading = true;
    try {
      this.user = await UserService.getUser("A", this.userId);
    } catch (error) {
      this.error = error.message;
    } finally {
      this.loading = false;
    }
  },
};

주의사항

1. 서브셋 선택

필요한 데이터만 포함하는 서브셋을 선택하세요. 불필요한 관계를 로드하면 성능이 저하됩니다.

// ❌ 나쁜 예: 모든 관계 로드
const user = await UserModel.findById("Full", 1);

// ✅ 좋은 예: 필요한 필드만
const user = await UserModel.findById("A", 1);

2. 예외 처리

findById는 레코드가 없으면 예외를 발생시킵니다. 필요한 경우 예외 처리를 추가하세요.

// ❌ 나쁜 예: 예외 처리 없음
const user = await UserModel.findById("A", userId); // 404 에러 가능

// ✅ 좋은 예: 예외 처리
try {
  const user = await UserModel.findById("A", userId);
} catch (error) {
  if (error instanceof NotFoundException) {
    // 적절한 처리
  }
}

3. null 가능성

레코드 존재 여부가 불확실하면 findOne을 사용하세요 (직접 구현 필요).

// findById: 레코드가 반드시 존재해야 함
const user = await UserModel.findById("A", 1);

// findOne: 레코드가 없을 수 있음 (직접 구현 필요)
const user = await UserModel.findOne("A", { email: "unknown@example.com" });
if (user === null) {
  // 레코드 없음 처리
}

다음 단계

findMany

리스트 조회 및 페이지네이션

save

레코드 저장 및 수정

Subset

서브셋 이해하기

예외 처리

NotFoundException 처리

​타입 시그니처

​자동 생성 코드

​매개변수

​subset

​id

​반환값

​예외

​NotFoundException

​기본 사용법

​단순 조회

​API에서 사용

​서브셋별 사용

​서브셋 A (기본)

​서브셋 B (관계 포함)

​서브셋 C (중첩 관계)

​실전 예시

​findById vs findOne vs findMany

​findById

​findOne

​findMany

​타입 안정성

​클라이언트 사용

​React (TanStack Query)

​Vue

​주의사항

​1. 서브셋 선택

​2. 예외 처리

​3. null 가능성

​다음 단계

findMany

save

Subset

예외 처리

타입 시그니처

자동 생성 코드

매개변수

subset

id

반환값

예외

NotFoundException

기본 사용법

단순 조회

API에서 사용

서브셋별 사용

서브셋 A (기본)

서브셋 B (관계 포함)

서브셋 C (중첩 관계)

실전 예시

findById vs findOne vs findMany

findById

findOne

findMany

타입 안정성

클라이언트 사용

React (TanStack Query)

Vue

주의사항

1. 서브셋 선택

2. 예외 처리

3. null 가능성

다음 단계