Loading...
この記事は、ひとりでつくるSaaS - 設計・実装・運用の記録 Advent Calendar 2025 の12日目の記事です。
昨日の記事では「MPAからSPAに移行した理由」について書きました。この記事では、Next.js Route HandlerからHonoに移行した理由と、その効果について解説します。
Route Handlerは手軽にAPIを作成できますが、プロジェクトが成長するにつれて課題が見えてきました。
1. ディレクトリ構造の制約
Route Handlerでは、app/api/配下のディレクトリ構造がそのままURLパスになります。
app/api/
├── users/
│ ├── route.ts → GET /api/users
│ └── [id]/
│ └── route.ts → GET /api/users/123
├── contents/
│ ├── route.ts → GET /api/contents
│ └── [id]/
│ ├── route.ts → GET /api/contents/456
│ └── comments/
│ └── route.ts → GET /api/contents/456/comments
エンドポイントが増えるにつれ、app/api/配下が肥大化していきます。ユーティリティ関数やバリデーションを共有したいとき、ファイルの配置場所に迷うことも多くなりました。
2. コードの重複
各route.tsファイルで似たようなバリデーションやエラーハンドリングを書くことになりがちです。
// app/api/users/route.ts
export async function POST(request: NextRequest) {
try {
const body = await request.json();
// バリデーション
if (!body.name || typeof body.name !== 'string') {
return NextResponse.json({ error: 'Invalid name' }, { status: 400 });
}
// 処理...
} catch (error) {
return NextResponse.json({ error: 'Internal error' }, { status: 500 });
}
}
// app/api/contents/route.ts
export async function POST(request: NextRequest) {
try {
const body = await request.json();
// 同じようなバリデーション...
if (!body.title || typeof body.title !== 'string') {
return NextResponse.json({ error: 'Invalid title' }, { status: 400 });
}
// 処理...
} catch (error) {
return NextResponse.json({ error: 'Internal error' }, { status: 500 });
}
}3. APIドキュメントの手動管理
OpenAPIドキュメントを作成しようとすると、実装とは別に手動で定義ファイルを書く必要があります。実装を変更したらドキュメントも更新する必要があり、乖離が発生しやすい状況でした。
Honoは軽量で高速なWebフレームワークです。
以下の点が決め手になりました。
HonoをNext.jsに統合すると、app/api/には接続用の最小限のコードだけを置き、API本体はserver/api/で自由に整理できます。
app/api/
└── [[...route]]/
└── route.ts # Honoへの接続のみ（数行）
server/api/
├── index.ts # Honoアプリ本体
├── routes/
│ ├── users.ts # ユーザー関連API
│ ├── contents.ts # コンテンツ関連API
│ └── admin.ts # 管理者API
└── middleware/
├── auth.ts # 認証ミドルウェア
└── error.ts # エラーハンドリング
機能ごとにファイルを整理でき、共通処理も適切な場所に配置できます。
@hono/zod-openapiを使うと、Zodスキーマからリクエスト・レスポンスの型を定義し、同時にOpenAPIドキュメントを自動生成できます。
import { createRoute, z } from '@hono/zod-openapi';
// リクエスト・レスポンスのスキーマ定義
const CreateUserSchema = z.object({
name: z.string().min(1).openapi({ example: '田中太郎' }),
email: z.string().email().openapi({ example: 'tanaka@example.com' }),
});
const UserResponseSchema = z.object({
id: z.string().openapi({ example: 'user_123' }),
name: z.string(),
email: z.string(),
createdAt: z.string().datetime(),
});
// ルート定義（型とドキュメントが同時に生成される）
const createUserRoute = createRoute({
method: 'post',
path: '/users',
request: {
body: {
content: { 'application/json': { schema: CreateUserSchema } },
},
},
responses: {
201: {
description: 'ユーザー作成成功',
content: { 'application/json': { schema: UserResponseSchema } },
},
400: {
description: 'バリデーションエラー',
},
},
});実装とドキュメントが常に同期されるため、乖離の心配がありません。
認証やエラーハンドリングをミドルウェアとして定義し、再利用できます。
// server/api/middleware/auth.ts
import { createMiddleware } from 'hono/factory';
export const authMiddleware = createMiddleware(async (c, next) => {
const session = await getSession(c.req.header('Authorization'));
if (!session) {
return c.json({ error: 'Unauthorized' }, 401);
}
c.set('user', session.user);
await next();
});// server/api/index.ts
import { OpenAPIHono } from '@hono/zod-openapi';
import { authMiddleware } from './middleware/auth';
const app = new OpenAPIHono();
// 認証が必要なルートにミドルウェアを適用
app.use('/users/*', authMiddleware);
app.use('/contents/*', authMiddleware);
// 公開APIはミドルウェアなし
app.route('/public', publicRoutes);HonoをNext.jsに統合するには、hono/vercelアダプタを使います。
// app/api/[[...route]]/route.ts
import { handle } from 'hono/vercel';
import { app } from '@/server/api';
export const GET = handle(app);
export const POST = handle(app);
export const PUT = handle(app);
export const DELETE = handle(app);[[...route]]はキャッチオールセグメントで、/api/*配下のすべてのリクエストをHonoにルーティングします。この数行だけでNext.jsとの接続が完了します。
Better Authのような認証ライブラリを使う場合は、認証エンドポイントを別に分けることもできます。
app/api/
├── [[...route]]/ # Honoへのプロキシ（メインAPI）
├── auth/ # Better Auth（認証専用）
│ └── [...all]/
└── webhooks/ # Webhook（Stripe等）
└── stripe/
処理の性質に応じてエンドポイントを分離することで、各部分が独立して管理できます。
Honoでは、エラーハンドリングを一箇所で定義できます。
// server/api/index.ts
import { OpenAPIHono } from '@hono/zod-openapi';
const app = new OpenAPIHono();
// Zodバリデーションエラーのハンドリング
app.onError((err, c) => {
if (err instanceof z.ZodError) {
return c.json({
error: 'Validation Error',
details: err.errors,
}, 400);
}
// その他のエラー
console.error(err);
return c.json({ error: 'Internal Server Error' }, 500);
});
// 404ハンドリング
app.notFound((c) => {
return c.json({ error: 'Not Found' }, 404);
});Route Handlerでは各ファイルに書いていたエラー処理が、1箇所にまとまります。
Route HandlerからHonoへの移行で得られた効果をまとめます。
| 項目 | Before（Route Handler） | After（Hono） |
|---|---|---|
| ディレクトリ構造 | URL構造に制約される | 自由に整理可能 |
| バリデーション | 手動で記述 | Zodで宣言的に定義 |
| 型安全性 | 手動で型定義 | Zodから自動推論 |
| APIドキュメント | 手動管理 | 自動生成 |
| エラー処理 | 各ファイルで重複 | ミドルウェアで一元化 |
定義したルートからOpenAPIドキュメントを自動生成できます。
// server/api/index.ts
app.doc('/doc', {
openapi: '3.0.0',
info: {
title: 'My API',
version: '1.0.0',
},
});/api/docにアクセスするとOpenAPI仕様のJSONが取得できます。このJSONをSwagger UIやApidogなどのツールにインポートすれば、エンドポイントの一覧確認やリクエストのテストができます。
Honoのアプリケーションはフレームワーク非依存なので、テストが書きやすくなります。
import { app } from '@/server/api';
describe('Users API', () => {
it('should create a user', async () => {
const res = await app.request('/users', {
method: 'POST',
body: JSON.stringify({ name: 'Test', email: 'test@example.com' }),
headers: { 'Content-Type': 'application/json' },
});
expect(res.status).toBe(201);
});
});すべてを一度に移行する必要はありません。新しいエンドポイントからHonoで実装し、既存のRoute Handlerは徐々に移行していく方法もあります。
Better AuthやStripe Webhookのように、ライブラリが専用のハンドラを提供している場合は、無理にHonoに統合せず、別エンドポイントとして維持するのも選択肢です。
Route HandlerからHonoへの移行で改善したことをまとめます。
解決した課題:
server/api/で自由に整理得られた効果:
HonoはNext.jsと相性が良く、Route Handlerの課題を解消しながら、より構造化されたAPI開発が可能になります。
明日は「Vercel最適化」について解説します。
シリーズの他の記事
Comments