Bun.js middleware у 2026: що це, як працює, як оптимізувати і де не зламати API
Практичний гайд по middleware у Bun.js: native Bun.serve, Hono, Elysia, auth, CORS, rate limiting, logging, observability, performance, best practices і погані практики. Пояснюємо, коли middleware допомагає, коли створює latency, і як будувати production-ready API на Bun.
Bun.js Middleware Production Guide 2026
Серія про production middleware у Bun.js: огляд, безпека, performance, observability, rate limiting, body parsing, WebSocket/SSE і тестування request pipeline.
Усі статті в цьому гайді
01
Bun.js middleware у 2026: overview, best practices і анти-патерни
Базова ментальна модель middleware у native Bun, Hono та Elysia, з прикладами, оптимізацією і roadmap наступних deep dive статей.
02
Auth middleware у Bun.js: JWT, sessions, API keys і multi-tenant контекст
Як правильно будувати auth middleware у Bun: порядок перевірок, cache, token rotation, tenant context, помилки 401/403 і тестування.
03
Rate limiting у Bun.js: in-memory, Redis, sliding window і edge cases
Детальний розбір rate limiting для Bun API: алгоритми, Redis, distributed limits, abuse protection і graceful degradation.
04
Observability middleware у Bun.js: logs, request id, tracing і latency budgets
Як додати request id, structured logs, timing headers, OpenTelemetry-подібний flow і не перетворити логування на bottleneck.
05
Body parsing і validation у Bun.js: JSON, uploads, streams і payload limits
Як безпечно читати body у Bun, де ставити limits, як не зламати streams, uploads, idempotency і schema validation.
Bun може швидко приймати HTTP-запити, але він не може магічно виправити pipeline, де кожен middleware читає body, створює зайві об'єкти, робить синхронний crypto, пише verbose logs і тягне користувача з бази на кожен публічний endpoint.
Саме тому хороший Bun middleware - це не “додати ще один .use()”. Це дизайн request pipeline: що перевіряється до routing, що після routing, що може short-circuit, що має доступ до body, що кешується, що вимірюється, і що взагалі не повинно бути middleware.
Якщо ви плануєте Bun API у 2026 році, ця стаття допоможе не повторити Node/Express звички там, де Bun дає іншу модель і кращі primitives.
Bun.serve без Express-ілюзій.коротка мапа
Це не tutorial “напиши hello world”. Це практичний огляд для команд, які хочуть будувати Bun API з нормальним request pipeline, а не просто перенести хаос Express middleware в інший runtime.
У класичному Express-мисленні middleware - це функція між request і response, яка може змінити req, змінити res, викликати next() або завершити відповідь. У Bun native модель інша: базовий сервер працює з Web APIs Request і Response, а Bun.serve приймає fetch handler або routes. Тобто “middleware” у native Bun - це не вбудований Express-like механізм, а архітектурний патерн композиції функцій навколо handler. [1][2]
Це важлива різниця. Коли ви пишете native Bun, ви самі вирішуєте, як виглядає pipeline: масив функцій, wrapper навколо handler, маленький router, або повний framework. Bun дає швидкий HTTP server, routes, static responses, file responses, timeouts, request IP, WebSocket controls. Але він не змушує вас приймати одну middleware-модель. [2][3]
Hono і Elysia заповнюють цей шар по-різному. Hono називає middleware “onion structure”: middleware виконується до handler, може await next(), а потім змінити response після handler. Elysia описує lifecycle events: request, parse, transform, beforeHandle, afterHandle, mapResponse, error, afterResponse і trace. [5][6]
Коротко
Bun middleware - це не один API. Це три практичні режими: native композиція навколо Bun.serve, Hono .use() для Web Standards middleware, або Elysia lifecycle hooks для Bun-first framework підхід.
Тут важливо не виривати middleware з контексту runtime. Bun оптимізує HTTP server і routes, Hono оптимізує просту middleware-модель, Elysia оптимізує typed lifecycle. Це різні відповіді на одну задачу.
Bun позиціонуєBun.serveяк high-performance HTTP server, а routes API підтримує static responses, dynamic routes, method handlers і fallbackfetch. [1][2]
Bun.serveHono прямо описує middleware як код, що працює before/after handler, можеawait next()або повернутиResponseдля early-exit. [5]
Elysia розкладає request-response cycle на lifecycle events, де hooks застосовуються до routes у порядку реєстрації. [6]
Висновок
Практичний висновок: не шукайте “один правильний Bun middleware API”. Спочатку оберіть lifecycle модель, яка відповідає вашому продукту.
Якщо API маленький, latency важлива, а команда хоче повний контроль, native Bun pipeline може бути достатнім. Ідея проста: handler приймає Request, повертає Response, а middleware обгортає handler або виконується послідовно до нього.
Найменший корисний патерн виглядає так:
type Handler = (req: Request) => Response | Promise<Response>;
type Middleware = (next: Handler) => Handler;
const withRequestId: Middleware = (next) => async (req) => {
const requestId = crypto.randomUUID();
const res = await next(req);
res.headers.set("x-request-id", requestId);
return res;
};
const withSecurityHeaders: Middleware = (next) => async (req) => {
const res = await next(req);
res.headers.set("x-content-type-options", "nosniff");
res.headers.set("referrer-policy", "strict-origin-when-cross-origin");
return res;
};
const compose = (handler: Handler, middleware: Middleware[]) =>
middleware.reduceRight((next, layer) => layer(next), handler);
const app = compose(
async (req) => {
const url = new URL(req.url);
if (url.pathname === "/health") return new Response("OK");
return Response.json({ ok: true });
},
[withRequestId, withSecurityHeaders],
);
Bun.serve({ fetch: app });Цей підхід легкий, але він накладає відповідальність: ви самі маєте визначити порядок, помилки, контекст, повторне читання body, route matching, типізацію і тестування.
Базова модель middleware pipeline: дешеві перевірки мають відсікати запит до дорогого handler або body parsing.
Скріншот секції native-bun-patternКоли це доречно
Native композиція підходить для малих API, internal services, health/readiness endpoints, custom gateways і performance-sensitive routes. Для великої продуктової API краще швидко оцінити Hono або Elysia.
У 2026 році питання не “чи є middleware у Bun”. Питання - який рівень абстракції вам потрібен і скільки lifecycle-поведінки ви хочете підтримувати самі.
| Підхід | Коли обирати | Сильна сторона | Ризик |
|---|---|---|---|
Native Bun.serve | Малі сервіси, gateways, webhooks, health endpoints, custom routing | Мінімальний overhead, повний контроль над Web Request/Response | Самостійно пишете routing, context, errors, middleware order |
| Hono | API, де потрібні familiar middleware, Web Standards і portability | Проста onion-model, .use(), built-in і third-party middleware [5] | Легко перенести Express-звички і зробити забагато глобальних .use() |
| Elysia | Bun-first API, typed context, validation, plugins, lifecycle hooks | Чіткий request lifecycle і типізація Bun-орієнтованого framework [6][7] | Порядок реєстрації hooks критичний, lifecycle треба знати глибше |
| Express-compatible stack | Міграція існуючого Node app, де middleware ecosystem важливіша за runtime purity | Нижчий migration cost | Частина middleware може покладатися на Node/Express деталі, які треба тестувати |
Три практичні middleware-моделі для Bun API: native контроль, Hono onion middleware або Elysia lifecycle hooks.
Скріншот секції framework-choiceВисновок
Якщо ви починаєте новий Bun API, не тягніть Express-модель автоматично. Native Bun, Hono і Elysia дають різні компроміси між контролем, DX, типізацією і ecosystem-ready middleware.
Хороший middleware вирішує cross-cutting concern. Поганий middleware приховує business logic у глобальному pipeline, де потім ніхто не може зрозуміти, чому route поводиться саме так.
Authentication і authorization
Перевірка JWT/session/API key, нормалізація user/tenant context, ранній 401 або 403. Але business-level permissions краще тримати ближче до use case, а не ховати всю авторизацію в глобальний middleware.
CORS і security headers
Добрий кандидат для middleware, бо правила застосовуються до багатьох routes. Важливо не ставити permissive * всюди, якщо API працює з credentials або приватними даними.
Rate limiting і abuse protection
Middleware може швидко відсікти зайві запити до body parsing і database calls. Для distributed API локального memory limit недостатньо, потрібен shared storage або edge-level policy.
Observability
Request id, structured logs, duration, trace context, error mapping. Це один з найкорисніших middleware-шарів, якщо він не пише надмірні payload-и і не блокує response path.
Body parsing і validation gate
Payload size limits, content-type checks, JSON parsing, schema validation. Важливо пам'ятати: body stream не можна бездумно читати кілька разів у різних шарах.
Response normalization
Єдиний формат помилок, cache headers, timing headers, compression decisions. Але не варто перетворювати response middleware на прихований serializer для всієї бізнес-логіки.
Швидкість Bun не означає, що будь-який middleware автоматично дешевий. Оптимізація pipeline починається з правил виконання, а не з microbenchmark.
Ставте дешеві reject-и перед дорогими операціями
Перевірка method, path, content-type, origin, basic headers і IP allowlist має йти до body parsing, database calls, crypto і remote config. Це зменшує CPU, memory pressure і tail latency.
Не читайте body у глобальному middleware без потреби
У Web API body є stream. Якщо middleware читає await req.json(), handler уже не може прочитати його так само просто. Робіть body parsing у вузькому шарі або передавайте parsed body у контекст явно.
Використовуйте static responses для стабільних routes
Bun routes можуть приймати готові Response objects. Офіційна документація вказує, що static route responses кешуються на lifetime server object і можуть давати performance benefit для health checks, redirects і фіксованих API responses. [2]
Розділяйте middleware для public і private routes
Не змушуйте /health, /ready, /assets/* або public GET routes проходити через auth, session lookup і tenant hydration. У Bun routes wildcard і specific routes дають можливість явно розділити ці поверхні. [2]
Майте latency budget для кожного шару
Logging, auth, rate limit, validation, DB context, response mapping - кожен шар має бюджет. Якщо middleware додає 5-10ms на кожен request, це вже архітектурне рішення, а не дрібниця.
Практичне правило
Оптимальний Bun middleware pipeline короткий, передбачуваний і вимірюваний. Усе, що не має бути глобальним, не повинно бути глобальним.
Не всі оптимізації однаково корисні. Частина з них зменшує latency, частина просто переносить складність у місце, де її важче дебажити.
Добре: static response для health/readiness
Для /health, /ready, простих redirects і fixed config відповідей використовуйте route-level static responses. Це зменшує runtime work і прибирає зайві алокації. [2]
Обережно: глобальний auth middleware
Auth як глобальний шар зручний, але він легко потрапляє на routes, яким не потрібен. Краще явно групувати private API і залишати public/system routes поза цим pipeline.
Добре: request id і timing
Це дешевий і корисний baseline для production debugging. Важливо не логувати повні body і секрети.
Обережно: body parsing до routing
Якщо middleware читає body для кожного request, ви платите ціну навіть там, де body не потрібен. Це особливо болить на uploads, webhooks і streaming routes.
Висновок
Найкраща оптимізація middleware - не виконувати middleware там, де він не потрібен.
Bun має важливу поведінку за замовчуванням: HTTP idleTimeout становить 10 секунд, якщо не налаштовано інакше. Для streaming responses або Server-Sent Events документація рекомендує встановлювати per-request timeout через server.timeout(req, 0), замість того щоб піднімати глобальний timeout для всіх запитів. [3]
Це прямо впливає на middleware. Якщо logging або auth middleware обгортає streaming response так, ніби це звичайний JSON endpoint, ви можете випадково буферизувати відповідь, закрити stream або зробити timeout policy однаковою для всіх routes.
Для WebSockets у Bun є окремі controls: idleTimeout, maxPayloadLength, backpressure через результат .send(), perMessageDeflate. Middleware-мислення тут теж інше: connection upgrade і message lifecycle не треба змішувати з HTTP JSON middleware. [4]
Правило для довгих connections
SSE, streams і WebSockets повинні мати окремий pipeline. Не пропускайте їх через middleware, який припускає короткий request-response JSON flow.
Ці помилки знайомі з Node/Express світу. У Bun вони не стають менш шкідливими, просто маскуються швидшим runtime.
Глобальний middleware для всього: auth, body parsing, logging, rate limit, tenant lookup і validation виконуються навіть для /health.
Повторне читання body у кількох шарах без явного контракту, хто є власником parsed payload.
Зберігання request-specific даних у module-level змінних. У concurrent server це прямий шлях до leakage між запитами.
Синхронні дорогі операції в middleware: crypto, filesystem, compression, великі JSON transforms.
Логування повного request body, cookies, authorization headers або PII.
CORS * для приватних API з credentials.
Rate limiting тільки in-memory у multi-instance production.
Немає єдиного формату помилок: один middleware повертає text, інший JSON, третій кидає exception.
Middleware змінює response так, що handler уже не може гарантувати contract.
Суть
Middleware має робити cross-cutting behavior явним. Якщо він приховує business rules або стан, pipeline стає складнішим за сам application code.
Цей список можна використовувати як review checklist перед запуском Bun API у staging або production.
Окремі pipeline для public, private, system і streaming routes
Не змушуйте різні типи traffic проходити через один набір middleware.
Short-circuit максимально рано
Method/path/content-type/origin/rate limit мають відсікти погані запити до дорогих операцій.
Один власник body parsing
Визначте, хто читає body, де зберігається parsed value і як handler його отримує.
Єдиний формат помилок
Auth, validation, rate limit і internal errors мають повертати прогнозований JSON contract.
Request id всюди
Додавайте request id у response headers і structured logs, щоб дебажити cross-service flow.
Latency budget для кожного middleware
Вимірюйте duration middleware шарів, а не тільки загальний response time.
Без секретів у logs
Authorization, cookies, API keys, tokens і PII мають маскуватися або не логуватися взагалі.
Тести на порядок виконання
Перевіряйте не тільки happy path, а й early exit, error path, missing headers, invalid body, timeout і streaming routes.
Цей пост - overview. Далі логічно розібрати кожен middleware-клас окремо, бо auth, rate limiting, observability і body parsing мають різні failure modes.
Chapter 2
Auth middleware
JWT, sessions, API keys, tenant context, cache, token refresh, 401 проти 403, і як не сховати permissions у глобальному шарі.
Chapter 3
Rate limiting
Fixed window, sliding window, token bucket, Redis, distributed deployment, abusive clients, webhooks і graceful degradation.
Chapter 4
Observability
Request id, structured logs, timing headers, tracing, error correlation і як не перетворити logging на latency bottleneck.
Chapter 5
Body parsing і validation
JSON, multipart, uploads, streams, payload limits, schema validation, idempotency keys і безпечне повторне використання parsed body.
Висновок
Серія буде корисна як production checklist для Bun API, де middleware має бути не декоративним шаром, а керованою частиною архітектури.
Bun дає сильний HTTP runtime, швидкі routes, static responses, Web APIs і низький overhead. Але middleware - це місце, де команди найчастіше повертають собі всю складність старого Node stack: глобальні side effects, body parsing у неправильному місці, logging без бюджету, auth без меж і route behavior, який неможливо пояснити з одного файлу.
Правильний підхід простий: виберіть lifecycle модель, тримайте pipeline коротким, розділяйте routes за типом traffic, вимірюйте latency кожного шару, не читайте body без ownership, і не ховайте business rules у глобальному middleware.
Якщо потрібен мінімальний overhead - пишіть native композицію навколо Bun.serve. Якщо потрібен знайомий middleware flow - беріть Hono. Якщо хочете Bun-first typed lifecycle - дивіться на Elysia. У всіх трьох випадках успіх залежить не від назви framework, а від дисципліни pipeline.
Native `Bun.serve` не нав'язує Express-style `.use()` модель. Він працює через `fetch` handler і `routes`, а middleware у native Bun зазвичай пишуть як композицію функцій навколо `Request`/`Response`. Якщо потрібна готова `.use()` модель, беріть Hono; якщо потрібні lifecycle hooks, дивіться Elysia. [1][5][6]
Hono краще, якщо вам потрібна проста Web Standards middleware-модель, portability і знайомий `.use()` flow. Elysia краще, якщо ви хочете Bun-first framework, typed context, validation і чіткий lifecycle. Native Bun краще для малих або дуже контрольованих services.
Найчастіше проблеми створюють body parsing, auth/session lookup, rate limiting із remote storage, verbose logging, synchronous crypto/compression і middleware, який виконується глобально для routes, де він не потрібен.
Можна, але обережно. Body у Web API є stream, тому middleware має бути явним власником parsing або передати parsed value далі в context. Не читайте body у кількох шарах без контракту.
Розділіть public/private/system/streaming routes, додайте ранні cheap checks, централізуйте error format, не логайте секрети, задайте payload limits, використовуйте request id, тестуйте early exits і вимірюйте latency кожного шару.
Не автоматично. Частина middleware працюватиме через сумісні frameworks або adapters, але Express middleware часто покладається на специфічні мутації `req`/`res`. Для нового Bun API краще спочатку обрати native Bun, Hono або Elysia модель, а потім переносити тільки справді потрібні шари.
Джерела нижче підтверджують API-поведінку Bun, routes/static responses, server lifecycle controls, Hono middleware model і Elysia lifecycle hooks.
• 1. Bun docs - Server: `Bun.serve`, routes, fallback fetch, configuration, lifecycle methods
• 2. Bun docs - Routing: route precedence, type-safe params, static responses, file responses
• 3. Bun docs - Server idleTimeout and per-request `server.timeout(req, seconds)`
• 4. Bun docs - WebSockets: compression, backpressure, idle timeout, max payload length
• 5. Hono docs - Middleware guide: before/after handler, `await next()`, early response
• 8. Bun docs - Runtime options including `--max-http-header-size`
PAS7 Studio може допомогти спроектувати Bun backend, провести audit request pipeline, розділити middleware по routes, додати observability, security baseline і performance checks.
Це особливо корисно, якщо ви мігруєте з Express/Fastify, запускаєте новий Bun API або хочете зрозуміти, де саме middleware створює latency і ризики.
Bun.js middleware у 2026: overview, best practices і анти-патерни
Пов'язані статті
Скільки коштує розробка AI асистента у 2026: RAG чатбот, база знань, CRM, Telegram та підтримка
Практичний гід для бізнесу: від чого залежить ціна розробки AI асистента у 2026 році, що входить у RAG чатбот, інтеграції з CRM, Telegram, guardrails, оцінювання, моніторинг і супровід.
AI для розробки лендінгів: де він реально прискорює запуск, а де псує конверсію
Дослідження про використання AI у розробці лендінгів: v0, Webflow AI, Builder.io, Framer-подібні AI builders, генерація UX, copy, SEO, персоналізація, A/B тести, ризики шаблонності, безпеки, доступності та технічного боргу.
AI SEO / GEO у 2026: ваші наступні клієнти — не люди, а агенти
Пошук зміщується від кліків до відповідей. Боти та AI-агенти сканують, цитують, рекомендують і дедалі частіше купують. Дізнайтесь, що таке AI SEO / GEO, чому класичного SEO вже недостатньо, і як PAS7 Studio допомагає брендам перемагати у «агентному» вебі.
Найпотужніший чіп від Apple? M5 Pro і M5 Max б'ють рекорди
Аналітичний розбір Apple M5 Pro і M5 Max станом на березень 2026 року. Пояснюємо, чому ці чіпи можна вважати найпотужнішими професійними ноутбучними SoC від Apple, як вони виглядають на тлі M4 Pro, M4 Max, M1 Pro, M1 Max і що показують у порівнянні з актуальними Intel та AMD.
Професійна розробка для вашого бізнесу
Створюємо сучасні веб-рішення та боти для бізнесу. Дізнайтеся, як ми можемо допомогти вам досягти цілей.