MENU

問い合わせ

    お問い合わせ


    【Honoで作る社内ヘルプデスク 第9回】hono/clientで型安全にAPIを呼ぶ:ルートの型を共有して呼び間違いを防ぐ

    社内ヘルプデスクの API(プログラムから呼ぶ窓口)は、ここまでで登録・一覧・状態の変更・コメントまでそろいました。次に増えてくるのは、「別の画面や社内スクリプトからこの API を呼びたい」という使い方です。

    「API の仕様が変わるたびに、呼び出す側のコードが動かなくなっていないか心配。項目名の打ち間違いや、仕様の変更に気づかないまま本番に出てしまうことは防げないの?」

    結論から言うと、Hono の RPC 機能(hono/client)を使うと、サーバーのルートの型をそのまま呼び出し側に渡せるので、URL や項目名・値の間違いを、動かす前の型チェック(npm run typecheck)で見つけられます。そのために必要なのは、ルートを「つなげて(メソッドチェーンで)」書くことと、応答の状態コードを明示することの2つです。

    前回は、Hono の JSX で担当者向けの管理画面を作りました。まだの方は先にご覧ください。

    詳しくは前回の記事で解説しています。

    新しいライブラリのインストールは不要です。hono/client は hono に含まれています。

    目次

    hono/client で何が変わるのか

    RPC(Remote Procedure Call。別の場所にある処理を、手元の関数のように呼ぶ仕組み)と聞くと大げさに感じますが、Hono の RPC は「サーバーのルートの型を、呼び出す側の TypeScript に伝える」仕組みです。通信そのものは普通の HTTP と JSON のままです。

    比べる点これまで(fetch で手書き)hono/client
    URL'/api/tickets/' + id のように文字列で組み立てるclient.api.tickets[':id{[0-9]+}'].$get({ param: { id } }) のように、ルートをたどって呼ぶ
    送る JSON項目名や値を間違えても、動かすまで気づかないサーバーの入力チェック(Zod のスキーマ)と違えば型チェックで止まる
    受け取る JSONres.json<…>() の型を呼び出し側で手書きするサーバーが返す形が型として届く。状態コードごとに形が分かれる
    仕様の変更呼び出し側を目で探して直す型チェックで、直す必要のある場所が一覧になる

    大事なのは、サーバーと呼び出し側で共有するのは「型」だけという点です。import type で読み込むので、サーバーの処理(DB に触るコードなど)が呼び出し側に入ることはありません。

    📰 出典:Hono「RPC」

    この回で作るものの全体像

    1. src/schemas.ts に、分類と優先度の型を足す
    2. チケットのルート(src/routes/tickets.ts)を、つなげて書く形に直し、応答の形と状態コードを明示する
    3. ログインのルート(src/routes/auth.ts)も同じ形に直す
    4. src/index.ts で、hono/client に渡す型(AppType)を書き出す
    5. 型つきのクライアント(src/client.ts)を作る
    6. テストで、型どおりに呼べること・間違った呼び方が型チェックで止まることを確かめる

    この回で hono/client から呼べるようにするのは、ログイン(/api/auth)とチケット(/api/tickets)です。コメントや添付ファイルのルートも同じ手順で足せます。

    1. 分類と優先度の型を足す

    応答の型に「分類は4種類のどれか」「優先度は3種類のどれか」を書けるように、すでにある配列から型を作ります。値の一覧を1か所にまとめておけば、分類を増やしたときに型も一緒に変わります。

    src/schemas.ts に次の変更を加えます(+ が追加、- が削除)。

    --- a/src/schemas.ts
    +++ b/src/schemas.ts
    @@ -3,6 +3,8 @@ import { statuses } from './status'
    
     export const categories = ['pc', 'account', 'system', 'other'] as const
     export const priorities = ['low', 'normal', 'high'] as const
    +export type Category = (typeof categories)[number]
    +export type Priority = (typeof priorities)[number]
    
     // 受付フォームから届く入力。ここを通ったものだけを DB に入れる(申請者はログイン情報から決めるので入力しない)
     export const createTicketSchema = z.object({

    2. チケットのルートを「つなげて」書く

    hono/client が型を受け取るには、ルートを1つの式でつなげて書く必要があります。これまでのように tickets.post(...) と tickets.get(...) を別々の文で書くと、処理としては同じでも、tickets という変数の型にはルートの情報が積み上がりません。.post(...).get(...) とつなげると、その戻り値の型に、各ルートのパス・入力・応答が順に足されていきます。

    📰 出典:Hono「RPC – Using RPC with larger applications」

    あわせて、次の2点を直します。

    • 状態コードを c.json(値, 200) のように明示する:Hono は、明示した状態コードを応答の型に含めます。呼び出し側は res.status === 201 のように分けるだけで、その状態コードのときの JSON の形に絞り込めます
    • エラーの文字列に as const を付ける:{ error: 'not_found' as const } とすると、型が「ただの文字列」ではなく 'not_found' という決まった値になり、呼び出し側で body.error === 'invalid_transition' のように分けて扱えます

    もう1つ、DB から取り出す行の型を TicketSummary・Ticket として書きました。これまでは .first<{ id: number }>() のように必要な項目だけを書いていたので、そのままだと「id しか返さない」という型が呼び出し側に伝わってしまいます。詳細の取得も SELECT * をやめ、返す項目を並べました。DB に列を足しても、意図せず API の応答に出ることがなくなります。

    処理の中身(権限・入力チェック・状態遷移のルール)は第1〜3回のままで、書き方だけを変えています。ファイル全体を置き換えます。

    <details> <summary>src/routes/tickets.ts の全文</summary>

    import { zValidator } from '@hono/zod-validator'
    import { Hono } from 'hono'
    import { requireLogin, requireRole, type AppEnv } from '../auth'
    import { changeStatusSchema, createTicketSchema, listQuerySchema, type Category, type Priority } from '../schemas'
    import { enqueueNotification } from '../notify'
    import type { Status } from '../status'
    import { changeStatus } from '../ticket-service'
    
    // API が返すチケットの形。hono/client を使う画面やスクリプトにも、この型がそのまま伝わる
    export type TicketSummary = {
      id: number
      title: string
      category: Category
      priority: Priority
      status: Status
      requester: string
      assignee: string | null
      created_at: string
    }
    export type Ticket = TicketSummary & { body: string; updated_at: string }
    
    // 社員は自分の申請だけ、担当者・管理者は全件を扱える
    const canSeeAll = (role: string) => role !== 'employee'
    
    // 第9回: hono/client に型を伝えるため、ルートを「つなげて(メソッドチェーンで)」書く。
    // tickets.post(...); tickets.get(...); と文を分けると、tickets の型に各ルートが積み上がらない
    export const tickets = new Hono<AppEnv>()
      // このルートはすべてログイン必須。ログインしていなければ 401
      .use('*', requireLogin)
    
      // チケット登録。入力が不正なら 400 を返し、DB には触らない
      .post(
        '/',
        zValidator('json', createTicketSchema, (result, c) => {
          if (!result.success) {
            return c.json(
              {
                error: 'invalid_request' as const,
                issues: result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })),
              },
              400,
            )
          }
        }),
        async (c) => {
          const input = c.req.valid('json')
          const user = c.get('user')
          // 申請者は入力ではなくログイン中の本人から決める(他人名義の申請を作れないようにする)
          // 値は必ず bind() で渡す(文字列連結で SQL を組み立てない)
          const ticket = await c.env.DB.prepare(
            `INSERT INTO tickets (title, body, category, priority, requester)
             VALUES (?, ?, ?, ?, ?)
             RETURNING id, title, category, priority, status, requester, assignee, created_at`,
          )
            .bind(input.title, input.body, input.category, input.priority, user.email)
            .first<TicketSummary>()
          // 担当者への通知はキューに任せ、画面の応答は待たせない
          await enqueueNotification(c.env, { kind: 'ticket_created', ticketId: ticket!.id })
          return c.json(ticket!, 201)
        },
      )
    
      .get('/:id{[0-9]+}', async (c) => {
        const user = c.get('user')
        const ticket = await c.env.DB.prepare(
          `SELECT id, title, body, category, priority, status, requester, assignee, created_at, updated_at
           FROM tickets WHERE id = ?`,
        )
          .bind(Number(c.req.param('id')))
          .first<Ticket>()
        // 他人のチケットは「存在しない」と同じ 404 にする(403 だと番号の存在が分かってしまう)
        if (!ticket || (!canSeeAll(user.role) && ticket.requester !== user.email)) {
          return c.json({ error: 'not_found' as const }, 404)
        }
        return c.json(ticket, 200)
      })
    
      // 一覧。新しい順。status で絞り込み、page / perPage で区切る(総件数も返す)
      .get(
        '/',
        zValidator('query', listQuerySchema, (result, c) => {
          if (!result.success) return c.json({ error: 'invalid_request' as const }, 400)
        }),
        async (c) => {
          const { status, page, perPage } = c.req.valid('query')
          const user = c.get('user')
          // 絞り込み条件は「状態」と「社員なら自分の申請だけ」。条件は組み立てても値は必ず bind する
          const conditions: string[] = []
          const filter: (string | number)[] = []
          if (status) {
            conditions.push('status = ?')
            filter.push(status)
          }
          if (!canSeeAll(user.role)) {
            conditions.push('requester = ?')
            filter.push(user.email)
          }
          const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''
    
          // 件数と一覧を1回の往復でまとめて取る
          const [count, list] = await c.env.DB.batch([
            c.env.DB.prepare(`SELECT COUNT(*) AS total FROM tickets ${where}`).bind(...filter),
            c.env.DB.prepare(
              `SELECT id, title, category, priority, status, requester, assignee, created_at
               FROM tickets ${where}
               ORDER BY created_at DESC, id DESC
               LIMIT ? OFFSET ?`,
            ).bind(...filter, perPage, (page - 1) * perPage),
          ])
          const total = (count.results[0] as { total: number }).total
          return c.json({ items: list.results as TicketSummary[], page, perPage, total }, 200)
        },
      )
    
      // 状態の変更は担当者・管理者だけ。ルールにない遷移は 409、すでに他の人が変えていた場合も 409
      .patch(
        '/:id{[0-9]+}/status',
        requireRole('agent', 'admin'),
        zValidator('json', changeStatusSchema, (result, c) => {
          if (!result.success) return c.json({ error: 'invalid_request' as const }, 400)
        }),
        async (c) => {
          const result = await changeStatus(c.env.DB, {
            id: Number(c.req.param('id')),
            next: c.req.valid('json').status,
            actor: c.get('user').email,
          })
          if (result.ok) return c.json(result.ticket, 200)
          if (result.error === 'not_found') return c.json({ error: 'not_found' as const }, 404)
          if (result.error === 'invalid_transition') {
            return c.json({ error: 'invalid_transition' as const, from: result.from, to: result.to }, 409)
          }
          return c.json({ error: 'conflict' as const }, 409)
        },
      )

    </details>

    3. ログインのルートも同じ形にする

    ログインのルートも、つなげて書く形に直します。export const auth = new Hono<AppEnv>() の行を、ルートの定義の前に移しているのは、変数を作る式の中で全部のルートをつなげるためです。

    src/routes/auth.ts に次の変更を加えます(+ が追加、- が削除)。

    --- a/src/routes/auth.ts
    +++ b/src/routes/auth.ts
    @@ -4,8 +4,6 @@ import { z } from 'zod'
     import { endSession, requireLogin, startSession, type AppEnv, type Role } from '../auth'
     import { verifyPassword } from '../password'
    
    -export const auth = new Hono<AppEnv>()
    -
     // 管理画面のログインフォームでも同じ入力チェックを使う
     export const loginSchema = z.object({
       email: z.string().trim().toLowerCase().email().max(254),
    @@ -27,25 +25,25 @@ export const checkCredentials = async (env: Env, email: string, password: string
       return { id: row.id, email: row.email, name: row.name, role: row.role }
     }
    
    -auth.post(
    -  '/login',
    -  zValidator('json', loginSchema, (result, c) => {
    -    if (!result.success) return c.json({ error: 'invalid_request' }, 400)
    -  }),
    -  async (c) => {
    -    const { email, password } = c.req.valid('json')
    -    const user = await checkCredentials(c.env, email, password)
    -    // 「メールが違う」「パスワードが違う」を区別せず、同じ文言で返す
    -    if (!user) return c.json({ error: 'invalid_credentials' }, 401)
    -
    -    await startSession(c, c.env.SESSION_SECRET, user.id)
    -    return c.json(user)
    -  },
    -)
    -
    -auth.post('/logout', (c) => {
    -  endSession(c)
    -  return c.json({ ok: true })
    -})
    -
    -auth.get('/me', requireLogin, (c) => c.json(c.get('user')))
    +// 第9回: hono/client に型を伝えるため、ルートをつなげて(メソッドチェーンで)書く
    +export const auth = new Hono<AppEnv>()
    +  .post(
    +    '/login',
    +    zValidator('json', loginSchema, (result, c) => {
    +      if (!result.success) return c.json({ error: 'invalid_request' as const }, 400)
    +    }),
    +    async (c) => {
    +      const { email, password } = c.req.valid('json')
    +      const user = await checkCredentials(c.env, email, password)
    +      // 「メールが違う」「パスワードが違う」を区別せず、同じ文言で返す
    +      if (!user) return c.json({ error: 'invalid_credentials' as const }, 401)
    +
    +      await startSession(c, c.env.SESSION_SECRET, user.id)
    +      return c.json(user, 200)
    +    },
    +  )
    +  .post('/logout', (c) => {
    +    endSession(c)
    +    return c.json({ ok: true }, 200)
    +  })
    +  .get('/me', requireLogin, (c) => c.json(c.get('user'), 200))

    4. hono/client に渡す型を書き出す

    src/index.ts で、ログインとチケットのルートをつなげて登録し、その結果の型を AppType として書き出します。app.route() は、登録したルートの型を足した app を返すので、つなげた式の型が「API の一覧」になります。

    src/index.ts に次の変更を加えます(+ が追加、- が削除)。

    --- a/src/index.ts
    +++ b/src/index.ts
    @@ -21,9 +21,11 @@ app.get('/api/health', async (c) => {
       return c.json({ status: 'ok', schemaVersion: row?.value ?? null })
     })
    
    -app.route('/api/auth', auth)
    +// 第9回: hono/client から呼ぶルートは、つなげて登録し、その結果の型を AppType として書き出す
    +const rpcRoutes = app.route('/api/auth', auth).route('/api/tickets', tickets)
    +export type AppType = typeof rpcRoutes
    +
     app.route('/api/users', users)
    -app.route('/api/tickets', tickets)
     app.route('/api', attachments)
     app.route('/api', comments)
     app.route('/admin', admin)

    export type で書き出すのは型だけです。Worker として動く処理(export default の fetch・queue・scheduled)は変わりません。

    5. 型つきのクライアントを作る

    呼び出し側で使うクライアントを作ります。hc<AppType>(…) だけでも動きますが、Hono の公式ドキュメントでは、型の計算を先に済ませた関数を用意しておく書き方が勧められています。ルートが増えても、エディタの補完(入力の候補を出す機能)が重くなりにくくなります。

    // src/client.ts
    // 第9回: API を型つきで呼ぶためのクライアント。サーバーのルートの型(AppType)だけを読み込む。
    // import type なのでサーバーのコードは取り込まれず、ブラウザや別のスクリプトからも使える
    import { hc } from 'hono/client'
    import type { AppType } from './index'
    
    // 型の計算を先に済ませておく(ルートが増えても、エディタの補完が重くなりにくい。Hono の公式の勧め)
    export type Client = ReturnType<typeof hc<AppType>>
    export const createClient = (...args: Parameters<typeof hc>): Client => hc<AppType>(...args)

    📰 出典:Hono「RPC – Compile your code before using it (recommended)」

    ブラウザの画面や社内のスクリプトからは、次のように使います(ここでは考え方の例で、ファイルには入れていません)。

    // 例:別の画面やスクリプトから使う
    const client = createClient('https://helpdesk.example.com')
    const res = await client.api.tickets.$get({ query: { status: 'open', page: '1' } })
    if (res.status === 200) {
      const { items, total } = await res.json() // items の型はサーバーの TicketSummary と同じ
    }

    クエリ文字列(URL の ? の後ろ)の値は、数字も文字列で渡します。URL の上ではすべて文字列で、数値に直すのはサーバー側の Zod(z.coerce.number()。第2回)の役目だからです。

    6. テストで確かめる

    テストでは、hono/client の fetch にテスト中の Worker(SELF.fetch)を渡し、本物の HTTP の代わりにします。確かめるのは次の点です。

    • 登録 → 詳細 → 状態の変更を、型どおりの引数で呼べる
    • 400・409 のエラーも、状態コードで分けると形が絞り込まれる
    • $url() で、組み立てられる URL を確かめられる
    • 間違った呼び方(ない分類・件名なし・ない状態・ないルート)が、型チェックで誤りになる

    最後の点には、TypeScript の // @ts-expect-error(次の行が型の誤りになるはず、という印)を使います。誤りにならなくなると、逆に npm run typecheck が失敗します。つまり「間違った呼び方が通ってしまう」ことをテストで見張れます。型の形そのものは、Vitest の expectTypeOf で確かめます。

    📰 出典:Vitest「Testing Types」

    <details> <summary>test/client.test.ts の全文</summary>

    // test/client.test.ts
    // 第9回: hono/client で API を呼ぶ。URL や JSON を手で組み立てず、サーバーの型どおりに呼べることを確かめる
    import { SELF } from 'cloudflare:test'
    import type { InferRequestType, InferResponseType } from 'hono/client'
    import { beforeAll, describe, expect, expectTypeOf, it } from 'vitest'
    import { createClient } from '../src/client'
    import { loginAs } from './helpers'
    
    // テストでは本物のネットワークではなく、テスト中の Worker(SELF)へ送る
    const clientFor = (cookie: string) =>
      createClient('http://example.com', {
        fetch: (input: RequestInfo | URL, init?: RequestInit) => SELF.fetch(input, init),
        headers: { cookie },
      })
    
    let employee: ReturnType<typeof clientFor>
    let agent: ReturnType<typeof clientFor>
    beforeAll(async () => {
      employee = clientFor(await loginAs('rpc-staff@example.com', 'employee'))
      agent = clientFor(await loginAs('rpc-agent@example.com', 'agent'))
    })
    
    describe('hono/client で型つきに呼ぶ', () => {
      it('登録 → 詳細 → 状態の変更を、型どおりの引数で呼べる', async () => {
        const created = await employee.api.tickets.$post({
          json: { title: 'VPN につながらない', body: '在宅で朝からつながりません', category: 'account' },
        })
        expect(created.status).toBe(201)
        // status で分けると、res.json() の型も「201 のときの形」に絞られる
        if (created.status !== 201) throw new Error('登録に失敗')
        const ticket = await created.json()
        expectTypeOf(ticket.status).toEqualTypeOf<'open' | 'in_progress' | 'resolved' | 'closed'>()
        expect(ticket.status).toBe('open')
    
        // パスの :id は param で渡す(文字列で URL をつなげない)
        const detail = await employee.api.tickets[':id{[0-9]+}'].$get({ param: { id: String(ticket.id) } })
        expect(detail.status).toBe(200)
    
        const changed = await agent.api.tickets[':id{[0-9]+}'].status.$patch({
          param: { id: String(ticket.id) },
          json: { status: 'in_progress' },
        })
        expect(changed.status).toBe(200)
        if (changed.status === 200) expect((await changed.json()).status).toBe('in_progress')
      })
    
      it('エラーの応答も型で分かれる(400 なら issues がある)', async () => {
        const res = await employee.api.tickets.$post({ json: { title: ' ', body: '本文', category: 'pc' } })
        expect(res.status).toBe(400)
        if (res.status === 400) {
          const body = await res.json()
          expect(body.error).toBe('invalid_request')
          // issues があるのは「登録の 400」の形だけ。型でも中身でも確かめる
          expect('issues' in body && body.issues.some((i) => i.path === 'title')).toBe(true)
        }
      })
    
      it('ルールにない遷移は 409 で、from / to が型つきで返る', async () => {
        const created = await employee.api.tickets.$post({ json: { title: 'マウス', body: '反応しない', category: 'pc' } })
        const { id } = (await created.json()) as { id: number }
        const res = await agent.api.tickets[':id{[0-9]+}'].status.$patch({
          param: { id: String(id) },
          json: { status: 'closed' },
        })
        expect(res.status).toBe(409)
        if (res.status === 409) {
          const body = await res.json()
          if (body.error === 'invalid_transition') {
            expect(body.from).toBe('open')
            expect(body.to).toBe('closed')
          } else {
            throw new Error('invalid_transition のはず')
          }
        }
      })
    
      it('一覧のクエリも型どおりに渡せる(数字も文字列で渡す)', async () => {
        const res = await agent.api.tickets.$get({ query: { status: 'open', page: '1', perPage: '5' } })
        expect(res.status).toBe(200)
        if (res.status === 200) {
          const list = await res.json()
          expect(list.perPage).toBe(5)
          expect(list.items.every((t) => t.status === 'open')).toBe(true)
        }
      })
    
      it('$url() で、組み立てられる URL を確かめられる', () => {
        const url = employee.api.tickets[':id{[0-9]+}'].$url({ param: { id: '42' } })
        expect(url.pathname).toBe('/api/tickets/42')
      })
    
      it('間違った呼び方は、実行する前に型チェック(npm run typecheck)で止まる', () => {
        // 実行はしない。下の行が「型の誤り」になることを tsc に確かめさせる(誤りでなくなると typecheck が失敗する)
        const wrongCalls = () => {
          // @ts-expect-error 分類(category)に無い値
          employee.api.tickets.$post({ json: { title: 'a', body: 'b', category: 'printer' } })
          // @ts-expect-error 件名(title)が無い
          employee.api.tickets.$post({ json: { body: 'b', category: 'pc' } })
          // @ts-expect-error 存在しない状態
          agent.api.tickets[':id{[0-9]+}'].status.$patch({ param: { id: '1' }, json: { status: 'done' } })
          // @ts-expect-error 存在しないルート
          employee.api.ticket.$get()
        }
        expect(typeof wrongCalls).toBe('function')
      })
    
      it('画面側で使う型を、サーバーのルートから取り出せる', () => {
        type CreateInput = InferRequestType<typeof employee.api.tickets.$post>['json']
        type Created = InferResponseType<typeof employee.api.tickets.$post, 201>
        expectTypeOf<CreateInput['category']>().toEqualTypeOf<'pc' | 'account' | 'system' | 'other'>()
        expectTypeOf<Created['id']>().toEqualTypeOf<number>()
      })
    })

    </details>

    検証コマンドを実行します。

    npx wrangler types
    npm run typecheck
    npm test

    開発環境(Node.js 26 LTS・npm 11.20)では、型チェックが通り、テストは10ファイル82件すべて成功しました。試しに、テストの category: 'printer' を 'pc' に直すと、Unused '@ts-expect-error' directive(誤りになるはずの行が誤りにならない)で型チェックが失敗することも確かめました。

    つまずきやすい落とし穴と注意

    • 文を分けて書いたルートは型に入らない:tickets.get(...) のように別の文で足したルートは、動きはしても hono/client からは見えません。「呼べない」「補完に出ない」ときは、まずここを確かめます
    • 状態コードを書かない応答は分けにくい:c.json(値) のままだと、状態コードによる絞り込みが効かず、エラーの形と正常の形が混ざった型になります
    • ミドルウェアが返す応答は型に入らない:ログイン確認(requireLogin)が返す 401 は、この版の Hono では呼び出し側の型に含まれませんでした(一覧の状態コードの型は 200 | 400)。ログイン切れは、状態コードの型に頼らず res.status === 401 を必ず確かめるようにします
    • 型は「約束」で、通信の中身の検査ではない:hono/client の型はコンパイルのときだけのものです。古い呼び出し側や外部からの送信に備え、サーバー側の Zod による入力チェックは外しません
    • 呼び出し側とサーバーの版を合わせる:別のリポジトリで画面を作る場合は、hono のメジャーバージョンと TypeScript の設定(strict: true)をそろえます。そろっていないと、型がうまく伝わらないことがあります
    • 本番運用で足したいもの:画面を別のドメインに置く場合は、CORS(別のドメインからの呼び出しを許す設定)と、Cookie の送り方(credentials)の設計が要ります。この連載では同じ Worker から画面を返しているため、扱っていません

    発注者向けメモ:API を「型でつなぐ」ことを開発会社に確認する

    画面とサーバーを別々に作る開発では、「サーバー側の項目名を変えたら、画面の一部が動かなくなっていた」という不具合が起きがちです。型を共有する仕組みは、こうした食い違いを、本番に出す前の確認(型チェック・テスト)で見つけるための備えです。発注の場面では、次の点を確認しておくと安心です。

    • ☐ 画面とサーバーで、API の型(または仕様書)をどう共有しているか。手作業で書き写していないか
    • ☐ API の仕様を変えたとき、影響する画面をどう見つけるか(型チェック・自動テストで見つかる仕組みがあるか)
    • ☐ 社外の会社や別のチームにも API を公開するか。公開するなら、OpenAPI(API の仕様を決まった形で書く標準)などの仕様書も必要か
    • ☐ サーバー側の入力チェックが、画面のチェックとは別にあるか

    開発会社への質問例です。

    • 「画面とサーバーで、項目名や値の種類の食い違いは、どの段階で見つかる仕組みですか?」
    • 「API を変更したとき、ほかのシステムへの影響はどう確認しますか?」

    hono/client のような型の共有は、画面とサーバーを同じ言語(TypeScript)で作るときに効く方法です。サーバーを別の言語で作る場合や、社外にも API を公開する場合は、OpenAPI の仕様書を作り、そこから型を作る方法が一般的です。どちらが合うかは、誰が API を使うかで変わります。工数が増えやすいのは、既存の API を後から型つきの形に直す場合や、社外向けの仕様書と版の管理まで求める場合です。金額の目安は、依頼先の見積もりで確認してください。

    まとめと次回予告

    この回では、hono/client でヘルプデスクの API を型つきで呼べるようにしました。ポイントは次の3つです。

    • ルートはつなげて書き、その結果の型(AppType)だけを呼び出し側に渡す
    • 状態コードを明示し、エラーの値に as const を付けると、呼び出し側で応答の形を分けて扱える
    • @ts-expect-error を使ったテストで、「間違った呼び方が通ってしまう」ことを型チェックで見張れる

    次回(第10回)は「ログとエラー処理・監視」です。Workers Logs で動きを記録し、エラーの応答の形を API 全体でそろえます。

    この連載の記事一覧

    この記事は連載「Honoで作る社内ヘルプデスク」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。

    システム制作・運用・保守のお問い合わせはこちら

      お問い合わせ


      よかったらシェアしてね!
      • URLをコピーしました!
      • URLをコピーしました!

      この記事を書いた人

      株式会社THIRD HERO代表取締役 朝野貴朗
      Webシステム開発を中心に、toC向けサービスサイトの運営、ツール開発などを行ってまいりました。

      コメント

      目次