Hono: rangka kerja web ultra-laju yang dibina di atas Web Standards

Selama bertahun-tahun, memilih rangka kerja web JavaScript bermakna menerima kompromi: Express adalah sejagat tetapi perlahan dan terikat dengan Node, Fastify pantas tetapi hanya Node, Next.js berciri penuh tetapi berat. Apabila runtime edge — Cloudflare Workers, Deno Deploy, Bun, Vercel Edge — muncul, rangka kerja itu menunjukkan hadnya.

Hono (Jepun untuk "api" 🔥) ialah jawapan moden. Rangka kerja di bawah 14KB, dibina sepenuhnya di atas Web Standards (Request, Response, fetch), berjalan di mana-mana terdapat runtime JavaScript. Kod yang sama disebarkan ke Cloudflare Workers, Bun, Deno, Node.js, Vercel, Netlify dan AWS Lambda — tanpa perubahan.

Mengapa Hono

1. Prestasi. RegExpRouter mengkompil semua corak laluan kepada satu regex. Penanda aras melebihi 400,000 ops/s.
2. Mudah alih. Web Standards bermaksud sifar kebergantungan Node.
3. DX TypeScript-first. Parameter laluan disimpulkan sebagai literal type, klien RPC selamat-jenis end-to-end.

Memulakan

npm create hono@latest my-api
cd my-api
npm install
npm run dev

// src/index.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.text('Hello Hono!'))

export default app

Pada Cloudflare Workers, ini sudah memadai. Pada Bun: Bun.serve({ fetch: app.fetch, port: 3000 }). Pada Node: serve({ fetch: app.fetch }) daripada @hono/node-server.

Routing

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.text('Home'))
app.get('/posts/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ id })
})
app.get('/posts/:id/comments/:commentId', (c) => {
  const { id, commentId } = c.req.param()
  return c.json({ id, commentId })
})
app.get('/files/*', (c) => c.text('Wildcard'))
app.post('/posts', async (c) => {
  const body = await c.req.json()
  return c.json({ created: body }, 201)
})

Pengelompokan laluan

// routes/posts.ts
import { Hono } from 'hono'

const posts = new Hono()
posts.get('/', (c) => c.json({ posts: [] }))
posts.get('/:id', (c) => c.json({ id: c.req.param('id') }))
export default posts

// src/index.ts
import { Hono } from 'hono'
import posts from './routes/posts'

const app = new Hono()
app.route('/posts', posts)

Objek Context

app.post('/echo', async (c) => {
  const userAgent = c.req.header('User-Agent')
  const page = c.req.query('page')
  const body = await c.req.json()
  const env = c.env

  c.set('requestId', crypto.randomUUID())
  const id = c.get('requestId')

  c.header('X-Request-Id', id)
  c.status(200)
  return c.json({ userAgent, page, body, id })
})

Middleware: model bawang

import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { secureHeaders } from 'hono/secure-headers'

const app = new Hono()

app.use('*', logger())
app.use('*', secureHeaders())
app.use('/api/*', cors({ origin: 'https://spinny.dev' }))

app.use('*', async (c, next) => {
  const start = performance.now()
  await next()
  c.header('X-Response-Time', `${performance.now() - start}ms`)
})

Middleware terbina

Middleware	Tujuan
logger	Log berstruktur kaedah, laluan, status, tempoh
cors	CORS boleh dikonfigurasi mengikut origin, kaedah, header
csrf	Perlindungan CSRF berasaskan origin
secureHeaders	Menetapkan CSP, HSTS, X-Frame-Options
bearerAuth / basicAuth	Auth Bearer/Basic siap pakai
jwt	JWT sahkan/tandatangan dengan jose
etag	Menjana ETag dan mengendalikan 304
cache	Cache melalui Web Cache API
compress	gzip/deflate pada respons
bodyLimit	Menolak body melebihi ambang
timing	Header Server-Timing untuk profiling

Middleware tersuai selamat-jenis

import { createMiddleware } from 'hono/factory'

type AuthVars = { userId: string; role: 'user' | 'admin' }

export const requireAuth = createMiddleware<{ Variables: AuthVars }>(
  async (c, next) => {
    const token = c.req.header('Authorization')?.replace('Bearer ', '')
    if (!token) return c.json({ error: 'Unauthorized' }, 401)

    const payload = await verifyJwt(token)
    c.set('userId', payload.sub)
    c.set('role', payload.role)
    await next()
  }
)

app.get('/me', requireAuth, (c) => {
  const userId = c.var.userId
  return c.json({ userId })
})

Validasi dengan Zod

import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const createPost = z.object({
  title: z.string().min(1).max(200),
  body: z.string().min(1),
  tags: z.array(z.string()).default([]),
})

app.post(
  '/posts',
  zValidator('json', createPost),
  (c) => {
    const data = c.req.valid('json')
    return c.json({ ok: true, post: data }, 201)
  }
)

RPC: klien selamat-jenis end-to-end

// server.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const app = new Hono()
  .get('/posts/:id', (c) =>
    c.json({ id: c.req.param('id'), title: 'Hello' })
  )
  .post(
    '/posts',
    zValidator('json', z.object({ title: z.string(), body: z.string() })),
    (c) => c.json({ ok: true }, 201)
  )

export type AppType = typeof app
export default app

// client.ts
import { hc } from 'hono/client'
import type { AppType } from './server'

const client = hc<AppType>('https://api.spinny.dev')

const res = await client.posts[':id'].$get({ param: { id: '42' } })
if (res.ok) {
  const data = await res.json()
  console.log(data.title)
}

const created = await client.posts.$post({
  json: { title: 'Helo', body: 'Hono adalah api' },
})

Diskriminasi kod status

.get('/posts/:id', (c) => {
  const post = findPost(c.req.param('id'))
  if (!post) return c.json({ error: 'not found' }, 404)
  return c.json({ post }, 200)
})

const res = await client.posts[':id'].$get({ param: { id } })
if (res.status === 404) {
  const { error } = await res.json()
}
if (res.status === 200) {
  const { post } = await res.json()
}

Penghala dan prestasi

Penghala	Kekuatan	Bila digunakan
RegExpRouter	Kelajuan maksimum, regex terkompil	Lalai untuk kebanyakan API
TrieRouter	Menyokong semua corak	Corak kompleks yang RegExp tidak boleh kendalikan
SmartRouter	Memilih yang terbaik secara automatik	Lalai disyorkan
LinearRouter	Pendaftaran ultra-laju	Pekerja sekali tembak, cold start kritikal
PatternRouter	Bundle minimum (<15KB)	Kekangan saiz melampau

import { Hono } from 'hono'
import { LinearRouter } from 'hono/router/linear-router'

const app = new Hono({ router: new LinearRouter() })

Deploy pelbagai runtime

Cloudflare Workers

import { Hono } from 'hono'

type Bindings = { MY_KV: KVNamespace; DB: D1Database }
const app = new Hono<{ Bindings: Bindings }>()

app.get('/cache/:key', async (c) => {
  const value = await c.env.MY_KV.get(c.req.param('key'))
  return c.json({ value })
})

export default app

Deploy: npx wrangler deploy.

Bun

import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => c.text('Bun + Hono'))

Bun.serve({ fetch: app.fetch, port: 3000 })

Node.js

import { serve } from '@hono/node-server'
import { Hono } from 'hono'

const app = new Hono()
app.get('/', (c) => c.text('Node + Hono'))

serve({ fetch: app.fetch, port: 3000 })

Deno

import { Hono } from 'jsr:@hono/hono'
const app = new Hono()
app.get('/', (c) => c.text('Deno + Hono'))
Deno.serve(app.fetch)

Vercel

// api/[[...route]].ts
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

const app = new Hono().basePath('/api')
app.get('/hello', (c) => c.json({ msg: 'Hello from Vercel' }))

export const GET = handle(app)
export const POST = handle(app)

Contoh praktikal: REST API dengan auth dan DB

import { Hono } from 'hono'
import { jwt } from 'hono/jwt'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

type Bindings = { DB: D1Database; JWT_SECRET: string }
type Variables = { jwtPayload: { sub: string } }

const app = new Hono<{ Bindings: Bindings; Variables: Variables }>()

app.use('*', logger())
app.use('/api/*', cors({ origin: 'https://spinny.dev', credentials: true }))

const auth = (c: any, next: any) =>
  jwt({ secret: c.env.JWT_SECRET })(c, next)

const api = app.basePath('/api')

api.get('/posts', async (c) => {
  const { results } = await c.env.DB
    .prepare('SELECT id, title, created_at FROM posts ORDER BY created_at DESC LIMIT 50')
    .all()
  return c.json({ posts: results })
})

api.post(
  '/posts',
  auth,
  zValidator('json', z.object({
    title: z.string().min(1).max(200),
    body: z.string().min(1),
  })),
  async (c) => {
    const { title, body } = c.req.valid('json')
    const userId = c.var.jwtPayload.sub
    const result = await c.env.DB
      .prepare('INSERT INTO posts (title, body, author_id) VALUES (?, ?, ?) RETURNING id')
      .bind(title, body, userId)
      .first<{ id: number }>()
    return c.json({ id: result?.id }, 201)
  }
)

api.onError((err, c) => {
  console.error(err)
  return c.json({ error: 'Internal error' }, 500)
})

export type AppType = typeof api
export default app

Pengujian

import { describe, it, expect } from 'vitest'
import app from '../src/index'

describe('GET /api/posts', () => {
  it('mengembalikan senarai posts', async () => {
    const res = await app.request('/api/posts')
    expect(res.status).toBe(200)
    const body = await res.json()
    expect(body.posts).toBeInstanceOf(Array)
  })
})

Amalan terbaik

1. Rantai definisi laluan

const app = new Hono()
  .get('/posts', handler1)
  .post('/posts', handler2)
  .get('/posts/:id', handler3)

2. Eksport jenis, bukan implementasi

Klien mesti mengimport AppType.

3. Satu penghala bagi setiap domain

Sub-app untuk posts, users, webhooks.

4. Validasi di sempadan, sentiasa

Setiap input luaran mesti melalui zValidator.

5. Bersandar pada bindings, bukan klien global

Pada Cloudflare, akses KV/D1/R2 melalui c.env.

6. Ukur sebelum mengoptimumkan penghala

SmartRouter lalai sesuai untuk 95% kes.

Kesimpulan

Hono telah menjadi standard de facto pada 2026 untuk membina API sedia-edge dalam TypeScript.

Senarai semak permulaan:

• npm create hono@latest dan pilih templat runtime anda
• Tentukan laluan dengan rantaian (.get(...).post(...))
• Tambah logger, cors, secureHeaders sebagai middleware global
• Validasi setiap input dengan @hono/zod-validator
• Eksport AppType dan gunakan API dengan klien hc selamat-jenis
• Tulis ujian dengan app.request() — tiada pelayan HTTP diperlukan
• Deploy dengan wrangler deploy (CF), vercel deploy atau bundler runtime anda