aibot88 Hono API 構築スキル
HonoとZodによる型安全なAPI開発の全ワークフローを提供します。
いつ使うか
このスキルは以下の場合に使用してください：
- 新しいCRUD APIエンドポイントの作成
- リクエストバリデーションの追加
- 型安全なクライアント-サーバー通信の構築
- APIのテストと最適化
- Honoドキュメントの検索
ワークフロー
1. API エンドポイントの作成
// apps/server/src/routes/admin/users.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { CreateUserSchema } from '@repo/schemas/request/admin/users'
import { db } from '@repo/database'
const app = new Hono()
// POST /users - 作成
app.post('/', zValidator('json', CreateUserSchema), async (c) => {
const data = c.req.valid('json') // 型安全
const user = await db.user.create({ data })
return c.json({ user }, 201)
})
// GET /users/:id - 取得
app.get('/:id', async (c) => {
const id = c.req.param('id')
const user = await db.user.findUnique({ where: { id } })
if (!user) return c.json({ error: 'Not found' }, 404)
return c.json({ user })
})
// RPCのために型をエクスポート
export type AppType = typeof app
詳細パターン（エラーハンドリング、ページネーション、複雑なクエリ）は crud-operations.md を参照してください。
2. バリデーションの追加
// packages/schemas/src/request/admin/users.ts
import { z } from 'zod'
import type { Prisma } from '@repo/database'
export const CreateUserSchema = z.object({
name: z.string().min(1).max(100),
email: z.string().email(),
age: z.number().int().positive().optional(),
}) satisfies z.ZodType<Prisma.UserCreateInput> // Prisma型と同期
export type CreateUserInput = z.infer<typeof CreateUserSchema>
詳細パターン（カスタムバリデーション、複雑な変換、エラーメッセージ）は validation.md を参照してください。
3. RPC クライアントのセットアップ
// apps/admin/src/utils/hc.ts
import { hc } from 'hono/client'
import type { AppType } from '@repo/server'
export const client = hc<AppType>('/api')
// apps/admin/src/swr/users/use-user.ts
export function useUser(id: string) {
return useSWR(['user', id], async () => {
return await parseResponse(client.admin.users[':id'].$get({ param: { id } })) // 完全に型付けされている
})
}
詳細パターン（型推論、エラーハンドリング、複数API統合）は rpc-client.md を参照してください。
4. Hono CLI でテスト・最適化
# ドキュメントを検索
hono search "middleware"
# ドキュメントを表示
hono docs /docs/guides/middleware
# サーバー起動なしでテスト
hono request -P /api/users apps/server/src/index.ts
hono request -P /api/users -X POST -d '{"name":"Alice"}' apps/server/src/index.ts
# 本番デプロイ前に最適化（ファイルサイズ38%削減、初期化16.5倍高速化）
hono optimize apps/server/src/index.ts -o dist/server.js
詳細ワークフロー（CLIコマンド、最適化、自動化パターン）は hono-cli.md を参照してください。
重要ルール
API 作成
c.notFound()は使用しない（RPC型を壊す）- 常にステータスコードを明示的に指定
- クライアント用に
AppTypeをエクスポート - response スキーマは visibility + deriveDto で構築（
.pick()は使わない）
バリデーション
- スキーマ名は PascalCase（
CreateUserSchema） - スキーマは
packages/schemas/に定義 - バリデート済みデータ取得には
c.req.valid()を使用 - クエリパラメータには
z.coerceを使用（文字列→数値の変換）
RPC クライアント
- サーバーから
AppTypeをエクスポート - クライアントで型をインポート（値ではない:
import type） - 型安全性のために
hc<AppType>()を使用 - レスポンス型には
InferResponseTypeを使用
Hono CLI
- 開発サーバー不要:
hono requestは内部でapp.request()を使用 - 環境の競合とサーバーの乱立を防ぐ
- テストには常に
hono requestを優先 hono optimizeは本番デプロイ前に実行（開発中は不要）
詳細パターン
詳細な実装パターンについては references を参照してください：
- crud-operations.md - CRUD操作、エラーハンドリング、ページネーション
- validation.md - カスタムバリデーション、複雑な変換、エラーメッセージ
- rpc-client.md - 型推論、エラーハンドリング、複数API
- hono-cli.md - CLIワークフロー、最適化、自動化