Node.js та Koa: повний цикл бекенду — middleware, валідація, деплой

Koa — мінімалістичний фреймворк від творців Express, переосмислений під async/await. Там де Express вимагає next() і колбеків, Koa працює через async/await і стек middleware, який виконується за принципом «цибулі»: запит проходить middleware зверху вниз, потім відповідь — знизу вгору. Це принципова відмінність: після await next() ви повертаєтеся назад у middleware з доступом до фінального стану відповіді. Вибирають Koa тоді, коли потрібна повна свобода вибору бібліотек без думок фреймворку, але з нормальною обробкою async-коду на відміну від Express.

Ми використовуємо Koa для проектів, де важлива продуктивність і мінімальний оверхед — це підтверджено досвідом розробки понад 50 API, на одному з яких ми обробляли до 10 000 запитів на секунду на одному інстансі. Оптимізація інфраструктури дозволяє знизити споживання пам'яті на 35%, що дає економію на серверній інфраструктурі до 35% щомісячних витрат. Терміни розробки розраховуються індивідуально.

Як middleware розв'язує типові проблеми Express?

import Koa from 'koa'
import Router from '@koa/router'

const app = new Koa()

app.use(async (ctx, next) => {
  const start = Date.now()
  await next()
  const ms = Date.now() - start
  console.log(`${ctx.method} ${ctx.url} - ${ctx.status} - ${ms}ms`)
})

app.use(async (ctx, next) => {
  try {
    await next()
  } catch (err) {
    ctx.status = err.statusCode || err.status || 500
    ctx.body = {
      error: process.env.NODE_ENV === 'production' ? 'Internal Server Error' : err.message
    }
    ctx.app.emit('error', err, ctx)
  }
})

Цей патерн — основа onion-архітектури. Спробуйте повторити таке в Express без зовнішніх бібліотек: доведеться писати костилі. Koa дає це з коробки. Стек middleware дозволяє реалізувати наскрізну обробку помилок, логування та авторизації без дублювання коду.

Обробка помилок в Koa

Обробка помилок в Koa будується на ланцюжку middleware. Приклад вище показує, як єдиний обробник може перехоплювати будь-які винятки. Додатково можна слухати подію app.on('error', ...) для централізованого логування. Це дозволяє уникнути дублювання коду та гарантує, що кожна помилка буде коректно замаскована в продакшені.

Валідація та аутентифікація без зайвого коду

Валідація через Zod

Koa не включає валідацію — підключаємо Zod:

import { z } from 'zod'

const createProductSchema = z.object({
  name: z.string().min(2).max(255),
  price: z.number().positive(),
  categoryId: z.number().int().positive(),
  description: z.string().optional(),
  attributes: z.record(z.unknown()).optional()
})

const validateBody = (schema) => async (ctx, next) => {
  const result = schema.safeParse(ctx.request.body)
  if (!result.success) {
    ctx.status = 422
    ctx.body = { errors: result.error.flatten().fieldErrors }
    return
  }
  ctx.validatedBody = result.data
  await next()
}

router.post('/products',
  authenticate,
  validateBody(createProductSchema),
  async (ctx) => {
    const product = await ProductService.create(ctx.validatedBody)
    ctx.status = 201
    ctx.body = product
  }
)

Така фабрика middleware дає типізовану та безпечну валідацію без прив'язки до конкретного фреймворку. У комбінації з TypeScript ви отримуєте повний контроль над типами.

JWT аутентифікація

@koa/router — офіційний роутер. Налаштування JWT через koa-jwt або вручну:

import jwt from 'jsonwebtoken'

const authenticate = async (ctx, next) => {
  const authHeader = ctx.headers.authorization
  if (!authHeader?.startsWith('Bearer ')) {
    ctx.throw(401, 'No token provided')
  }
  try {
    const token = authHeader.slice(7)
    ctx.state.user = jwt.verify(token, process.env.JWT_SECRET)
    await next()
  } catch {
    ctx.throw(401, 'Invalid or expired token')
  }
}

Сесії через koa-session + Redis store — ще один поширений сценарій. Час життя сесії налаштовується, рекомендуємо 7 днів для користувацьких сесій.

Чому Koa швидший за Express і коли він не потрібен?

Виграш у продуктивності

Koa написаний з нуля на генераторах та async/await, його ядро важить менше 600 рядків коду. Це безпосередньо впливає на TTFB і дозволяє легко налаштовувати кожен middleware. На відміну від Express, у Koa немає вбудованих допоміжних функцій (наприклад, res.json()), що знижує оверхед. Бенчмарки показують, що Koa обробляє на 15-20% більше запитів на секунду при однаковому навантаженні. Зниження споживання пам'яті сягає 35%, що дозволяє скоротити кількість серверів і заощадити до 30% бюджету на інфраструктуру.

Коли краще вибрати Fastify або NestJS

Koa дає мінімальний оверхед — його ядро важить менше 600 рядків коду. Це безпосередньо впливає на TTFB і дозволяє легко налаштовувати кожен middleware. У поєднанні з TypeScript та сучасними практиками (Repository pattern, BFF) ви отримуєте швидкий та передбачуваний бекенд. Ми гарантуємо стабільну роботу API навіть при високих навантаженнях.

Однак Koa вимагає самостійного збирання: немає вбудованої валідації, немає swagger-генерації, немає DI. Якщо проект зростає і потрібна структура — краще Fastify (продуктивність + схеми) або NestJS (архітектура). Koa залишається актуальним для невеликих API, проксі-серверів і проектів, де команда хоче повний контроль без фреймворк-магії.

Практична структура та процес

Приклад структури проекту

src/
  index.js          # точка входу
  app.js            # створення koa-додатку
  middleware/
    auth.js
    errorHandler.js
    requestLogger.js
    validate.js
  routes/
    index.js
    products.js
    users.js
    orders.js
  services/
    products.js
    users.js
  models/
  config/
  utils/

Розділення на routes, services, models — класичний підхід. Детальніше про Repository pattern описано в документації Microsoft.

Завантаження файлів

@koa/multer для multipart:

import multer from '@koa/multer'
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'

const upload = multer({
  storage: multer.memoryStorage(),
  limits: { fileSize: 10 * 1024 * 1024 },
  fileFilter: (req, file, cb) => {
    if (!file.mimetype.startsWith('image/')) {
      return cb(new Error('Only images allowed'))
    }
    cb(null, true)
  }
})

router.post('/upload',
  authenticate,
  upload.single('file'),
  async (ctx) => {
    const file = ctx.file
    const key = `uploads/${Date.now()}-${file.originalname}`
    await s3.send(new PutObjectCommand({
      Bucket: process.env.S3_BUCKET,
      Key: key,
      Body: file.buffer,
      ContentType: file.mimetype
    }))
    ctx.body = { url: `https://${process.env.CDN_HOST}/${key}` }
  }
)

Обмеження розміру файлу — обов'язковий захист від DoS-атак.

Етапи розробки та орієнтири за строками

1. Аналітика та проектування архітектури — 1–2 дні
2. Налаштування стеку (роути, middleware, БД) — 3–5 днів
3. Реалізація CRUD + аутентифікація — 1–2 тижні
4. Інтеграції (email, файли, платіжки) — 1–2 тижні
5. Тестування (jest + supertest) — 3–5 днів
6. Деплой та документація — 1–2 дні

Що входить в результат

Після завершення розробки ви отримуєте:

• Вихідний код з покриттям тестами не менше 80%
• Документацію API (OpenAPI/Swagger) при необхідності
• Доступи до сервера та репозиторію
• Інструкцію з деплою
• Гарантію на код — 3 місяці безкоштовної підтримки

Простий API для сайту-візитки або лендінгу: 3–6 тижнів. Koa швидко стартує, але вимагає акуратності в організації коду. Оцінимо ваш проект безкоштовно — зв'яжіться, щоб обговорити деталі. Замовте розробку бекенду на Koa вже сьогодні — отримайте консультацію інженера.

Послуги бекенд-розробки: production-grade надійність

На production-сервері о 3:14 ночі черга Laravel Jobs перестала оброблятися — 40 000 необроблених завдань у Redis. Причина: worker упав через memory leak у статичній змінній Eloquent observer, supervisor не перезапустив через misconfigured stopwaitsecs. Ми розбирали такий інцидент на проекті з 500 RPS: діагностика 4 години, фікс — 20 хвилин. Щоб ви не втрачали гроші, пропонуємо послуги бекенд-розробки з акцентом на production-grade надійність — 10+ років досвіду, 50+ проектів, 5 років на ринку. Оцінимо ваш проект за 2 дні.

Які проблеми вирішуємо

N+1 запити: головний вбивця швидкості

N+1 — найпоширеніша причина повільних сторінок у Laravel-додатках. Стандартна історія: сторінка працювала нормально на dev з 10 записами, на production з 10 000 — 8-секундне завантаження.

Laravel Debugbar у dev-оточенні показує кількість запитів. Більше 20 — сигнал для audit.

Model::preventLazyLoading(! app()->isProduction());

Telescope для профілювання: логує всі запити, jobs, mail, notifications з деталізацією. Після впровадження eager loading час завантаження сторінки падає з 8 с до 0.3 с — у 27 разів.

Memory leak у статичних змінних

У Laravel Octane або Swoole додаток тримається в пам’яті між запитами. Статичні змінні не скидаються — призводять до неконтрольованого росту пам’яті. Використовуємо defer-функції та контейнерні біндинги для коректного скидання стану.

Неправильний connection pool

Rails, Laravel, Django відкривають нове з'єднання PostgreSQL на кожен PHP/Python процес. 100 воркерів — 100 з'єднань. PostgreSQL деградує від 200+ активних з'єднань через overhead на управління.

PgBouncer у transaction pooling: 1000 воркерів → 20–50 реальних з'єднань. Це знижує latency на 40% та зменшує витрати на хостинг на 30% — при середній вартості хостингу $2,000/міс економить $600/міс. GIN-індекс для JSONB до 100 разів швидший за B-tree при пошуку.

Як Octane справляється з високим навантаженням?

Laravel Octane (RoadRunner або Swoole) прибирає overhead bootstrap на кожен HTTP-запит. Приріст: 3–8x на синтетичних бенчмарках, 2–4x на реальних додатках. Важливо: не зберігати стан у статичних змінних — застосовуємо це на проектах >1000 RPS.

Як PostgreSQL допомагає уникнути повільних запитів?

Використовуємо composite indexes для WHERE + ORDER BY, partial indexes для фільтрів з високою селективністю, GIN-індекси для JSONB та full-text search. to_tsvector + GIN замість LIKE '%query%' — запобігає seq scan навіть на мільйонах записів. Аналізуємо плани через EXPLAIN ANALYZE та pg_stat_statements.

Як обрати стек для вашого проекту?

Node.js виправданий для realtime: Laravel публікує події в Redis Pub/Sub, Node.js підписується та транслює клієнтам. Go — для goroutines (10k з'єднань на сервер — норма), але розробка повільніша, ніж Laravel.

Чому Redis критичний для продуктивності?

Redis виконує кілька ролей:

Redis Cluster для горизонтального масштабування, Sentinel для автоматичного failover. Замовте консультацію щодо оптимізації Redis для вашого проекту.

Що входить в роботу під ключ

• Архітектурне проектування (документація API, схема БД, діаграма сервісів)
• Реалізація за узгодженим ТЗ з code review
• Налаштування CI/CD (GitHub Actions, Docker), моніторингу (Sentry, Grafana), алертингу
• Навантажувальне тестування (k6, wrk) зі звітом
• Передача вихідних кодів, доступів, інструкція з деплою
• Навчання команди замовника (2–3 сесії)
• Гарантійна підтримка 1 місяць після здачі

Орієнтири по термінах

Вартість розраховується індивідуально після аналізу вимог до навантаження, інтеграцій та бізнес-логіки. Зв'яжіться з нами для безкоштовного аудиту вашого поточного backend — отримайте план оптимізації за 2 дні. Замовте консультацію та дізнайтеся, як знизити витрати на інфраструктуру на 30% без втрати продуктивності.