Erstellen Sie Ihre erste API mit Koa

Wenn Sie JavaScript beherrschen und eine Backend-API entwickeln möchten, ist Koa einen genaueren Blick wert. Es ist minimalistisch, modern und von Grund auf um async/await herum gebaut – was saubereren Code und keine Callback-Hölle bedeutet. Dieses Koa-API-Tutorial führt Sie durch die Grundlagen: Einrichten eines Projekts, Verstehen der Middleware-Funktionsweise und Erstellen einer kleinen REST-API mit GET- und POST-Endpunkten.

Voraussetzungen

• Node.js 20+ (aktuelle LTS-Version empfohlen)
• Grundlegende JavaScript-Kenntnisse, einschließlich async/await
• Ein Terminal und ein Texteditor

Was ist Koa und warum sollten Sie es verwenden?

Koa ist ein schlankes Node.js-Web-Framework, das vom Team hinter Express entwickelt wurde. Anders als Express hat Koa keine gebündelte Middleware – Sie fügen nur hinzu, was Sie benötigen. Sein herausragendes Merkmal ist die Middleware-Kaskade, manchmal auch „Zwiebel-Modell” genannt, bei der jede Middleware-Funktion Code vor und nach der nächsten in der Kette ausführt.

Dies macht die Koa-API-Grundlagen einfach nachvollziehbar: Jede Anfrage fließt nach innen durch Ihren Middleware-Stack, und die Antwort fließt nach außen zurück.

Schritt 1 — Richten Sie Ihr Projekt ein

Erstellen Sie ein neues Verzeichnis und initialisieren Sie es:

mkdir koa-items-api && cd koa-items-api
npm init -y

Fügen Sie "type": "module" zu package.json hinzu, um die ES-Modul-Syntax zu verwenden, und installieren Sie dann die Abhängigkeiten:

npm install koa @koa/router @koa/bodyparser

• koa — das Kern-Framework
• @koa/router — offizielle Routing-Middleware
• @koa/bodyparser — parst eingehende JSON-Request-Bodies

Schritt 2 — Verstehen Sie die Koa-Middleware-API

Jede Koa-Middleware ist eine async-Funktion, die ein ctx-(Context-)Objekt und eine next-Funktion erhält. Das ctx-Objekt kombiniert Request und Response an einem Ort – ctx.method, ctx.path, ctx.request.body und ctx.body (die Response) befinden sich alle dort.

Der Aufruf von await next() übergibt die Kontrolle an die nächste Middleware. Hier ist ein einfaches Logging-Beispiel:

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

Beachten Sie, dass Code nach await next() ausgeführt wird, sobald die nachgelagerte Middleware fertig ist. Das ist das Zwiebel-Modell in Aktion.

Schritt 3 — Erstellen Sie eine REST-API mit Koa

Erstellen Sie app.js mit einer kleinen In-Memory-Items-API:

import Koa from "koa"
import Router from "@koa/router"
import  bodyParser  from  "@koa/bodyparser"

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

// In-Memory-Datenspeicher
let nextId = 3
let items = [
  { id: 1, name: "Keyboard" },
  { id: 2, name: "Monitor" },
]

// GET /items — alle Items zurückgeben
router.get("/items", (ctx) => {
  ctx.body = { success: true, data: items }
})

// GET /items/:id — ein Item zurückgeben
router.get("/items/:id", (ctx) => {
  const item = items.find((i) => i.id === Number(ctx.params.id))
  if (!item) {
    ctx.status = 404
    ctx.body = { error: "Item not found" }
    return
  }
  ctx.body = { success: true, data: item }
})

// POST /items — ein neues Item erstellen
router.post("/items", (ctx) => {
  const { name } = ctx.request.body
  if (!name) {
    ctx.status = 400
    ctx.body = { error: "Name is required" }
    return
  }
  const newItem = { id: nextId++, name }
  items.push(newItem)
  ctx.status = 201
  ctx.body = { success: true, data: newItem }
})

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

app.listen(3000, () => console.log("Server running on http://localhost:3000"))

Hinweis: Der ursprüngliche Ansatz id: items.length + 1 funktioniert nicht mehr, wenn Sie jemals ein Item löschen, da die Array-Länge schrumpft, während bestehende IDs dies nicht tun. Ein separater nextId-Zähler vermeidet doppelte IDs.

Starten Sie den Server:

node app.js

Testen Sie Ihre Endpunkte

Alle Items abrufen:

curl http://localhost:3000/items

Ein Item erstellen:

curl -X POST http://localhost:3000/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Mouse"}'

Erwartete Antwort:

{ "success": true, "data": { "id": 3, "name": "Mouse" } }

Ein fehlendes Item anfordern:

curl http://localhost:3000/items/99

{ "error": "Item not found" }

router.allowedMethods() behandelt nicht unterstützte HTTP-Methoden automatisch und gibt eine korrekte 405 Method Not Allowed-Antwort zurück, ohne zusätzlichen Code.

Fazit

Koas Stärke ist seine Einfachheit. Das ctx-Objekt hält Request- und Response-Handling an einem Ort, und die Middleware-Kaskade gibt Ihnen präzise Kontrolle darüber, wie Anfragen durch Ihre Anwendung fließen. Diese Grundlage – ein Koa-Server, @koa/router für Routing und @koa/bodyparser für JSON-Parsing – ist alles, was Sie brauchen, um mit dem Erstellen einer REST-API mit Koa zu beginnen. Von hier aus können Sie Schritt für Schritt eine echte Datenbank, Validierung oder Error-Handling-Middleware hinzufügen.

Häufig gestellte Fragen

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.