Prisma API에서 아무도 이야기하지 않는 문제
Source: Dev.to
반복적인 쿼리 로직 문제
요구사항이 늘어나면서 엔드포인트에 필요해지는 것들:
- 필터링
- 검색
- 정렬
- 페이지네이션
- 소프트‑삭제 체크
- 쿼리 검증
전형적인 즉석 해결 방법은 다음과 같습니다:
if (query.isActive) {
where.isActive = query.isActive === "true";
}
if (query.search) {
where.OR = [
{ firstName: { contains: query.search, mode: "insensitive" } },
{ email: { contains: query.search, mode: "insensitive" } }
];
}
if (query.sort === "createdAt") {
orderBy.createdAt = "desc";
}각 엔드포인트마다 약간씩 다른 같은 로직이 생깁니다.
처음엔 중복이 별 문제처럼 보이지만, 시간이 지나면 다음과 같은 상황이 발생합니다:
- 한 엔드포인트는 잘못된 필터를 허용하고, 다른 엔드포인트는 이를 거부함
- 정렬 동작이 일관되지 않음
- 불리언을 일부에서는 올바르게 처리하지만, 다른 곳에서는 문자열로 취급함
이러한 작은 불일치가 실제로는 아무것도 깨지지 않았음에도 긴 디버깅 세션을 초래합니다.
왜 단순 헬퍼만으로는 부족한가
흔히 하는 반응은 중복 코드를 헬퍼 함수로 추출하는 것입니다. 실제로 헬퍼는 다음과 같이 문제가 됩니다:
- 너무 유연함 – 안전하지 않고 이해하기 어려움
- 너무 엄격함 – 서로 다른 엔드포인트에서 재사용하기 어려움
- 확장하기 어려움 – 새로운 요구가 생기면 깨지기 쉬움
일부 헬퍼는 Prisma 쿼리를 직접 실행하기도 해서, 서비스 레이어가 실행 흐름을 잃게 됩니다.
로직을 반복하는 대신 의도를 인코딩하기
핵심 문제는 쿼리 자체가 아니라 의도(필터링, 검색, 정렬, 거부 가능 여부)를 명확히 표현할 방법이 없다는 것입니다.
여기서 등장하는 것이 Prisma Query Builder (prisma‑qb) 입니다. 이 작은 라이브러리는 규칙을 한 번만 정의하고 안전한 Prisma 쿼리 객체를 생성해 줍니다.
사용 예시
import { buildPrismaQuery } from "prisma-qb";
const { where, orderBy } = buildPrismaQuery({
query: req.query,
searchFields: [
{ field: "firstName" },
{ field: "email" }
],
filterFields: [
{ key: "isActive", field: "isActive", type: "boolean" }
],
sortFields: [
{ key: "createdAt", field: "createdAt" }
],
defaultSort: { key: "createdAt", order: "desc" }
});이 함수는 Prisma where와 orderBy 객체만 반환합니다—실행은 하지 않죠. 서비스 레이어가 실제 쿼리 실행을 담당합니다.
장점
- 예측 가능한 API – 잘못된 쿼리 파라미터, 예상치 못한 필터, 검증되지 않은 정렬이 즉시 차단됩니다.
- 타입‑인식 검색 – 숫자가 문자열로 잘못 취급되지 않습니다.
- 숨겨진 실행 없음 – 라이브러리가 Prisma를 대신 실행하지 않으므로 완전한 제어권을 유지합니다.
- 지저분한 입력에도 안정적 – 명시적으로 허용한 필드만 쿼리에 참여합니다.
Prisma를 감싸거나 숨기지 않으며 새로운 쿼리 개념을 만들지도 않습니다. 단순히 Prisma 쿼리를 책임감 있게 구축해 줄 뿐입니다.
누가 사용하면 좋은가?
- 실제 API를 구축하는 개발자(데모가 아니라)
- 장기적인 일관성을 중시하는 팀
- 엔드포인트마다 같은 로직을 다시 쓰는 것을 싫어하는 사람
- 시간이 지나도 가독성·유지보수성을 유지해야 하는 프로젝트
이 상황이 익숙하다면, 이미 반복적인 쿼리 처리의 고통을 느껴봤을 겁니다. Prisma가 데이터베이스 접근을 해결했다면, Prisma Query Builder는 남은 API‑레벨 중복을 해결합니다.
설치 및 사용
한 번 사용해 보세요. 마음에 들지 않으면 알려 주세요. 피드백은 더 나은 도구를 만드는 데 큰 도움이 됩니다. 😉