Search API

Search API

概要

ブログ記事の全文検索APIです。Cloudflare Pages Functions上で動作し、MiniSearchによるインデックス検索を提供します。

エンドポイント

GET /pj/zpaper/api/search?q=<検索クエリ>

Cloudflare Pages Functionsのファイルベースルーティングにより、functions/pj/zpaper/api/search.tsが処理します。

クエリパラメータ

レスポンス

成功時（200 OK）

{
  "results": [
    {
      "slug": "article-slug",
      "title": "記事タイトル",
      "description": "記事の説明文",
      "tags": "tag1 tag2",
      "createdAt": "2026-03-01",
      "excerpt": "記事本文の先頭500文字（プレーンテキスト）",
      "highlighted_title": "記事<mark>タイトル</mark>",
      "highlighted_excerpt": "...本文の<mark>キーワード</mark>がハイライトされた抜粋...",
      "score": 12.345
    }
  ],
  "query": "検索クエリ",
  "totalResults": 1
}

クエリが空の場合（200 OK）

{
  "results": [],
  "query": "",
  "totalResults": 0
}

レスポンスフィールド

highlighted_titleとhighlighted_excerptはHTMLエスケープ済みのテキストにハイライトを適用しています。検索ページではこれらのフィールドをdangerouslySetInnerHTMLで表示します。

キーワードログ

検索結果が1件以上の場合、クエリ情報がCloudflare KVに非同期で記録されます。詳細はキーワードログAPIを参照してください。

検索フィールドとブースト

MiniSearchは以下のフィールドを検索対象とし、ブースト値によってランキングに重み付けを行います。

MiniSearch設定

{
  fields: ['title', 'description', 'tags', 'excerpt'],
  searchOptions: {
    boost: { title: 3, description: 2, tags: 1.5 },
    prefix: true,   // プレフィックス検索を有効化
    fuzzy: 0.2,     // ファジーマッチング（許容度0.2）
  }
}

• prefix: 入力途中の部分文字列でも検索結果を返します
• fuzzy: タイプミスや表記揺れに対して許容度0.2でマッチングします

キャッシュ

レスポンスには Cache-Control: public, max-age=300 ヘッダが付与され、5分間キャッシュされます。

開発環境

開発環境（pnpm dev）では、Cloudflare Pages Functionsの代わりにクライアントサイドで検索が行われます。

1. ビルド時に public/search-index.json が生成される
2. 検索ページが /pj/zpaper/search-index.json をフェッチ
3. ブラウザ上のMiniSearchでインデックスを構築して検索

本番環境と同じMiniSearch設定（ブースト値、prefix、fuzzy）が使用されます。