[Framework] Koa.js

Koa, Koa.js, koajs, koa framework, koa nodejs, TJ Holowaychuk Koa, koa 3

정의

Koa.js 는 Express 창시자 TJ Holowaychuk 이 2013년 발표한 Node.js 웹 프레임워크 입니다. Express 의 후계자 성격이며, 미들웨어를 async/await 로 자연스럽게 표현 하고 양파 (onion) 모델 로 요청/응답을 감쌉니다. 초경량 코어 (약 500 LOC), 라우팅과 body parsing 은 별도 패키지.

2024-2025 년 현재 Koa 2.15+ 또는 Koa 3.x (async/await native, Node 20+) 이 사용됩니다.

왜 Koa 인가

• 작고 명료: 코어에 라우팅 없음. 필요한 것만 조합.
• async/await 우선: Express 의 callback 지옥 없음.
• Onion middleware: await next() 로 downstream + upstream 를 자연스럽게.
• Context (ctx): request + response 를 감싼 하나의 객체.
• Error 처리 단순: try/catch 로 미들웨어 예외 잡음.
• 경량: 저지연, 오버헤드 최소.

단점:

• 생태계가 Express 대비 좁음
• 큰 앱 구조는 스스로 설계 (NestJS 같은 opinionated 프레임워크 없음)
• 학습 자료 (블로그, 예시) 적음

설치 & 최소 예제

mkdir myapp && cd myapp
npm init -y
npm i koa

// server.js
const Koa = require('koa');
const app = new Koa();

app.use(async (ctx) => {
  ctx.body = 'Hello Koa';
});

app.listen(3000);

node server.js
# curl http://localhost:3000  ->  Hello Koa

Context (ctx)

Koa 의 핵심. request + response 통합.

app.use(async (ctx, next) => {
  console.log(ctx.method);           // 'GET'
  console.log(ctx.path);              // '/users/1'
  console.log(ctx.query);             // {page: '1'}
  console.log(ctx.headers);           // 헤더
  console.log(ctx.request.body);      // body (parser 필요)

  ctx.status = 201;
  ctx.body = {ok: true};              // 자동 JSON 직렬화
  ctx.set('X-Custom', 'value');       // 응답 헤더
});

자세한 것은 Koa Context 참조.

Middleware (Onion 모델)

app.use(async (ctx, next) => {
  console.log('A pre');
  await next();
  console.log('A post');
});

app.use(async (ctx, next) => {
  console.log('B pre');
  await next();
  console.log('B post');
});

app.use(async (ctx) => {
  console.log('C');
  ctx.body = 'ok';
});

// 요청 시 출력:
// A pre
//   B pre
//     C
//   B post
// A post

각 미들웨어의 await next() 이전은 downstream 방향, 이후는 upstream 방향. 요청 처리 완료를 순차 관측 가능.

자세한 것은 Koa Middleware 참조.

라우팅 (@koa/router)

npm i @koa/router

const Koa = require('koa');
const Router = require('@koa/router');

const app = new Koa();
const router = new Router();

router.get('/', async (ctx) => {
  ctx.body = 'Home';
});

router.get('/users/:id', async (ctx) => {
  ctx.body = { id: ctx.params.id };
});

router.post('/users', async (ctx) => {
  ctx.body = ctx.request.body;
});

app.use(router.routes()).use(router.allowedMethods());

app.listen(3000);

자세한 것은 Koa Router 참조.

Body Parser (@koa/bodyparser)

npm i @koa/bodyparser

const bodyParser = require('@koa/bodyparser');
app.use(bodyParser());

router.post('/echo', async (ctx) => {
  ctx.body = ctx.request.body;
});

자세한 것은 Koa Body Parsing 참조.

흔한 조합 (스택)

목적	패키지
라우팅	@koa/router
Body	@koa/bodyparser, koa-body (파일 업로드)
Multipart	@koa/multer
CORS	@koa/cors
Session	koa-session
Cookie	내장 (ctx.cookies)
Compression	koa-compress
Logger	koa-logger, koa-pino-logger
Static	koa-static
JWT	koa-jwt, jose
Rate limit	koa-ratelimit
Views (Jinja)	@ladjs/koa-views
Error	내장 + app.on('error', ...)

Async / Promise 지원

Koa 는 처음부터 async 지원. 미들웨어가 Promise 를 리턴하거나 async 함수.

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
});

Error 처리

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {
      error: err.message,
      ...(process.env.NODE_ENV !== 'production' && {stack: err.stack}),
    };
    ctx.app.emit('error', err, ctx);
  }
});

app.on('error', (err, ctx) => {
  console.error('server error', err);
});

Koa 는 기본적으로 ctx.status = 4xx/5xx + ctx.throw(4xx, 'message') 지원. 자세한 것은 Koa Error Handling 참조.

응답 반환

ctx.body = 'string';       // text/plain (또는 text/html 자동 감지)
ctx.body = { a: 1 };       // JSON
ctx.body = buffer;         // binary
ctx.body = stream;         // streaming
ctx.body = null;           // 204 no content

Status:

ctx.status = 201;
ctx.throw(404, 'Not found');       // 예외 발생
ctx.assert(user, 401, 'Login required');

Header:

ctx.set('Content-Type', 'application/json');
ctx.append('Set-Cookie', '...');
ctx.remove('X-Foo');

Redirect:

ctx.redirect('/login');
ctx.redirect('back', '/');    // Referer 기반

Config

Koa 자체는 config 없음. dotenv, config, zod 조합.

require('dotenv').config();

const app = new Koa();
app.proxy = process.env.NODE_ENV === 'production';   // X-Forwarded-* 신뢰

TypeScript 지원

@types/koa, @types/koa__router. 하지만 완전한 TS-first 는 아님. NestJS 처럼 완전한 타입 안전 원하면 그쪽.

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

interface AppState { user?: User; }
interface AppContext { db: DatabaseService; }

const app = new Koa<AppState, AppContext>();
const router = new Router<AppState, AppContext>();

router.get('/me', async (ctx) => {
  const user = ctx.state.user;   // typed
  const users = await ctx.db.query(...);  // typed
  ctx.body = user;
});

ctx.state 는 request 스코프 저장, ctx 확장은 앱 스코프.

프로젝트 구조 (실전)

myapp/
├── src/
│   ├── app.js                # createApp
│   ├── server.js              # 진입점 (listen)
│   ├── config/
│   │   └── index.js
│   ├── middleware/
│   │   ├── error.js
│   │   ├── logger.js
│   │   ├── auth.js
│   │   └── request-id.js
│   ├── routes/
│   │   ├── index.js           # router combine
│   │   ├── users.js
│   │   └── posts.js
│   ├── services/
│   │   └── db.js
│   ├── models/
│   └── utils/
├── test/
├── package.json
└── .env

app.js:

const Koa = require('koa');
const bodyParser = require('@koa/bodyparser');
const cors = require('@koa/cors');
const helmet = require('koa-helmet');

const errorMiddleware = require('./middleware/error');
const loggerMiddleware = require('./middleware/logger');
const routes = require('./routes');

function createApp() {
  const app = new Koa();
  app.proxy = true;

  app.use(errorMiddleware);
  app.use(loggerMiddleware);
  app.use(helmet());
  app.use(cors({origin: 'https://app.example.com', credentials: true}));
  app.use(bodyParser({jsonLimit: '1mb'}));
  app.use(routes.routes()).use(routes.allowedMethods());

  return app;
}

module.exports = createApp;

server.js:

const createApp = require('./app');
const app = createApp();

const server = app.listen(process.env.PORT || 3000, () => {
  console.log(`Listening on ${process.env.PORT || 3000}`);
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  server.close(() => process.exit(0));
});

Fastify 와의 관계

Fastify 는 Koa 이후 등장한 성능 지향 프레임워크. Fastify 가 더 빠르고 (JSON stringify 캐싱, plugin 시스템), 스키마 지원 우수. Koa 는 가벼움 + async/await 초점, Fastify 는 성능 + 표준화.

Express 와의 관계

Koa 는 Express 의 후계자로 시작. TJ 가 Express 를 인수인계 후 Koa 를 만듦. 오늘날 두 프레임워크 병존. 자세한 것은 Koa vs Express 참조.

실전 예: JSON API

const Koa = require('koa');
const Router = require('@koa/router');
const bodyParser = require('@koa/bodyparser');

const app = new Koa();
const router = new Router();

// Global error
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {error: err.message};
  }
});

app.use(bodyParser());

// Routes
router.get('/users', async (ctx) => {
  ctx.body = await getUsersFromDb();
});

router.get('/users/:id', async (ctx) => {
  const user = await getUserById(ctx.params.id);
  ctx.assert(user, 404, 'User not found');
  ctx.body = user;
});

router.post('/users', async (ctx) => {
  const {email, name} = ctx.request.body;
  ctx.assert(email, 400, 'email required');
  const user = await createUser({email, name});
  ctx.status = 201;
  ctx.body = user;
});

app.use(router.routes()).use(router.allowedMethods());

app.listen(3000);

함정

관련 위키

• Koa Context - ctx 심화
• Koa Middleware - Onion 모델
• Koa Router - 라우팅
• Koa Body Parsing
• Koa Error Handling
• Koa Testing
• Koa Deployment
• Koa vs Express
• NestJS - 대비 (opinionated)
• FastAPI - Python 대비
• Flask - Python 마이크로프레임워크 대비
• JavaScript async/await
• JavaScript Promise