Hono 4.5 → 5.0 마이그레이션 + Cloudflare Edge 정착 사후

핵심 요약

Hono 5.0 GA 마이그레이션. Zod 4.0 통합·RPC client codegen·streaming 표준화가 핵심. 사내 14개 API(Cloudflare Workers + D1) 6주 운영, 응답 평균 p99 142ms → 88ms. 마이그레이션 시간 ~1.5일/API.

1. 주요 변화 — 4가지

• Zod 4.0 통합 — @hono/zod-validator 별도 설치 없이 builtin
• Hono RPC client — TypeScript client codegen 자동, tRPC 유사
• Streaming API 표준화 — c.stream() / c.streamSSE() 명확 분리
• Middleware order 강제 — onError/notFound는 모든 라우트 정의 후에 위치

2. 마이그레이션 코드

// 4.5 — Zod validator
import { zValidator } from '@hono/zod-validator'
app.post('/items', zValidator('json', schema), async c => {...})

// 5.0 — builtin
import { Hono } from 'hono'
import { z } from 'zod'
const app = new Hono()
app.post('/items', z.object({ name: z.string() }), async c => {
  const body = c.req.valid('json')
  return c.json({ ok: true, body })
})

3. RPC client — frontend 통합

// server.ts
import { hc } from 'hono/client'
type AppType = typeof app
// 클라이언트
const client = hc('https://api.example.com')
const res = await client.items.$post({ json: { name: 'Pixmint' } })

tRPC와 거의 동일한 DX. type-safe API 호출. Edge runtime 호환.

4. 실측

5. 함정

• Middleware order — 5.0에서 onError/notFound 위치 강제, 잘못 두면 빌드 에러
• Zod 4 breaking — schema.parse() 동작 미세 변경, 객체 키 순서
• Streaming hot reload — wrangler dev에서 SSE 첫 연결 불안정, 5.0.4 패치 권장
• Custom context — c.set() 타입 추론, 제네릭 명시 필요