Czy to nie za dużo abstrakcji dla małego projektu?

Dla prostego CRUD z dwiema czy trzema encjami — owszem, to przerost formy nad treścią i lepiej zostać przy bezpośrednich zapytaniach w Server Action. Wzorzec zaczyna się opłacać, gdy pojawia się realna logika biznesowa: kalkulacja cen, stany magazynowe, powiadomienia, reguły, które trzeba egzekwować spójnie. Wtedy warto wprowadzić separację wcześnie, zanim logika rozproszy się po wielu funkcjach i stanie się trudna do zmiany.

Kiedy wprowadzić warstwy repository i service?

Dobrym sygnałem jest moment, w którym Server Action albo Route Handler przekracza mniej więcej 30 linii i miesza w sobie walidację, dostęp do bazy i reguły biznesowe — albo gdy zauważasz, że ta sama logika jest potrzebna w dwóch miejscach. To wtedy duplikacja i splątanie zaczynają realnie spowalniać pracę, a separacja warstw się zwraca. Nie musisz refaktoryzować całej aplikacji naraz; zacznij od domeny, która najbardziej boli.

Czy repository powinno zwracać typy z Prisma?

Docelowo nie — repository powinno zwracać własne typy domenowe, niezależne od ORM, bo to one są granicą, która pozwala później wymienić Prismę na Drizzle bez ruszania logiki biznesowej. W praktyce jednak na początku używanie typów generowanych przez Prismę jest w pełni akceptowalne i pragmatyczne. Wprowadzasz własne typy domenowe dopiero wtedy, gdy zmiana ORM albo niezależność od niego staje się realnym wymaganiem, a nie teoretycznym.

Czym repository różni się od service?

Repository odpowiada wyłącznie za dostęp do danych — zna ORM i bazę, ale nie zna reguł biznesowych. Service zna reguły biznesowe i orkiestruje operacje, ale nie wie nic o bazie, ORM ani HTTP; korzysta z repository jak z czarnej skrzynki. Ten podział sprawia, że zapytania masz w jednym miejscu, logikę w drugim, a żadna warstwa nie musi się zmieniać, gdy zmienia się ta druga. To esencja całego wzorca.

Czy ten wzorzec działa z Drizzle, nie tylko Prisma?

Tak — i to jest jedna z jego głównych zalet. Repository jest właśnie tą warstwą, która ukrywa konkretny ORM przed resztą aplikacji, więc czy pod spodem siedzi Prisma, Drizzle, czy surowy SQL, service i Server Actions tego nie widzą. Wymiana ORM sprowadza się do przepisania implementacji metod repository przy zachowaniu ich sygnatur — logika biznesowa i warstwa wejścia pozostają nietknięte.

Gdzie trzymać transakcje?

Transakcja powinna obejmować cały przypadek użycia, a nie pojedyncze wywołanie repository. Najczęściej robi to service przez Unit of Work: otwiera transakcję, tworzy repozytoria na kliencie transakcyjnym i wykonuje wszystkie operacje atomowo. Dzięki temu utworzenie zamówienia i zmniejszenie stanu magazynowego kończą się razem albo razem się wycofują.

Czy walidacja powinna być w Server Action czy w service?

Walidacja wejścia należy do warstwy wejścia: Server Action, Route Handler, zadanie cykliczne albo webhook powinny zamienić obce dane na bezpieczny input domenowy. Reguły biznesowe, np. limity ilości, dostępność produktu, uprawnienia do anulowania zamówienia czy stany przejść, należą do service. Schemat Zod możesz współdzielić między Server Action i Route Handlerem, żeby nie rozjechały się kontrakty.

Wzorzec Repository + Service Layer w Next.js full-stack — backend, który nie boli

Problem: logika biznesowa w Server Actions

Artykuł w skrócie

Trzy warstwy o jasnych rolach — repository (dostęp do danych), service (reguły biznesowe), Server Actions i Route Handlers jako cienkie adaptery wejścia. Każda wie o sobie jak najmniej.
Repository skupia zapytania w jednym miejscu — zmiana schematu czy wymiana ORM (Prisma → Drizzle) to edycja implementacji repository, a nie przepisywanie całej aplikacji.
Service nie wie o HTTP, ale zna przypadek użycia — zawiera reguły biznesowe, orkiestrację i decyzję o transakcji; dzięki temu testujesz logikę bez bazy, podstawiając fałszywe repository.
Transakcja obejmuje cały przypadek użycia — utworzenie zamówienia i aktualizacja stanu magazynowego muszą zakończyć się razem albo razem się wycofać.
Ten sam serwis obsługuje wiele wejść — Server Action, Route Handler i zadanie cykliczne wywołują tę samą metodę serwisu, więc logika biznesowa istnieje raz, bez duplikacji.
Czyste funkcje dla logiki obliczeniowej — np. kalkulacja ceny jako osobna, pozbawiona efektów ubocznych funkcja, którą trywialnie pokrywasz testami.
To nie przerost, ale nie zawsze — dla CRUD z dwiema encjami to za dużo; sięgaj po wzorzec, gdy pojawiają się reguły biznesowe albo ta sama logika potrzebna w wielu miejscach.

Code

// ŹLE — Server Action, który robi wszystko
'use server'
 
export async function createOrder(formData: FormData) {
  const session = await auth()
  if (!session) throw new Error('Unauthorized')
 
  const productId = formData.get('productId') as string
  const quantity = Number(formData.get('quantity'))
 
  // Walidacja
  if (!productId || quantity < 1) throw new Error('Invalid data')
 
  // Logika biznesowa + dostęp do bazy — wymieszane
  const product = await prisma.product.findUnique({ where: { id: productId } })
  if (!product) throw new Error('Product not found')
  if (product.stock < quantity) throw new Error('Not enough stock')
 
  const total = product.price * quantity
  const discount = total > 500 ? 0.1 : 0
  const finalPrice = total * (1 - discount)
 
  const order = await prisma.order.create({
    data: {
      userId: session.user.id,
      productId,
      quantity,
      total: finalPrice,
      status: 'PENDING',
    },
  })
 
  await prisma.product.update({
    where: { id: productId },
    data: { stock: { decrement: quantity } },
  })
 
  revalidatePath('/orders')
  return { success: true, orderId: order.id }
}

Problemy: nie da się tego testować bez bazy danych, logika cenowa jest ukryta w Server Action, zmiana ORM wymaga przepisania całej funkcji, duplikacja gdy potrzebujesz tego samego w Route Handlerze.

Warstwa Repository — abstrakcja dostępu do danych

to obiekt (lub zestaw funkcji), który enkapsuluje dostęp do bazy danych. Zapytania SQL/ORM są w jednym miejscu — reszta aplikacji operuje na czystych interfejsach TypeScript.

Code

// repositories/create-repositories.ts
import type { Prisma, PrismaClient } from '@prisma/client'
import { db } from '@/lib/db'
import type { CreateOrderData, Order, Product } from '@/types'
 
type DbClient = PrismaClient | Prisma.TransactionClient
 
export function createRepositories(client: DbClient = db) {
  return {
    product: createProductRepository(client),
    order: createOrderRepository(client),
  }
}
 
export type Repositories = ReturnType<typeof createRepositories>
 
function createProductRepository(client: DbClient) {
  return {
    async findById(id: string): Promise<Product | null> {
      return client.product.findUnique({ where: { id } })
    },
 
    async findMany(filters?: {
      category?: string
      minPrice?: number
      maxPrice?: number
    }): Promise<Product[]> {
      return client.product.findMany({
        where: {
          category: filters?.category,
          price: {
            gte: filters?.minPrice,
            lte: filters?.maxPrice,
          },
        },
        orderBy: { createdAt: 'desc' },
      })
    },
 
    async decrementStockIfAvailable(id: string, quantity: number) {
      return client.product.updateMany({
        where: {
          id,
          stock: { gte: quantity },
        },
        data: {
          stock: { decrement: quantity },
        },
      })
    },
 
    async incrementStock(id: string, quantity: number): Promise<Product> {
      return client.product.update({
        where: { id },
        data: { stock: { increment: quantity } },
      })
    },
  }
}
 
function createOrderRepository(client: DbClient) {
  return {
    async findById(id: string): Promise<Order | null> {
      return client.order.findUnique({
        where: { id },
        include: { product: true, user: true },
      })
    },
 
    async findByUserId(userId: string): Promise<Order[]> {
      return client.order.findMany({
        where: { userId },
        include: { product: true },
        orderBy: { createdAt: 'desc' },
      })
    },
 
    async create(data: CreateOrderData): Promise<Order> {
      return client.order.create({ data })
    },
 
    async updateStatus(id: string, status: string): Promise<Order> {
      return client.order.update({
        where: { id },
        data: { status },
      })
    },
  }
}

Korzyści Repository

Jedno miejsce na zapytania — zmiana schematu bazy wymaga edycji w jednym pliku
Testowalność — mockujesz repository, nie całą bazę danych
Wymienialność — przejście z Prisma na Drizzle to zmiana implementacji repository, nie całej aplikacji
Czytelność — productRepository.findById(id) jest jaśniejsze niż surowe zapytanie Prisma

Zwróć uwagę na parametr client. Repository może działać na globalnym db, ale może też dostać klienta transakcyjnego tx. To detal, który decyduje, czy wzorzec nadaje się do realnego backendu, czy tylko ładnie wygląda na diagramie.

Unit of Work — transakcja dla przypadku użycia

Jeśli operacja biznesowa dotyka kilku tabel, transakcja powinna obejmować cały przypadek użycia. Nie chcesz sytuacji, w której zamówienie powstało, ale stan magazynowy nie został zmniejszony.

Code

// lib/unit-of-work.ts
import { db } from '@/lib/db'
import {
  createRepositories,
  type Repositories,
} from '@/repositories/create-repositories'
 
export interface UnitOfWork {
  transaction<T>(
    callback: (repositories: Repositories) => Promise<T>,
  ): Promise<T>
}
 
export const unitOfWork: UnitOfWork = {
  async transaction(callback) {
    return db.$transaction(async (tx) => {
      const repositories = createRepositories(tx)
      return callback(repositories)
    })
  },
}

To jest prosty wariant wzorca Unit of Work: service nie musi znać szczegółów Prisma, ale może powiedzieć „ta operacja ma być atomowa”.

Warstwa Service — logika biznesowa

zawiera reguły biznesowe, walidację i orkiestrację operacji. Serwis korzysta z repository do dostępu do danych, ale nie wie nic o bazie danych, ORM ani HTTP.

Code

// services/order-service.ts
import { unitOfWork, type UnitOfWork } from '@/lib/unit-of-work'
import type { Order } from '@/types'
 
interface CreateOrderInput {
  userId: string
  productId: string
  quantity: number
}
 
interface CreateOrderResult {
  success: boolean
  order?: Order
  error?: string
}
 
interface OrderServiceDeps {
  unitOfWork: UnitOfWork
}
 
export function createOrderService({ unitOfWork }: OrderServiceDeps) {
  return {
    async createOrder(input: CreateOrderInput): Promise<CreateOrderResult> {
      // 1. Walidacja biznesowa
      if (input.quantity < 1 || input.quantity > 100) {
        return { success: false, error: 'Ilość musi być między 1 a 100' }
      }
 
      return unitOfWork.transaction(async (repositories) => {
        // 2. Sprawdzenie dostępności produktu
        const product = await repositories.product.findById(input.productId)
        if (!product) {
          return { success: false, error: 'Produkt nie istnieje' }
        }
 
        if (product.stock < input.quantity) {
          return { success: false, error: `Dostępne sztuki: ${product.stock}` }
        }
 
        // 3. Logika cenowa
        const pricing = calculatePricing(product.price, input.quantity)
 
        // 4. Atomowe zmniejszenie stanu magazynowego
        const stockUpdate =
          await repositories.product.decrementStockIfAvailable(
            input.productId,
            input.quantity,
          )
 
        if (stockUpdate.count === 0) {
          return { success: false, error: 'Produkt właśnie się wyprzedał' }
        }
 
        // 5. Utworzenie zamówienia w tej samej transakcji
        const order = await repositories.order.create({
          userId: input.userId,
          productId: input.productId,
          quantity: input.quantity,
          total: pricing.finalPrice,
          status: 'PENDING',
        })
 
        return { success: true, order }
      })
    },
 
    async cancelOrder(
      orderId: string,
      userId: string,
    ): Promise<CreateOrderResult> {
      return unitOfWork.transaction(async (repositories) => {
        const order = await repositories.order.findById(orderId)
 
        if (!order) {
          return { success: false, error: 'Zamówienie nie istnieje' }
        }
 
        if (order.userId !== userId) {
          return { success: false, error: 'Brak uprawnień' }
        }
 
        if (order.status !== 'PENDING') {
          return { success: false, error: 'Zamówienie nie może być anulowane' }
        }
 
        await repositories.product.incrementStock(
          order.productId,
          order.quantity,
        )
        const updated = await repositories.order.updateStatus(
          orderId,
          'CANCELLED',
        )
 
        return { success: true, order: updated }
      })
    },
  }
}
 
export const orderService = createOrderService({ unitOfWork })
 
// Czysta funkcja — łatwa do testowania
function calculatePricing(unitPrice: number, quantity: number) {
  const subtotal = unitPrice * quantity
  const discountRate = subtotal > 500 ? 0.1 : subtotal > 200 ? 0.05 : 0
  const discount = subtotal * discountRate
  const finalPrice = subtotal - discount
 
  return { subtotal, discountRate, discount, finalPrice }
}

Ten serwis nadal jest prosty, ale ma trzy ważne cechy: operacja zamówienia jest atomowa, zapobieganie oversellingowi jest w zapytaniu aktualizującym stock, a zależności można podmienić w teście bez mockowania importów modułów.

Granice odpowiedzialności

Ten podział działa tylko wtedy, gdy każda warstwa robi swoją część pracy:

Warstwa	Odpowiedzialność
Server Action	formularz, sesja użytkownika, walidacja inputu, rewalidacja cache
Route Handler	HTTP, statusy odpowiedzi, walidacja JSON, mapowanie błędów na response
Service	reguły biznesowe, orkiestracja, decyzja o transakcji
Repository	zapytania do bazy i szczegóły ORM
Czyste funkcje domenowe	obliczenia bez efektów ubocznych, np. cena, rabat, limity
`revalidatePath` / cache	na zewnątrz service, bo to szczegół interfejsu Next.js

Jeśli service zaczyna importować revalidatePath, Request, Response albo cookies, granica pęka. Jeśli repository zaczyna decydować, czy użytkownik może anulować zamówienie, granica też pęka.

Wspólna walidacja wejścia

Server Action i Route Handler mogą mieć różne protokoły wejścia, ale powinny kończyć z tym samym bezpiecznym typem domenowym. Najprościej wynieść schemat Zod do wspólnego pliku:

Code

// schemas/order-schema.ts
import { z } from 'zod'
 
export const createOrderSchema = z.object({
  productId: z.string().uuid(),
  quantity: z.coerce.number().int().min(1).max(100),
})
 
export type CreateOrderDto = z.infer<typeof createOrderSchema>

Server Actions — cienka warstwa wejścia

Po separacji Server Actions stają się cienką warstwą wejścia dla formularzy i mutacji Reacta: autoryzacja, walidacja inputu, wywołanie serwisu, rewalidacja cache.

Code

// actions/order-actions.ts
'use server'
 
import { auth } from '@/lib/auth'
import { revalidatePath } from 'next/cache'
import { orderService } from '@/services/order-service'
import { createOrderSchema } from '@/schemas/order-schema'
 
export async function createOrderAction(formData: FormData) {
  // 1. Autoryzacja
  const session = await auth()
  if (!session) return { error: 'Musisz być zalogowany' }
 
  // 2. Walidacja inputu
  const parsed = createOrderSchema.safeParse({
    productId: formData.get('productId'),
    quantity: formData.get('quantity'),
  })
 
  if (!parsed.success) {
    return { error: 'Nieprawidłowe dane', details: parsed.error.flatten() }
  }
 
  // 3. Delegacja do serwisu
  const result = await orderService.createOrder({
    userId: session.user.id,
    ...parsed.data,
  })
 
  // 4. Rewalidacja cache
  if (result.success) {
    revalidatePath('/orders')
    revalidatePath('/products')
  }
 
  return result
}
 
export async function cancelOrderAction(orderId: string) {
  const session = await auth()
  if (!session) return { error: 'Musisz być zalogowany' }
 
  const result = await orderService.cancelOrder(orderId, session.user.id)
 
  if (result.success) {
    revalidatePath('/orders')
  }
 
  return result
}

Route Handlers — ten sam serwis, inne wejście

Code

// app/api/orders/route.ts
import { auth } from '@/lib/auth'
import { orderService } from '@/services/order-service'
import { createOrderSchema } from '@/schemas/order-schema'
 
export async function POST(request: Request) {
  const session = await auth()
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }
 
  const body = await request.json()
  const parsed = createOrderSchema.safeParse(body)
 
  if (!parsed.success) {
    return Response.json(
      { error: 'Invalid payload', details: parsed.error.flatten() },
      { status: 422 },
    )
  }
 
  const result = await orderService.createOrder({
    userId: session.user.id,
    ...parsed.data,
  })
 
  if (!result.success) {
    return Response.json({ error: result.error }, { status: 400 })
  }
 
  return Response.json(result.order, { status: 201 })
}

Server Action i Route Handler używają tego samego serwisu — logika biznesowa istnieje w jednym miejscu.

Testowanie

Największa korzyść tej architektury: testowanie bez bazy danych.

Code

// __tests__/services/order-service.test.ts
import { createOrderService } from '@/services/order-service'
import { vi, describe, it, expect, beforeEach } from 'vitest'
 
describe('orderService.createOrder', () => {
  const productRepository = {
    findById: vi.fn(),
    decrementStockIfAvailable: vi.fn(),
    incrementStock: vi.fn(),
  }
 
  const orderRepository = {
    findById: vi.fn(),
    create: vi.fn(),
    updateStatus: vi.fn(),
  }
 
  const unitOfWork = {
    transaction: vi.fn(async (callback) =>
      callback({
        product: productRepository,
        order: orderRepository,
      }),
    ),
  }
 
  const orderService = createOrderService({ unitOfWork })
 
  beforeEach(() => {
    vi.clearAllMocks()
  })
 
  it('should create order when product is available', async () => {
    productRepository.findById.mockResolvedValue({
      id: '1',
      name: 'Test',
      price: 100,
      stock: 10,
      category: 'test',
    })
 
    productRepository.decrementStockIfAvailable.mockResolvedValue({ count: 1 })
 
    orderRepository.create.mockResolvedValue({
      id: 'order-1',
      userId: 'user-1',
      productId: '1',
      quantity: 2,
      total: 200,
      status: 'PENDING',
    })
 
    const result = await orderService.createOrder({
      userId: 'user-1',
      productId: '1',
      quantity: 2,
    })
 
    expect(result.success).toBe(true)
    expect(result.order?.total).toBe(200)
    expect(productRepository.decrementStockIfAvailable).toHaveBeenCalledWith(
      '1',
      2,
    )
    expect(unitOfWork.transaction).toHaveBeenCalledTimes(1)
  })
 
  it('should fail when product out of stock', async () => {
    productRepository.findById.mockResolvedValue({
      id: '1',
      name: 'Test',
      price: 100,
      stock: 1,
      category: 'test',
    })
 
    const result = await orderService.createOrder({
      userId: 'user-1',
      productId: '1',
      quantity: 5,
    })
 
    expect(result.success).toBe(false)
    expect(result.error).toContain('Dostępne sztuki')
    expect(orderRepository.create).not.toHaveBeenCalled()
  })
})

Struktura plików

Code

src/
├── repositories/        ← Dostęp do danych (ORM)
│   └── create-repositories.ts
├── services/            ← Logika biznesowa
│   ├── order-service.ts
│   ├── pricing-service.ts
│   └── notification-service.ts
├── schemas/             ← Wspólna walidacja wejścia
│   └── order-schema.ts
├── actions/             ← Server Actions (cienkie adaptery)
│   ├── order-actions.ts
│   └── product-actions.ts
├── lib/
│   ├── db.ts
│   └── unit-of-work.ts  ← Transakcje dla przypadków użycia
├── app/
│   ├── api/             ← Route Handlers (cienkie adaptery)
│   └── ...
└── types/               ← Interfejsy i typy
    └── index.ts

Kiedy nie używać tego wzorca

Nie każdy projekt potrzebuje pełnego zestawu warstw. Jeśli masz małą stronę z panelem administracyjnym, trzy tabele i proste operacje CRUD, zacznij od prostszej struktury:

schema Zod blisko Server Action,
jedno zapytanie Prisma/Drizzle w funkcji,
brak osobnego service, dopóki nie ma reguł biznesowych,
refaktor dopiero wtedy, gdy ta sama logika pojawia się w drugim miejscu.

Wzorzec Repository + Service Layer ma sens, gdy pojawiają się transakcje, kilka wejść do tej samej operacji, integracje zewnętrzne, reguły stanów albo realne testy jednostkowe logiki domenowej. Najpierw funkcja, potem warstwa — to często zdrowsza ścieżka niż budowanie katalogów „na zapas”.

Werdykt Labu

Repository i Service Layer to nie przerost formy, jeśli stosujesz je w odpowiednim momencie. To inwestycja w utrzymywalność, która separuje trzy rzeczy zbyt często wymieszane w jednej funkcji: dostęp do danych, reguły biznesowe i interfejs wejścia. Repository skupia zapytania, service trzyma logikę i transakcje, a Server Actions oraz Route Handlers stają się cienkimi adapterami. Efekt jest namacalny — logikę testujesz bez bazy, wymiana ORM nie dotyka reguł biznesowych, a ten sam serwis obsługuje Server Action, Route Handler i zadanie cykliczne bez duplikacji.

Klucz to wyczucie skali. Dla CRUD z dwiema encjami ten wzorzec jest przerostem; sięgaj po niego, gdy pojawia się prawdziwa logika biznesowa — ceny, stany, reguły — albo gdy ta sama operacja potrzebna jest w dwóch miejscach. Nie musisz wprowadzać go w całej aplikacji naraz: zacznij od domeny, w której Server Actions zaczynają puchnąć i mieszać odpowiedzialności, a resztę refaktoryzuj, gdy zaboli. Tak zastosowany, wzorzec naprawdę sprawia, że backend przestaje boleć.

Elastyczne i wydajne narzędzia dla biznesu, które dotrzymają kroku Twojemu rozwojowi.

Next.js

Problem: logika biznesowa w Server Actions

Artykuł w skrócie

Trzy warstwy o jasnych rolach — repository (dostęp do danych), service (reguły biznesowe), Server Actions i Route Handlers jako cienkie adaptery wejścia. Każda wie o sobie jak najmniej.
Repository skupia zapytania w jednym miejscu — zmiana schematu czy wymiana ORM (Prisma → Drizzle) to edycja implementacji repository, a nie przepisywanie całej aplikacji.
Service nie wie o HTTP, ale zna przypadek użycia — zawiera reguły biznesowe, orkiestrację i decyzję o transakcji; dzięki temu testujesz logikę bez bazy, podstawiając fałszywe repository.
Transakcja obejmuje cały przypadek użycia — utworzenie zamówienia i aktualizacja stanu magazynowego muszą zakończyć się razem albo razem się wycofać.
Ten sam serwis obsługuje wiele wejść — Server Action, Route Handler i zadanie cykliczne wywołują tę samą metodę serwisu, więc logika biznesowa istnieje raz, bez duplikacji.
Czyste funkcje dla logiki obliczeniowej — np. kalkulacja ceny jako osobna, pozbawiona efektów ubocznych funkcja, którą trywialnie pokrywasz testami.
To nie przerost, ale nie zawsze — dla CRUD z dwiema encjami to za dużo; sięgaj po wzorzec, gdy pojawiają się reguły biznesowe albo ta sama logika potrzebna w wielu miejscach.

Code

// ŹLE — Server Action, który robi wszystko
'use server'
 
export async function createOrder(formData: FormData) {
  const session = await auth()
  if (!session) throw new Error('Unauthorized')
 
  const productId = formData.get('productId') as string
  const quantity = Number(formData.get('quantity'))
 
  // Walidacja
  if (!productId || quantity < 1) throw new Error('Invalid data')
 
  // Logika biznesowa + dostęp do bazy — wymieszane
  const product = await prisma.product.findUnique({ where: { id: productId } })
  if (!product) throw new Error('Product not found')
  if (product.stock < quantity) throw new Error('Not enough stock')
 
  const total = product.price * quantity
  const discount = total > 500 ? 0.1 : 0
  const finalPrice = total * (1 - discount)
 
  const order = await prisma.order.create({
    data: {
      userId: session.user.id,
      productId,
      quantity,
      total: finalPrice,
      status: 'PENDING',
    },
  })
 
  await prisma.product.update({
    where: { id: productId },
    data: { stock: { decrement: quantity } },
  })
 
  revalidatePath('/orders')
  return { success: true, orderId: order.id }
}

Warstwa Repository — abstrakcja dostępu do danych

to obiekt (lub zestaw funkcji), który enkapsuluje dostęp do bazy danych. Zapytania SQL/ORM są w jednym miejscu — reszta aplikacji operuje na czystych interfejsach TypeScript.

Code

// repositories/create-repositories.ts
import type { Prisma, PrismaClient } from '@prisma/client'
import { db } from '@/lib/db'
import type { CreateOrderData, Order, Product } from '@/types'
 
type DbClient = PrismaClient | Prisma.TransactionClient
 
export function createRepositories(client: DbClient = db) {
  return {
    product: createProductRepository(client),
    order: createOrderRepository(client),
  }
}
 
export type Repositories = ReturnType<typeof createRepositories>
 
function createProductRepository(client: DbClient) {
  return {
    async findById(id: string): Promise<Product | null> {
      return client.product.findUnique({ where: { id } })
    },
 
    async findMany(filters?: {
      category?: string
      minPrice?: number
      maxPrice?: number
    }): Promise<Product[]> {
      return client.product.findMany({
        where: {
          category: filters?.category,
          price: {
            gte: filters?.minPrice,
            lte: filters?.maxPrice,
          },
        },
        orderBy: { createdAt: 'desc' },
      })
    },
 
    async decrementStockIfAvailable(id: string, quantity: number) {
      return client.product.updateMany({
        where: {
          id,
          stock: { gte: quantity },
        },
        data: {
          stock: { decrement: quantity },
        },
      })
    },
 
    async incrementStock(id: string, quantity: number): Promise<Product> {
      return client.product.update({
        where: { id },
        data: { stock: { increment: quantity } },
      })
    },
  }
}
 
function createOrderRepository(client: DbClient) {
  return {
    async findById(id: string): Promise<Order | null> {
      return client.order.findUnique({
        where: { id },
        include: { product: true, user: true },
      })
    },
 
    async findByUserId(userId: string): Promise<Order[]> {
      return client.order.findMany({
        where: { userId },
        include: { product: true },
        orderBy: { createdAt: 'desc' },
      })
    },
 
    async create(data: CreateOrderData): Promise<Order> {
      return client.order.create({ data })
    },
 
    async updateStatus(id: string, status: string): Promise<Order> {
      return client.order.update({
        where: { id },
        data: { status },
      })
    },
  }
}

Korzyści Repository

Jedno miejsce na zapytania — zmiana schematu bazy wymaga edycji w jednym pliku
Testowalność — mockujesz repository, nie całą bazę danych
Wymienialność — przejście z Prisma na Drizzle to zmiana implementacji repository, nie całej aplikacji
Czytelność — productRepository.findById(id) jest jaśniejsze niż surowe zapytanie Prisma

Unit of Work — transakcja dla przypadku użycia

Jeśli operacja biznesowa dotyka kilku tabel, transakcja powinna obejmować cały przypadek użycia. Nie chcesz sytuacji, w której zamówienie powstało, ale stan magazynowy nie został zmniejszony.

Code

// lib/unit-of-work.ts
import { db } from '@/lib/db'
import {
  createRepositories,
  type Repositories,
} from '@/repositories/create-repositories'
 
export interface UnitOfWork {
  transaction<T>(
    callback: (repositories: Repositories) => Promise<T>,
  ): Promise<T>
}
 
export const unitOfWork: UnitOfWork = {
  async transaction(callback) {
    return db.$transaction(async (tx) => {
      const repositories = createRepositories(tx)
      return callback(repositories)
    })
  },
}

To jest prosty wariant wzorca Unit of Work: service nie musi znać szczegółów Prisma, ale może powiedzieć „ta operacja ma być atomowa”.

Warstwa Service — logika biznesowa

zawiera reguły biznesowe, walidację i orkiestrację operacji. Serwis korzysta z repository do dostępu do danych, ale nie wie nic o bazie danych, ORM ani HTTP.

Code

// services/order-service.ts
import { unitOfWork, type UnitOfWork } from '@/lib/unit-of-work'
import type { Order } from '@/types'
 
interface CreateOrderInput {
  userId: string
  productId: string
  quantity: number
}
 
interface CreateOrderResult {
  success: boolean
  order?: Order
  error?: string
}
 
interface OrderServiceDeps {
  unitOfWork: UnitOfWork
}
 
export function createOrderService({ unitOfWork }: OrderServiceDeps) {
  return {
    async createOrder(input: CreateOrderInput): Promise<CreateOrderResult> {
      // 1. Walidacja biznesowa
      if (input.quantity < 1 || input.quantity > 100) {
        return { success: false, error: 'Ilość musi być między 1 a 100' }
      }
 
      return unitOfWork.transaction(async (repositories) => {
        // 2. Sprawdzenie dostępności produktu
        const product = await repositories.product.findById(input.productId)
        if (!product) {
          return { success: false, error: 'Produkt nie istnieje' }
        }
 
        if (product.stock < input.quantity) {
          return { success: false, error: `Dostępne sztuki: ${product.stock}` }
        }
 
        // 3. Logika cenowa
        const pricing = calculatePricing(product.price, input.quantity)
 
        // 4. Atomowe zmniejszenie stanu magazynowego
        const stockUpdate =
          await repositories.product.decrementStockIfAvailable(
            input.productId,
            input.quantity,
          )
 
        if (stockUpdate.count === 0) {
          return { success: false, error: 'Produkt właśnie się wyprzedał' }
        }
 
        // 5. Utworzenie zamówienia w tej samej transakcji
        const order = await repositories.order.create({
          userId: input.userId,
          productId: input.productId,
          quantity: input.quantity,
          total: pricing.finalPrice,
          status: 'PENDING',
        })
 
        return { success: true, order }
      })
    },
 
    async cancelOrder(
      orderId: string,
      userId: string,
    ): Promise<CreateOrderResult> {
      return unitOfWork.transaction(async (repositories) => {
        const order = await repositories.order.findById(orderId)
 
        if (!order) {
          return { success: false, error: 'Zamówienie nie istnieje' }
        }
 
        if (order.userId !== userId) {
          return { success: false, error: 'Brak uprawnień' }
        }
 
        if (order.status !== 'PENDING') {
          return { success: false, error: 'Zamówienie nie może być anulowane' }
        }
 
        await repositories.product.incrementStock(
          order.productId,
          order.quantity,
        )
        const updated = await repositories.order.updateStatus(
          orderId,
          'CANCELLED',
        )
 
        return { success: true, order: updated }
      })
    },
  }
}
 
export const orderService = createOrderService({ unitOfWork })
 
// Czysta funkcja — łatwa do testowania
function calculatePricing(unitPrice: number, quantity: number) {
  const subtotal = unitPrice * quantity
  const discountRate = subtotal > 500 ? 0.1 : subtotal > 200 ? 0.05 : 0
  const discount = subtotal * discountRate
  const finalPrice = subtotal - discount
 
  return { subtotal, discountRate, discount, finalPrice }
}

Granice odpowiedzialności

Ten podział działa tylko wtedy, gdy każda warstwa robi swoją część pracy:

Warstwa	Odpowiedzialność
Server Action	formularz, sesja użytkownika, walidacja inputu, rewalidacja cache
Route Handler	HTTP, statusy odpowiedzi, walidacja JSON, mapowanie błędów na response
Service	reguły biznesowe, orkiestracja, decyzja o transakcji
Repository	zapytania do bazy i szczegóły ORM
Czyste funkcje domenowe	obliczenia bez efektów ubocznych, np. cena, rabat, limity
`revalidatePath` / cache	na zewnątrz service, bo to szczegół interfejsu Next.js

Wspólna walidacja wejścia

Server Action i Route Handler mogą mieć różne protokoły wejścia, ale powinny kończyć z tym samym bezpiecznym typem domenowym. Najprościej wynieść schemat Zod do wspólnego pliku:

Code

// schemas/order-schema.ts
import { z } from 'zod'
 
export const createOrderSchema = z.object({
  productId: z.string().uuid(),
  quantity: z.coerce.number().int().min(1).max(100),
})
 
export type CreateOrderDto = z.infer<typeof createOrderSchema>

Server Actions — cienka warstwa wejścia

Po separacji Server Actions stają się cienką warstwą wejścia dla formularzy i mutacji Reacta: autoryzacja, walidacja inputu, wywołanie serwisu, rewalidacja cache.

Code

// actions/order-actions.ts
'use server'
 
import { auth } from '@/lib/auth'
import { revalidatePath } from 'next/cache'
import { orderService } from '@/services/order-service'
import { createOrderSchema } from '@/schemas/order-schema'
 
export async function createOrderAction(formData: FormData) {
  // 1. Autoryzacja
  const session = await auth()
  if (!session) return { error: 'Musisz być zalogowany' }
 
  // 2. Walidacja inputu
  const parsed = createOrderSchema.safeParse({
    productId: formData.get('productId'),
    quantity: formData.get('quantity'),
  })
 
  if (!parsed.success) {
    return { error: 'Nieprawidłowe dane', details: parsed.error.flatten() }
  }
 
  // 3. Delegacja do serwisu
  const result = await orderService.createOrder({
    userId: session.user.id,
    ...parsed.data,
  })
 
  // 4. Rewalidacja cache
  if (result.success) {
    revalidatePath('/orders')
    revalidatePath('/products')
  }
 
  return result
}
 
export async function cancelOrderAction(orderId: string) {
  const session = await auth()
  if (!session) return { error: 'Musisz być zalogowany' }
 
  const result = await orderService.cancelOrder(orderId, session.user.id)
 
  if (result.success) {
    revalidatePath('/orders')
  }
 
  return result
}

Route Handlers — ten sam serwis, inne wejście

Code

// app/api/orders/route.ts
import { auth } from '@/lib/auth'
import { orderService } from '@/services/order-service'
import { createOrderSchema } from '@/schemas/order-schema'
 
export async function POST(request: Request) {
  const session = await auth()
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }
 
  const body = await request.json()
  const parsed = createOrderSchema.safeParse(body)
 
  if (!parsed.success) {
    return Response.json(
      { error: 'Invalid payload', details: parsed.error.flatten() },
      { status: 422 },
    )
  }
 
  const result = await orderService.createOrder({
    userId: session.user.id,
    ...parsed.data,
  })
 
  if (!result.success) {
    return Response.json({ error: result.error }, { status: 400 })
  }
 
  return Response.json(result.order, { status: 201 })
}

Server Action i Route Handler używają tego samego serwisu — logika biznesowa istnieje w jednym miejscu.

Testowanie

Największa korzyść tej architektury: testowanie bez bazy danych.

Code

// __tests__/services/order-service.test.ts
import { createOrderService } from '@/services/order-service'
import { vi, describe, it, expect, beforeEach } from 'vitest'
 
describe('orderService.createOrder', () => {
  const productRepository = {
    findById: vi.fn(),
    decrementStockIfAvailable: vi.fn(),
    incrementStock: vi.fn(),
  }
 
  const orderRepository = {
    findById: vi.fn(),
    create: vi.fn(),
    updateStatus: vi.fn(),
  }
 
  const unitOfWork = {
    transaction: vi.fn(async (callback) =>
      callback({
        product: productRepository,
        order: orderRepository,
      }),
    ),
  }
 
  const orderService = createOrderService({ unitOfWork })
 
  beforeEach(() => {
    vi.clearAllMocks()
  })
 
  it('should create order when product is available', async () => {
    productRepository.findById.mockResolvedValue({
      id: '1',
      name: 'Test',
      price: 100,
      stock: 10,
      category: 'test',
    })
 
    productRepository.decrementStockIfAvailable.mockResolvedValue({ count: 1 })
 
    orderRepository.create.mockResolvedValue({
      id: 'order-1',
      userId: 'user-1',
      productId: '1',
      quantity: 2,
      total: 200,
      status: 'PENDING',
    })
 
    const result = await orderService.createOrder({
      userId: 'user-1',
      productId: '1',
      quantity: 2,
    })
 
    expect(result.success).toBe(true)
    expect(result.order?.total).toBe(200)
    expect(productRepository.decrementStockIfAvailable).toHaveBeenCalledWith(
      '1',
      2,
    )
    expect(unitOfWork.transaction).toHaveBeenCalledTimes(1)
  })
 
  it('should fail when product out of stock', async () => {
    productRepository.findById.mockResolvedValue({
      id: '1',
      name: 'Test',
      price: 100,
      stock: 1,
      category: 'test',
    })
 
    const result = await orderService.createOrder({
      userId: 'user-1',
      productId: '1',
      quantity: 5,
    })
 
    expect(result.success).toBe(false)
    expect(result.error).toContain('Dostępne sztuki')
    expect(orderRepository.create).not.toHaveBeenCalled()
  })
})

Struktura plików

Code

src/
├── repositories/        ← Dostęp do danych (ORM)
│   └── create-repositories.ts
├── services/            ← Logika biznesowa
│   ├── order-service.ts
│   ├── pricing-service.ts
│   └── notification-service.ts
├── schemas/             ← Wspólna walidacja wejścia
│   └── order-schema.ts
├── actions/             ← Server Actions (cienkie adaptery)
│   ├── order-actions.ts
│   └── product-actions.ts
├── lib/
│   ├── db.ts
│   └── unit-of-work.ts  ← Transakcje dla przypadków użycia
├── app/
│   ├── api/             ← Route Handlers (cienkie adaptery)
│   └── ...
└── types/               ← Interfejsy i typy
    └── index.ts

Kiedy nie używać tego wzorca

Nie każdy projekt potrzebuje pełnego zestawu warstw. Jeśli masz małą stronę z panelem administracyjnym, trzy tabele i proste operacje CRUD, zacznij od prostszej struktury:

schema Zod blisko Server Action,
jedno zapytanie Prisma/Drizzle w funkcji,
brak osobnego service, dopóki nie ma reguł biznesowych,
refaktor dopiero wtedy, gdy ta sama logika pojawia się w drugim miejscu.

Werdykt Labu

Elastyczne i wydajne narzędzia dla biznesu, które dotrzymają kroku Twojemu rozwojowi.

Next.js

Wzorzec Repository + Service Layer w Next.js full-stack — backend, który nie boli

Problem: logika biznesowa w Server Actions

Warstwa Repository — abstrakcja dostępu do danych

Korzyści Repository

Unit of Work — transakcja dla przypadku użycia

Warstwa Service — logika biznesowa

Granice odpowiedzialności

Wspólna walidacja wejścia

Server Actions — cienka warstwa wejścia

Route Handlers — ten sam serwis, inne wejście

Testowanie

Struktura plików

Kiedy nie używać tego wzorca

Czytaj dalej

Wzorzec Repository + Service Layer w Next.js full-stack — backend, który nie boli

Problem: logika biznesowa w Server Actions

Warstwa Repository — abstrakcja dostępu do danych

Korzyści Repository

Unit of Work — transakcja dla przypadku użycia

Warstwa Service — logika biznesowa

Granice odpowiedzialności

Wspólna walidacja wejścia

Server Actions — cienka warstwa wejścia

Route Handlers — ten sam serwis, inne wejście

Testowanie

Struktura plików

Kiedy nie używać tego wzorca

Czytaj dalej