Hono実装ガイド — Zodバリデーション・OpenAPI・JWT認証を組み合わせた本番品質API構築【2026年版】

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

const app = new Hono()

const userSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).max(150)
})

app.post('/users', zValidator('json', userSchema), (c) => {
  const user = c.req.valid('json') // 型: { name: string; email: string; age: number }
  return c.json({ id: 1, ...user }, 201)
})

app.post(
  '/users',
  zValidator('json', userSchema, (result, c) => {
    if (!result.success) {
      return c.json(
        {
          error: 'Validation failed',
          details: result.error.flatten()
        },
        422
      )
    }
  }),
  (c) => {
    const user = c.req.valid('json')
    return c.json({ id: 1, ...user }, 201)
  }
)

import { Hono } from 'hono'
import { jwt } from 'hono/jwt'

const app = new Hono()

// /auth/* 以下のルートにJWT認証を適用
app.use('/auth/*', jwt({
  secret: process.env.JWT_SECRET!,
  alg: 'HS256'
}))

app.get('/auth/me', (c) => {
  const payload = c.get('jwtPayload')
  return c.json(payload)
})

import { sign } from 'hono/jwt'

app.post('/login', zValidator('json', z.object({
  email: z.string().email(),
  password: z.string().min(8)
})), async (c) => {
  const { email, password } = c.req.valid('json')

  // DB照合（擬似コード）
  const user = await db.findUserByEmail(email)
  if (!user || !(await verifyPassword(password, user.passwordHash))) {
    return c.json({ error: 'Invalid credentials' }, 401)
  }

  const token = await sign(
    {
      sub: user.id,
      email: user.email,
      exp: Math.floor(Date.now() / 1000) + 60 * 60 // 1時間
    },
    process.env.JWT_SECRET!,
    'HS256'
  )

  return c.json({ token })
})

import { bearerAuth } from 'hono/bearer-auth'
import { basicAuth } from 'hono/basic-auth'

// Bearer Auth（APIキー）
app.use('/api/*', bearerAuth({ token: process.env.API_KEY! }))

// Basic Auth
app.use('/admin/*', basicAuth({
  username: 'admin',
  password: process.env.ADMIN_PASSWORD!
}))

import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi'

const app = new OpenAPIHono()

const UserCreateSchema = z.object({
  name: z.string().min(1).openapi({ example: 'Taro Yamada' }),
  email: z.string().email().openapi({ example: 'taro@example.com' })
})

const UserResponseSchema = z.object({
  id: z.number().openapi({ example: 1 }),
  name: z.string(),
  email: z.string()
})

const createUserRoute = createRoute({
  method: 'post',
  path: '/users',
  tags: ['Users'],
  request: {
    body: {
      content: {
        'application/json': { schema: UserCreateSchema }
      }
    }
  },
  responses: {
    201: {
      content: { 'application/json': { schema: UserResponseSchema } },
      description: 'User created successfully'
    },
    422: {
      description: 'Validation error'
    }
  }
})

app.openapi(createUserRoute, (c) => {
  const { name, email } = c.req.valid('json')
  return c.json({ id: 1, name, email }, 201)
})

// OpenAPI仕様JSONエンドポイント
app.doc('/openapi.json', {
  openapi: '3.0.0',
  info: { title: 'My Production API', version: '1.0.0' }
})

import { swaggerUI } from '@hono/swagger-ui'

// Swagger UIを /ui で提供
app.get('/ui', swaggerUI({ url: '/openapi.json' }))

// 開発環境のみUIを有効化する例
if (process.env.NODE_ENV !== 'production') {
  app.get('/ui', swaggerUI({ url: '/openapi.json' }))
}

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { rateLimiter } from 'hono-rate-limiter'

const app = new Hono()

// ロギング
app.use('*', logger())

// CORS設定
app.use('/api/*', cors({
  origin: ['https://example.com', 'https://app.example.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowHeaders: ['Authorization', 'Content-Type'],
  maxAge: 86400
}))

// レート制限（1分間に60リクエスト）
app.use('/api/*', rateLimiter({
  windowMs: 60 * 1000,
  limit: 60,
  keyGenerator: (c) => c.req.header('x-forwarded-for') ?? 'unknown'
}))

import { HTTPException } from 'hono/http-exception'

// カスタムエラーをスロー
app.get('/resource/:id', async (c) => {
  const resource = await db.find(c.req.param('id'))
  if (!resource) {
    throw new HTTPException(404, { message: 'Resource not found' })
  }
  return c.json(resource)
})

// グローバルエラーハンドラー
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json(
      { error: err.message, status: err.status },
      err.status
    )
  }
  console.error('Unexpected error:', err)
  return c.json({ error: 'Internal Server Error' }, 500)
})