meepin

posts

NestJS 프로젝트에서 API를 추가할 때 보는 기본 흐름

Apr 23, 2026 updated Apr 23, 2026 apibackendnestjsprisma

해당 문서는 NestJS 프로젝트에 API를 추가하는 흐름을 정리하려고 적었습니다..
NestJS는 Node 기반 백엔드라서, 프론트에서 타입스크립트에 익숙하다면 그나마 덜 낯선 편입니다.

다만 자세한 설명은 안 합니다.
공식 문서는 무적권 옆에 띄워놓고 보는 쪽이 낫습니다.

기준 스택은 PostgreSQL + Prisma ORM입니다.

큰 흐름부터

API를 추가하고 관리하는 게 사실 과정의 90%라고 생각합니다.
그래서 세부 구현보다 흐름을 먼저 적어두는 편이 좋습니다.

DB 변경이 필요 없는 경우에는 그냥 바로 API를 만들러 가면 됩니다.
반대로 스키마가 바뀌면 Prisma 쪽부터 먼저 손봐야 합니다.

프로젝트 구조는 대충 이렇게 봅니다

문서 기준 구조는 CMS 프로젝트 기반이었는데, 크게 다르진 않습니다.

docker/
env/
src/
  _shared/
  _config/
  auth/
  cache/
  content-folder/
  content-manager/
  content-media/
  media-library/
  content-type/
  prisma/
  app.module.ts
  main.ts

처음 레포를 받았으면 일단 이거부터 갑니다.

npm install

저는 repository 레이어를 뺐습니다

이건 취향이 좀 들어갑니다.
저는 서비스 레이어에서 바로 ORM을 호출하는 게 편해서 repository 레이어를 뺐습니다.

별로 정답이라고 우기려는 건 아니고, 현재 프로젝트에선 그게 더 단순했습니다.
도메인 검증, 예외 처리, ORM 호출이 service 안에 모이는 쪽이 그나마 읽기 쉬웠습니다.

어디를 먼저 보느냐

src/app.module.ts

NestJS는 뭐든 모듈로 만들어야 합니다.
app.module.ts는 그 모듈들을 하나로 관리하는 루트 쪽이라, 새로운 모듈을 만들면 여기에 적재해야 합니다.

자바에서 빈 등록하는 느낌으로 보면 대충 비슷합니다.

Service

비즈니스 로직이 들어가는 곳입니다.

  • ORM 호출
  • 도메인 검증
  • 예외 처리

이런 게 여기 모입니다.

Controller

요청을 받아서 서비스로 던지는 곳입니다.
자바 어노테이션처럼 데코레이터로 꽤 편하게 붙습니다.

  • @Get()
  • @Post()
  • @Patch()
  • @Delete()
  • @Body()
  • @Param()
  • @Query()
  • @ApiOperation()
  • @ApiOkResponse()

새 API 추가 예시

예를 들어 POST /v1/admin 같은 걸 만든다고 치면 저는 보통 이렇게 봅니다.

  1. Admin 모델이 현재 요구사항을 만족하는지 확인
  2. 부족하면 src/prisma/schema.prisma 수정
  3. npm run prisma:migrate:dev
  4. npm run prisma:generate
  5. src/admin/dto/create-admin.dto.ts 작성
  6. src/admin/admin.service.ts에 createAdmin() 구현
  7. src/admin/admin.controller.ts에 @Post() 라우트 추가
  8. 테스트 추가
  9. build, lint, test 실행

결국 특별한 건 없습니다.
DB가 바뀌면 Prisma부터, 아니면 service와 controller부터. 그 다음 테스트와 검증까지 가는 흐름입니다.

마무리

NestJS에서 API를 추가하는 일은 생각보다 구현보다 관리가 더 큽니다.
모듈, DTO, service, controller, Prisma, 테스트까지 계속 같이 보게 되거든요.

그래서 저는 새 API를 만들 때마다 세부 구현보다 지금 어느 레이어를 건드리는지부터 먼저 보는 편이 낫다고 생각합니다.
그게 그나마 덜 꼬입니다.