DEV Community: Kaziu

エンティティ・値オブジェクト・サービス・UseCase をざっくり整理

Kaziu — Sat, 31 Oct 2026 11:13:25 +0000

まぁRailsというか、DDD(ドメイン駆動設計)やクリーンアーキテクチャの範囲ですけどな

一覧

用語	ひとことで	例
エンティティ	ID で見分けるもの	ユーザー、案件、注文
値オブジェクト	中身で見分けるもの	金額、電話番号、住所、期間
サービスオブジェクト	手続きを入れる箱	税額を計算する、S3 にアップロードする
UseCase	ユーザーがやりたいこと1つ	案件を登録する、注文を確定する

エンティティ ─ ID で見分けるもの

人は、名字が変わっても引っ越しても同じ人です。逆に、同姓同名・同い年の人が2人いても別人です。

このように、中身ではなく ID（その人であること）で見分けるものがエンティティです。

user = User.find(1)
user.update!(name: '鈴木') # 名前が変わっても id: 1 のまま。同じユーザー

Rails では、id を持つ ActiveRecord モデルの大半がエンティティです。

値オブジェクト ─ 中身で見分けるもの

財布の1000円札とあなたの1000円札は、交換しても誰も困りません。お札の番号は気にせず、中身（金額）が同じなら同じものとして扱います。これが値オブジェクトです。

PhoneNumber = Data.define(:value) do
  def initialize(value:)
    raise ArgumentError, '不正な電話番号' unless value.match?(/\A0\d{9,10}\z/)

    super
  end

  def mobile?
    value.match?(/\A0[7-9]0\d{8}\z/)
  end
end

PhoneNumber.new(value: '09012345678') == PhoneNumber.new(value: '09012345678') # => true

特徴は次の3つです。

ID を持たない
中身を変えない（変えたいときは新しく作る）
ルールを持てる（「0 から始まる10〜11桁」「携帯番号か判定する」など）

電話番号をただの String で持っていると、「携帯番号か判定する」処理が User にも Company にもコピペされていきます。値オブジェクトにすれば、電話番号のルールが1か所にまとまります。

サービスオブジェクト ─ 手続きを入れる箱

「税額を計算する」「S3 にファイルをアップロードする」のように、特定のモデルに入れるとモデルが太ってしまう手続きを入れておくクラスです。

class TaxCalculator
  def initialize(amount)
    @amount = amount
  end

  def call
    (@amount * 0.1).floor
  end
end

よくある約束ごとは次のとおりです。

1クラス1つの仕事
公開メソッドは call などの1つだけ
名前は「何をするか」がわかるものにする（UserService のようなあいまいな名前は避ける）

サービス＝ビジネスロジック？

イコールではありません。業務のルールはエンティティや値オブジェクトにも入りますし、サービスには「S3 にアップロードする」のような技術的な処理も入ります。サービスは「ビジネスロジックの置き場所の1つ」くらいに考えておくのが正確です。

UseCase ─ ユーザーがやりたいこと1つ

「案件を登録する」「注文を確定する」のように、ユーザーがアプリでやりたいこと1つ分をクラスにしたものです。アプリの機能一覧をそのままクラスにしたイメージです。

UseCase は指揮役です。自分では細かい作業をせず、エンティティやサービスを呼び出して手順を組み立てます。

class ConfirmOrderUseCase
  def call(user:, order_id:)
    order = Order.find(order_id)
    raise '権限がありません' unless order.user_id == user.id     # 権限チェック

    ActiveRecord::Base.transaction do
      tax = TaxCalculator.new(order.subtotal).call                # サービスを使う
      order.update!(tax: tax, status: :confirmed)                 # エンティティを更新する
    end
  end
end

現場によっては、UseCase を Operation、Interactor、Command などの別の名前で呼ぶこともあります。名前は違っても「ユーザーの操作1つ分の手続き」という役割は同じです。

4つの関係

UseCase「注文を確定する」（指揮役）
   │
   ├─ エンティティを読み書きする   … 注文（Order）
   │      └─ 値オブジェクトを持つ  … 金額、電話番号
   │
   └─ サービスを呼ぶ              … 税額の計算、メール送信、S3

UseCase が段取りを決める
その中で、エンティティを操作したり、サービスに作業を任せたりする
値オブジェクトは、エンティティやサービスの中で「値」として使われる

呼び出す向きは上から下への一方通行です。サービスが UseCase を呼ぶことはありません。

もうActiveJob - Job,Que,Adaptorもレストランに例えますかーー

Kaziu — Fri, 30 Oct 2026 12:08:21 +0000

わかってるんですが、レストランに例えさせてください。

登場人物

まずは対応表です。この記事はずっとこの例えで進めます。

Rails の用語	レストランでいうと
Webリクエスト	来店したお客さんの注文
コントローラ	レジ係
ジョブ	注文票
`perform_later`	注文票をボードに貼ること
キュー	注文票を貼っておくボード
ワーカー	料理人
アダプター	ボードの種類

なぜ「あとでやる」必要があるのか

ユーザー登録したら歓迎メールを送る、という機能を考えます。

class UsersController < ApplicationController
  def create
    user = User.create!(user_params)
    WelcomeMailer.with(user: user).welcome.deliver_now # ← ここで数秒待たされる
    render json: user
  end
end

これはレジ係が注文を受けたあと自分で厨房に入って料理を作り、出来上がるまでレジに戻らない状態です。後ろに並んだお客さんは、その間ずっと待たされます。

メール送信、CSV 出力、外部 API 連携のように時間がかかる処理は、「あとでやる」ことにしてすぐお客さんに返事をしたい。これがジョブの出番です。

ジョブ = 注文票

ジョブは「この仕事をやっておいて」という注文票です。

class WelcomeMailJob < ApplicationJob
  def perform(user_id)
    user = User.find(user_id)
    WelcomeMailer.with(user: user).welcome.deliver_now
  end
end

レジ係（コントローラ）は注文票を書いてボードに貼るだけです。

def create
  user = User.create!(user_params)
  WelcomeMailJob.perform_later(user.id) # ← 注文票を貼るだけ。一瞬で終わる
  render json: user
end

perform_later は「後で（later）実行して（perform）」という意味です。レジ係はすぐ次のお客さんの対応に戻れます。

注文票には「料理」ではなく「テーブル番号」を書く

引数には user そのものではなく user.id を渡しています。

注文票に料理そのものを貼り付ける人はいません。「3番テーブル、ハンバーグ」と書いておき、料理人が作るときに最新の情報を確認します。ジョブも同じで、ID だけ渡して、実行するときに DB から取り直すのが基本です。キューに積んでから実行されるまでの間に、データが変わっているかもしれないからです。

キュー = 注文票ボード

キューは注文票を到着順に並べておくボードです。

 レジ係                 注文票ボード（キュー）            料理人（ワーカー）
┌──────┐  貼る    ┌──────────────────────────┐  取る   ┌──────┐
│      │ ───────▶ │ [票3] [票2] [票1]         │ ──────▶ │ 調理 │
└──────┘          └──────────────────────────┘         └──────┘

レジ係は貼るだけ、料理人は取って作るだけ。お互いの仕事を待ちません
料理人は常に厨房で待機していて、票が貼られたらすぐ取りに来ます
注文が殺到したら、票がボードに並ぶだけです。厨房はパンクしません

「注文のたびに料理人を雇えばいいのでは？」

ボードに並ばせず、注文ごとに新しい料理人を雇って即調理させればいい、と思うかもしれません。Rails でいえば「ジョブごとに新しいプロセスを起動する」方式です。

これは次の理由でうまくいきません。

雇うのが高い: Rails のプロセスは起動に数秒、メモリに数百MB かかります。毎回の研修コストが重すぎます
増えすぎる: 1秒に1000件の注文が来たら、1000人が同時に厨房に入ってきます。CPU より先に、メモリや DB 接続（厨房の広さやコンロの数）が限界を迎えます
注文が消える: 料理人が途中で倒れたら、その注文は誰にも知られずに消えます
やり直しができない: 失敗しても、誰も作り直してくれません

ボードと常駐の料理人なら、人数を一定に保ったまま、注文をなくさず、確実にこなせます。キューは「待たせるための仕組み」ではなく、そのための仕組みです。

アダプター = ボードの種類

注文票ボードにはいろいろな種類があります。ホワイトボード、紙の伝票、本部と繋がった受注システム……。

ActiveJob は、どのボードを使っても注文票の書き方は同じになるように作られています。ボードごとの違いを吸収する「変換プラグ」がアダプターです。

# 注文票の書き方は、どのボードでも同じ
WelcomeMailJob.perform_later(user.id)

# どのボードを使うかは設定 1 行で切り替える
config.active_job.queue_adapter = :async

代表的なボードを見ていきます。

`:async` ─ 店員が頭の中で覚えておく

┌───────────── お店（Rails プロセス 1 つ）─────────────┐
│  レジ係 ──▶ 店員の頭の中のメモ ──▶ 店内の料理人       │
└──────────────────────────────────────────────────────┘

Rails のデフォルトです。キューも料理人も、Rails プロセスの中に全部入っています。

追加で何もインストールしなくても動くので、学習や開発に便利です
ただし注文は店員の頭の中にあるだけです。店を閉める（プロセスを再起動する、デプロイする）と、まだ作っていない注文は全部忘れられます

`:inline` ─ レジ係がその場で作る

ボードを使わず、レジ係がその場で自分で料理します。perform_later と書いても非同期になりません。

開発中に「ジョブがちゃんと動くか」をすぐ確かめたいときに便利です。

`:test` ─ 研修用のボード

実際には料理を作らず、「注文票が正しく貼られたか」だけを記録します。RSpec でテストするときに使います。

expect {
  post '/users', params: { ... }
}.to have_enqueued_job(WelcomeMailJob)

`:solid_queue` / `:sidekiq` / `:sqs` など ─ 店の外にあるボード

本番用です。注文票は店の外にある受注システム（DB、Redis、Amazon SQS など）に記録されます。

┌── お店（Rails プロセス）──┐      ┌── 店の外の受注システム ──┐
│  レジ係                    │ ───▶ │  注文票ボード             │
└────────────────────────────┘      └───────────────────────────┘
   ↑ 何度閉店・開店しても               ↑ 注文はこっちに残る

店を閉めても（Rails を再起動・デプロイしても）、注文は残ります
料理人を別の厨房（別のサーバー）に置いて、必要なだけ増やせます
失敗した注文を「5分後にもう一度」と貼り直せます

ただし、ボード自体が壊れたときにどこまで残るかは、ボード次第です。

Redis もメモリに置いています。永続化（スナップショットや追記ログ）を設定していないと、Redis の再起動で消えます
DB や SQS はディスクや複数拠点に保存されるので、より消えにくいです

:async との本当の違いは「メモリかディスクか」ではなく、ボードがお店（Rails）と一緒に閉まるかどうかです。

アダプター	ボードの置き場所	Rails 再起動で消える？	ボード自体の再起動で消える？	主な用途
`:async`	店員の頭の中（Rails のメモリ）	消える	─	学習・開発
`:inline`	なし（その場で作る）	─	─	開発・デバッグ
`:test`	研修用の記録	─	─	テスト
`:sidekiq`	Redis（別サーバーのメモリ）	消えない	永続化の設定次第	本番
`:solid_queue`	DB（ディスク）	消えない	ほぼ消えない	本番
`:sqs` 系	Amazon SQS	消えない	複数拠点に保存され消えにくい	本番

本番で気をつけたいこと

店の外にあるボードを使うと、:async や :inline では見えなかった問題が出てきます。

1. 同じ注文票が 2 枚届くことがある

SQS のような分散キューでは、まれに同じジョブが 2 回実行されることがあります。ハンバーグが 2 皿届いたら困りますよね。

ジョブは「何回実行しても結果が同じになる」ように作ります（冪等性）。例えば「送信済みフラグが立っていたら何もしない」といった工夫です。

2. 会計が確定する前に注文票を貼らない

ActiveRecord::Base.transaction do
  user = User.create!(user_params)
  WelcomeMailJob.perform_later(user.id) # ← 危険
  # ...この後で例外が起きてロールバックすると？
end

トランザクションの中で perform_later すると、次のことが起こりえます。

料理人が先に注文票を見て厨房に行ったのに、まだ注文が確定していない（コミット前なので User.find で見つからない）
注文がキャンセルされた（ロールバック）のに、料理人は作り始めてしまう

注文票は会計が確定してから（トランザクションのコミット後に）貼りましょう。after_commit を使うのが定番です。

なお Rails 7.2 以降には、トランザクション中に積んだジョブをコミット後まで遅らせる仕組み（enqueue_after_transaction_commit）もあります。

レストランで理解する Rack・プロセス・スレッド・Unicorn・Puma・Action Cable

Kaziu — Thu, 29 Oct 2026 12:21:32 +0000

普段 Controller や Model を書いているぶんには、Rails の下で何が動いているかを意識することはあまりありません。
ところが、Rails アプリにリアルタイムチャットや通知のような「つなぎっぱなし」の機能を入れようとすると、急に「Unicorn だと相性が悪い」「Action Cable なら大丈夫」といった話が出てきます。

この記事では、そうした話を理解するための土台となる Rails の足元の仕組みを、レストラン にたとえて整理します。

1. Rack：注文票の共通フォーマット

Rack は、Ruby の Web サーバーと Web アプリをつなぐ共通の約束事です。

call(env) を持ち、[ステータス, ヘッダ, ボディ] を返すオブジェクトなら Rack アプリ

class HelloApp
  def call(env)
    [200, { 'content-type' => 'text/plain' }, ['Hello']]
  end
end

レストランでいうと 注文票のフォーマット です。フォーマットが決まっているので、ホール（Unicorn、Puma）と厨房（Rails、Sinatra）を自由に組み合わせられます。

注文票が厨房に届くまでには、ミドルウェア（入口の警備員や受付）を通ります。

お客さん → 警備員（Rack::Attack） → 受付（Rack::Cors） → 厨房（Rails）

2. 層：ホール → 受付 → 厨房

Web サーバー（Unicorn / Puma）   ホール：お客さんを迎え、店員を割り当てる
Rack ＋ ミドルウェア             注文票と、受付・警備
アプリケーション層（Rails）      厨房：Controller や Model が動く

ここでいう「アプリケーション層」は、OSI 参照モデルのものとは別物で、Rails のコードが動いている段階のことです。

3. プロセスとスレッド：店舗と店員

プロセス ＝ 店舗（専用の厨房・冷蔵庫を持つ）
スレッド ＝ 店員（同じ店の冷蔵庫を共用する）

	プロセス（店舗）	スレッド（店員）
メモリ	別々	共有
作るコスト	重い	軽い
怖いところ	メモリを食う	共有データの取り合い

x = 0
Thread.new { x = 100 }.join
p x  # => 100（共有しているので書き換わる）

y = 0
Process.wait(fork { y = 100 })
p y  # => 0（別の店舗なので影響しない）

店員同士が冷蔵庫を共有していると、「2人が同時に卵の数を数えて、在庫数がずれる」といった事故が起きます。これが スレッドセーフ問題 です。Ruby では、クラス変数やグローバル変数がこの「共有の冷蔵庫」にあたります。

4. ブロッキング：テーブルの横で立ち尽くす店員

スレッドが何かを待っている間、他のことが何もできずに止まっている状態を ブロッキング と呼びます。

店員：「ご注文は？」
お客さん：（メニューを30分眺めている……）
店員：（ずっとテーブルの横で待っている）

普通のリクエストの待ち時間は一瞬なので問題になりません。困るのは、ロングポーリングや WebSocket のような「つなぎっぱなし」の通信です。

5. Unicorn：店員1人の店舗をたくさん出す

Unicorn マスター（オーナー）
 ├ ワーカー1（店員1人）
 ├ ワーカー2（店員1人）
 └ ワーカー3（店員1人）

1ワーカーが同時に処理できるのは1件だけ
店舗が独立しているので安全。ただしメモリを食う

つなぎっぱなしの通信が来ると、こうなります。

ワーカー1〜3：全員がお客さんの横で待機
→ 次のお客さんの相手が誰もできない 💀

6. Puma：1店舗に店員をたくさん置く

Puma プロセス
 ├ スレッド1（店員）
 ├ スレッド2（店員）
 └ スレッド3（店員）

Unicorn より少ないメモリで、多くのお客さんをさばける
コードはスレッドセーフである必要がある

Ruby には GVL があり、Ruby のコードを実行できるのは同時に1スレッドだけです（包丁が1本しかないイメージ）。それでも DB などを待っている間は包丁を手放すので、Web アプリなら十分に速く動きます。

ただし、つなぎっぱなしの通信ではスレッドが待機で埋まり、結局 Unicorn と同じく詰まります。

7. Action Cable：呼び出しベルで見回るホール係

(Rails上で動きます)

発想を変えて、テーブルの横で待つのをやめます。

ホール係（1人）：
  各テーブルに呼び出しベルを置く
  → ベルが鳴ったテーブルにだけ、さっと対応する

これが イベントループ です。待機中の接続に誰も張り付かないので、接続が大量にあってもさばけます。

Action Cable は、Rack の rack.hijack で接続そのものを引き取り、このイベントループに渡します。そのため Web サーバーのワーカーはすぐに手が空き、Unicorn の上でも動きます。

弱点：ホール係が1件の重い仕事に没頭すると、全テーブルが待たされます。
→ Action Cable の上では重いクエリや sleep を避け、重い処理はバックグラウンドジョブに任せます。

まとめ

	待機中の接続に張り付くもの	接続が増えると	重い処理
Unicorn	プロセス	メモリが足りなくなる	強い
Puma	スレッド	スレッドが足りなくなる	まあまあ
Action Cable	なし	ほぼ平気	弱い

ngrok で「手元のサーバー」を一時的に公開して Webhook の送信をテスト

Kaziu — Mon, 28 Sep 2026 08:00:51 +0000

はじめに

SaaS の開発で、Webhook の送信機能を作っています。

お客さんは SaaS のデータを自社の基幹システムへ連携していますが、今は SaaS の API をポーリング（定期的に問い合わせる方式）して変更を取りに来ているため、リアルタイムには反映されません。
そこで、SaaS 側でデータが変わった瞬間に Webhook でお客さんのシステムへ送り、基幹システムのデータを自動で更新できるようにするのが目的です。

困ったのは、「送られる側」をローカルでどう用意するかでした。

送り先 URL は利用者が自由に入力できるため、社内ネットワークのアドレスを指定されると、サーバーに内部へのリクエストを送らせる SSRF（Server-Side Request Forgery） 攻撃が成立してしまいます。
その対策として、インターネット上に公開された HTTPS の URL 以外には送信しない制限を入れました。そのため、手元の localhost に受け口を立てても送れません。

ngrok とは

手元の PC で動いているサーバーに、一時的な公開 URL を付けてくれるツールです。

外部のサービス ──→ https://xxxx.ngrok-free.app ──(ngrok が中継)──→ 自分の PC の localhost:3000

公開された HTTPS の URL になるので、SSRF 対策のチェックを緩めずにローカルで受信を確認できます。
起動中は http://localhost:3040 で、届いたリクエストの中身も見られます。

使い方

1. 仮の受け口を作る

POST を受け取って中身を表示し、200 を返すだけのサーバーです。

# webhook_receiver.py
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers['Content-Length']))
        print(dict(self.headers))
        print(json.dumps(json.loads(body), indent=2, ensure_ascii=False))
        self.send_response(200)  # 500 や 401 にすれば失敗時の挙動も確認できる
        self.end_headers()

HTTPServer(('0.0.0.0', 4000), Handler).serve_forever()

python3 webhook_receiver.py

2. ngrok で公開する

brew install ngrok
ngrok config add-authtoken <あなたのトークン>
ngrok http 4000

表示された https://xxxx.ngrok-free.app が公開 URL です。

3. 送信側に URL を設定して動かす

アプリの Webhook 設定にこの URL を入れてデータを更新すると、受け口のターミナルに届いた JSON が表示されます。

{
  "eventId": "event_123",
  "type": "order",
  "occurredAt": "2026-01-01T12:00:00+09:00",
  "order": { "id": 1, "name": "サンプル注文" }
}

注意点

公開 URL は誰でもアクセスできるので、確認が終わったらすぐ止める
実データは流さず、ダミーデータで確認する
細かいパターン（エラー・タイムアウトなど）は、自動テストで HTTP 通信をスタブして確認し、ngrok は最後の通し確認に使う

まとめ

ポーリングではリアルタイムにならないため、変更を即座に送る Webhook を作っている
SSRF 対策で公開 URL にしか送れないが、ngrok を使えばチェックを緩めずにローカルで確認できる

「先頭カラムが同じインデックス、それ1つ無駄ちゃう？」— 冗長インデックスの見つけ方と消し方

Kaziu — Tue, 15 Sep 2026 07:02:01 +0000

テーブルのインデックスを眺めていて、こんな2本が並んでいるのを見つけたことはないだろうか。

KEY        `idx_logs_on_import_id`            (`import_id`)
UNIQUE KEY `idx_logs_on_import_id_and_file`   (`import_id`, `file_path`)

結論から言うと、上の単独インデックスはたいてい消せる。この記事では「なぜ消せるのか」「本当に消していいのか（消せない例外）」「どう機械的に見つけるか」「安全な消し方」までを一通りまとめる。

なぜ「単独 `(import_id)`」が冗長なのか

ポイントは 複合インデックスの “左端プレフィックス（leftmost prefix）” は、単独インデックスとしても使える という B-Tree インデックスの性質だ。

(import_id, file_path) というインデックスは、まず import_id で並び、その中で file_path で並ぶ。電話帳が「姓 → 名」の順に並んでいるのを想像するといい。

「姓だけで探す」→ できる（左から順に並んでいるから）
「名だけで探す」→ できない

同じように (import_id, file_path) は、

WHERE import_id = ? → 効く（左端が import_id）
WHERE file_path = ? → 効かない（2番目のカラム単独では使えない）

つまり WHERE import_id = ? の検索は、複合インデックスがそのまま賄える。単独の (import_id) は複合と役割が丸かぶりというわけだ。

冗長インデックスは「あって困る」

「使わないだけで害はないのでは？」と思うかもしれないが、インデックスはタダではない。

書き込みが遅くなる：INSERT / UPDATE / DELETE のたびに、全インデックスを更新する必要がある。冗長な1本ぶん、無駄な更新コストが毎回乗る。
ディスク・メモリを食う：インデックスは実データとは別に実体を持つ。バッファプールも圧迫する。
オプティマイザの選択肢を無駄に増やす：実行計画の検討対象が増える。

読み取りのメリットはゼロ（複合で足りる）なのに、書き込みコストだけ払っている状態。これが「冗長」を消すべき理由だ。

どうやって機械的に見つけるか

目視で全テーブルを追うのは非現実的。ツールに任せよう。

1. MySQL 標準ビュー `sys.schema_redundant_indexes`（おすすめ・導入不要）

MySQL 5.7 以降なら追加インストール不要で使える。左端プレフィックスの重複を判定し、削除用の SQL まで生成してくれる。

SELECT
  table_name,
  redundant_index_name,     -- 冗長な方（消す候補）
  redundant_index_columns,
  dominant_index_name,      -- それを包含している方（残す）
  dominant_index_columns,
  sql_drop_index            -- そのまま実行できる DROP 文
FROM sys.schema_redundant_indexes
WHERE table_name = 'logs';

出力イメージ：

redundant_index_name : idx_logs_on_import_id
dominant_index_name  : idx_logs_on_import_id_and_file
sql_drop_index       : ALTER TABLE `app`.`logs` DROP INDEX `idx_logs_on_import_id`

2. `pt-duplicate-key-checker`（Percona Toolkit / CLI）

DB 全体をまとめてスキャンして、重複・冗長インデックスと DROP 文を吐く定番ツール。CI や定期ジョブに組み込みやすい。

pt-duplicate-key-checker --host 127.0.0.1 --user readonly --ask-pass

3. `sys.schema_unused_indexes`（未使用インデックスの検出）

「冗長」とは別軸で、「前回のサーバ起動以降、一度もクエリで使われていないインデックス」を洗い出せる。ただし後述の FK 注意あり。

4. ORM 付属のツール（例：Rails の `active_record_doctor`）

アプリ側から detect_extraneous_indexes（冗長）や detect_unindexed_foreign_keys（FK に索引が無い）を検出できる。マイグレーションと同じ言語で回せるので CI 相性が良い。

【重要】消してはいけない冗長候補：外部キー（FK）の索引

ツールが「未使用」「候補」と出しても、消すとエラーになるインデックスがある。それが 外部キーの索引だ。

MySQL は「親テーブルの行が削除・更新されたとき、それを参照している子行がいないか」を毎回チェックする。これは実質 WHERE fk_column = ? の検索で、索引が無いと毎回フルスキャンになって激遅。だから MySQL は「FK を張るなら子カラムに索引を必ず持て」と要求し、無ければ自動で作る。

-- これは「未使用」に見えても、FK のために必須。消すと ERROR 1553。
KEY `fk_logs_on_user_id` (`user_id`),
CONSTRAINT `fk_logs_on_user_id` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`)

見分け方：その FK カラムを「左端」に持つ “別の” インデックスがあるか？

あるなら（例：複合インデックスの左端が FK カラム）→ FK の要件はそちらが満たすので、単独インデックスは消せる。
無いなら → その索引が FK 唯一の頼み → 消せない（消すと ERROR 1553: Cannot drop index ... needed in a foreign key constraint）。

冒頭の例で単独 (import_id) を消せるのは、複合 (import_id, file_path) の左端が import_id で、FK の索引要件も肩代わりできるからだ。

安全な消し方

マイグレーション

インデックスを1本 DROP するだけ。可逆（ロールバックで復活）にしておく。

class RemoveRedundantIndexFromLogs < ActiveRecord::Migration[8.0]
  def change
    remove_index :logs, column: :import_id, name: 'idx_logs_on_import_id'
  end
end

素の SQL なら：

ALTER TABLE `logs` DROP INDEX `idx_logs_on_import_id`;

適用前に「本当に消せるか」を実地で裏取り

とくに FK が絡むカラムは、机上で「複合が包含するはず」と思っても、実際に DROP して ERROR 1553 が出ないかを一度確認しておくと安心だ。開発 DB で up → down して、元に戻せることも確認しておく。

# 実際に DROP が通るか（FK エラーが出ないか）を確認
bin/rails db:migrate:up   VERSION=<version>
# 確認できたら元に戻す（開発 DB を汚さない）
bin/rails db:migrate:down VERSION=<version>

up が ERROR 1553 を出さずに通れば、「複合インデックスが FK の索引要件を満たしている」ことの動かぬ証拠になる。

Railsのstructure.sqlって何？何のため?

Kaziu — Tue, 15 Sep 2026 02:55:12 +0000

Railsのプロジェクトを触っていると、db/structure.sql という巨大なファイルに出会います。
「これ何？勝手に書き換わるけど触っていいの？」と戸惑いがちなこのファイルを、初心者向けにまとめます。

結論：DBの「完成形の設計図」

structure.sql は、ひとことで言うと

今のデータベースの構造を、ゼロから丸ごと再現するためのSQL命令をまとめた「完成形の設計図（スナップショット）」

です。しかもRailsが自動で生成・更新するファイルで、人が手で書くものではありません。

中身はこんなイメージです。

CREATE TABLE `deals` (              -- 「案件」テーブルを作る命令
  `id` bigint unsigned NOT NULL,
  `name` varchar(255),
  ...
);

CREATE TABLE `contacts` ( ... );    -- 「コンタクト」テーブルを作る命令
...（全テーブル分つづく）...

-- 末尾に「どの設計変更まで適用済みか」の台帳
INSERT INTO `schema_migrations` VALUES
('20260806000000'),
('20260805000000'),
...

前半に全テーブルの CREATE TABLE、末尾に「どこまで変更を適用済みか」の台帳（schema_migrations）が入っています。

前提知識：マイグレーションとの関係

structure.sql を理解するには、マイグレーションとセットで考えるのが近道です。

マイグレーション = DB構造の変更履歴（＝設計変更の指示書の束）
- 例：「dealsテーブルにstatus列を追加する」といったファイルが1変更につき1つ
- ファイル名は 20260803000000 のような 日付＋番号
structure.sql = その履歴を全部適用し終えた最終結果のスナップショット

図にするとこうです。

① 開発者がマイグレーションファイルを書く（変更の指示書）
         例:「dealsにstatus列を追加」

② db:migrate を実行 → 実際にDBが変更される

③ ★このときRailsが自動でstructure.sqlを"今のDBの姿"に更新する★

つまり structure.sql は、db:migrate の副産物として自動更新されるもの。原則、手で編集しません。

何のためにあるの？

一番の存在理由は、新しくDBを一から作るときに速いからです。

新メンバーが環境構築するとき、あるいはテスト用DBを毎回作り直すとき、DBを「まっさら → 最新の形」にする必要があります。その方法は2つあります。

方法	やること	速度
マイグレーションを全部実行	何百個の指示書を1個ずつ順番に実行	遅い
`structure.sql` を読み込む	完成形を一発で再現	速い

なぜマイグレーション全実行は遅いのか

理由①：歴史をもう一度なぞるので無駄が多い

マイグレーションは変更履歴なので、全実行すると過去の回り道まで再現します。

① dealsテーブルを作る
② dealsにstatus列を追加
③ ②のstatus列を削除する   ← 気が変わった
④ dealsにstate列を追加

最終的に欲しいのは「statusは無く、stateがある」状態だけ。でも全実行は②で作って③で消す無意味な往復まで律儀に再現します。structure.sql は最終結果だけなので回り道しません。

理由②：1個ずつ直列でしか実行できない（オーバーヘッド）

マイグレーションは順序依存なので並列化できず、1個ごとに「Rails起動→コード読込→SQL変換→実行→台帳記録」の準備・後片付けが発生します。これが数百回積み重なる。
structure.sql は1本の巨大なSQLを流し込むだけなので、この繰り返しコストがほぼゼロです。

理由③：中間状態の作り替えが積もる

同じ「state列を追加」でも、マイグレーションはテーブル作成→列追加→列削除→別の列追加…と中間状態を何度も作り替えます。インデックスの貼り直しなどが絡むとさらに遅くなります。

たとえ話

マイグレーション全実行 = 料理番組を1話目から全部見て、途中の失敗作まで作り直して追体験する
structure.sql = 完成した料理の写真とレシピを見て、それだけ作る

欲しいのは完成品だけなので、後者が圧倒的に速い、というわけです。

だから2つを使い分ける

structure.sql とマイグレーションは、どちらか一方が偉いのではなく、場面で使い分けます。

場面	使うもの	理由
新環境構築・テストDB作成	structure.sql（完成形）	履歴をなぞる必要はなく、速く最新状態を再現したい
稼働中の本番DBを変更	マイグレーション（差分だけ）	既存データを保ったまま「今回の変更分」だけ安全に当てたい

新メンバーの環境構築は「まっさら → 最新形にしたいだけ」なので、structure.sql が最適です。

補足：schema.rb と structure.sql

Railsの設計図には2形式があり、プロジェクトごとにどちらか一方を選びます。

ファイル	中身	特徴
`db/schema.rb`	Rubyで書かれた設計図	シンプル。Railsのデフォルト
`db/structure.sql`	生のSQLで書かれた設計図	トリガーやDB独自機能まで忠実に表現できる

MySQLのトリガーや細かい制約など、Rubyの schema.rb では表現しきれない機能を使っているプロジェクトでは structure.sql を選びます。

まとめ

質問	答え
structure.sqlって何？	今のDB全体の構造を再現するSQLをまとめた「完成形の設計図」
Railsが作るの？	はい。`db:migrate` 実行時に自動生成・更新される
手で書く？	原則ノー。自動更新される
何の役に立つ？	新環境・テストDBを一瞬で最新構造にするため

SQL複数カラムの計算結果をインデックスにまとめる設計手法と、書き込みオーバーヘッドの限界

Kaziu — Mon, 14 Sep 2026 14:42:59 +0000

データベースで複数のカラムを掛け合わせた検索（例：(単価 × 数量 - 割引) × 税率）を実行すると、通常は全件スキャン（Table Scan）が発生して大幅な遅延を引き起こします。

この記事では、複数カラムの計算結果を単一または複合インデックスへ集約する方法と、気になる書き込み時のオーバーヘッド（遅延リスク）のレベル感・警戒時の対策について解説します。

1. 複数カラムの計算結果をインデックスにまとめる2つの手法

例えば、以下の 5 カラムを持つ orders テーブルを考えます。

price（単価）
quantity（数量）
discount（値引き）
tax_rate（税率）
status（注文ステータス）

「合計請求金額が 10,000 円以上の完了済み（completed）注文」を高速検索したい場合、アプローチは 2 通り存在します。

アプローチA：式インデックス（Expression Index）を直接貼る

計算式そのものをインデックスに定義し、status カラムと組み合わせた複合インデックスを作成します。

SQL (PostgreSQL)

CREATE INDEX idx_orders_total_amount_and_status ON orders (
  ((price * quantity - discount) * (1 + tax_rate)), 
  status
);

Rails migration

class AddCalculatedIndexToOrders < ActiveRecord::Migration[7.0]
  def change
    add_index :orders, 
              ["((price * quantity - discount) * (1 + tax_rate))", :status],
              name: "idx_orders_total_amount_and_status"
  end
end

アプローチB：生成列（Generated Column）＋複合インデックス【おすすめ】

式が複雑な場合、テーブルに「計算結果カラム」を定義してそこにインデックスを貼る方が、SQLの可読性とメンテナンス性が格段に向上します。

Rails (Migration)

class AddTotalAmountToOrders < ActiveRecord::Migration[7.0]
  def change
    change_table :orders do |t|
      # 1. 4つのカラムを使った計算列を定義（DB側で自動計算＆保存される）
      t.virtual :total_amount, 
                type: :decimal, 
                precision: 10, 
                scale: 2, 
                as: "(price * quantity - discount) * (1 + tax_rate)", 
                stored: true

      # 2. 生成列と status の複合インデックスを作成
      t.index [:total_amount, :status], name: "idx_orders_total_amount_and_status"
    end
  end
end

2. 書き込み（INSERT / UPDATE）オーバーヘッドのレベル感

計算インデックスや生成列を使用すると、対象カラムのいずれか 1 つでも INSERT または UPDATE されるたびに「再計算＋ B-Treeインデックスの再配置」が発生します。

パフォーマンスへの影響度は「データ件数」よりも「1秒あたりの書き込み・更新回数（TPS）」に依存します。

警戒レベル	1秒あたりの書き込み/更新数 (TPS)	アプリへの影響・状況判定・推奨アクション
レベル 1：安全	〜 50 回/秒	一般的なWebシステムやECサイト。ミリ秒以下の処理で完結する。対策不要（積極的に導入して良い）
レベル 2：注意	100 〜 500 回/秒	スパイク時のアクセスやSNSアプリ。書き込みのレイテンシがわずかに上昇。モニタリング継続（Slow Queryログを監視）
レベル 3：警戒	1,000 回/秒以上	IoTデータ受信、金融取引、大量バッチ処理。CPU使用率急増・ロック詰まりが発生。要対策（アーキテクチャの見直しが必要）

どのくらいの「データ量」で影響が大きくなる？

データ量が増えると、「インデックス自体のサイズがメモリ（RAM）に入り切らなくなったタイミング」でパフォーマンスが急激に落ちます。

メモリに収まるサイズ（〜数百万件）：
インデックスの更新処理がすべてメモリ（RAM）上で完結するため、計算オーバーヘッドがあってもミリ秒以下（数ミリ秒）で終わります。
メモリに入り切らないサイズ（数千万件〜億単位）：
インデックスを更新するたびにディスク（SSD/HDD）への読み書きが発生します。こうなると、1回の UPDATE の遅延が数ミリ秒から数ミリ秒〜数秒へと跳ね上がります。

特に遅くなりやすい「ワーストケース」のパターン

同じ書き込みでも、以下のパターンは特にオーバーヘッドが大きくなります。

更新が超頻繁なカラム（例：updated_at や status）が含まれている
price などの金額は一度決まると滅多に変わりませんが、status や updated_at が計算式に含まれていると、ステータスが変わるたびに計算＆インデックス再配置が発生します。
一括更新（UPDATE ... WHERE や BULK INSERT）を行う
1件ずつの更新なら数ミリ秒の遅延で済みますが、UPDATE orders SET price = price * 1.1 のように10万件を一括更新する場合、10万回の再計算とインデックス更新が同時に走り、DBが数秒〜数分フリーズします。

Rails の `dependent: :destroy` が激重になる話を簡単な例で

Kaziu — Mon, 14 Sep 2026 06:28:26 +0000

何が起きるか

親レコードを消すと、子レコードも一緒に消えて便利な dependent: :destroy（いわゆる cascade 削除）。
でも子がコールバックを持っていると、削除のたびにそれが発火します。

class Author < ApplicationRecord
  has_many :books, dependent: :destroy
end

class Book < ApplicationRecord
  belongs_to :author, touch: true   # 消すと親の更新日時を更新（いわゆる touch）
  after_destroy :reindex_search     # 1件消すたびに Elasticsearch を再インデックス（同期・重い）
end

author.destroy すると…

Author を1件destroy
 └─ books が1000件あれば 1件ずつ destroy（cascade）
      └─ そのたびに親を touch し、after_destroy で
         Elasticsearch 更新が「直列」で1000回走る 😱

件数が少ないうちは気づかず、本番のデータ量で突然タイムアウトします。

対策：重い子だけ「コールバック無し」で先に消す

delete_all はコールバック（cascade も touch も）を発火させず、SQL 1発で消します。

ActiveRecord::Base.transaction do
  Book.where(author_id: author.id).delete_all  # ① 重い子を静かに一掃
  author.destroy                               # ② もう子はいないので連鎖しない
end

# Elasticsearch の更新は捨てずに、あとで非同期・一括で1回だけ
ReindexJob.perform_later(author.id)            # ③ トランザクションの外で

ポイント3つ

やること	理由
重い子を `delete_all` で先に消す	コールバック（cascade / touch）を発火させない（`destroy_all` は発火する）
本体はそのあと消す	連鎖する子が残っていないので重い処理が走らない
重い処理（ES再インデックス）は非同期ジョブで一括	「同期で1件ずつ」→「非同期でまとめて1回」に置き換え

用語メモ

cascade（カスケード） … 親を消すと子も連鎖して消える挙動。dependent: :destroy がこれ
touch … 中身は変えず「更新された印」として関連レコードの更新日時だけ更新すること
destroy = 1件ずつ読み込み、コールバックを呼ぶ（安全だが遅い）
delete = SQLで直接、コールバックを呼ばない（速いが自己責任）

SQLの自己結合（self-join）を一番簡単な例で

Kaziu — Mon, 14 Sep 2026 04:51:17 +0000

「同じテーブルを自分自身に結合する」のが自己結合です。
初めて見ると「え、同じテーブルをJOIN…？」と戸惑いますが、
⭐️ 親子・上下の関係が1つのテーブルに入っているときの定番テクニックです。

例：社員テーブル（社員も上司も“社員”）

上司も社員なので、同じ employees テーブルに入っています。

id	name	manager_id（上司のid）
1	山田（部長）	(なし)
2	佐藤	1
3	鈴木	1

「各社員と、その上司の名前を並べて出したい」とき、
employees をもう一度、別名で結合します。

SELECT
  emp.name     AS 社員,
  boss.name    AS 上司
FROM employees AS emp
LEFT JOIN employees AS boss   -- ← 同じテーブルを別名で結合
  ON emp.manager_id = boss.id;

結果:

社員	上司
山田（部長）	(なし)
佐藤	山田（部長）
鈴木	山田（部長）

ポイントは「別名（AS）」

同じテーブルなので、AS emp / AS boss と別名を付けて別テーブル扱いにするのが肝です。

emp.name … 社員本人の名前
boss.name … 上司の名前

別名がないと「どっちの name？」が区別できません。

LEFT JOIN にする理由

上司がいない人（部長など）も結果に残したいので LEFT JOIN を使います。
INNER JOIN だと上司がいない行が消えてしまいます。

まとめ

親子・上下の関係が同じテーブルにあるとき、テーブルを別名で自分自身に結合すると「本人＋相手」を1行に並べられる。 これが自己結合。

社員×上司、カテゴリ×親カテゴリ、取引先×その親の取引先など、
「同じ種類のもの同士の関係」を1テーブルで持つ設計で活躍します。

「Blob」って何？ブラウザでファイルをダウンロードする仕組み

Kaziu — Fri, 11 Sep 2026 03:13:11 +0000

CSVダウンロード機能を実装すると、こんな見慣れないコードが出てきます。

const blob = new Blob([response.data], { type: 'text/csv' })
const objectURL = window.URL.createObjectURL(blob)
downloadFile(objectURL, 'データ.csv')

「Blob？」「URLを作る？」「それをダウンロード？どこから？」を、この記事でスッキリさせます。

Blob とは

Blob = 中身が何でもいい「データのかたまり」。ブラウザにとっての"ファイルのようなもの"です。文字・画像・CSV・PDFなど何でも入り、「これはCSVです」といった種類ラベル（MIMEタイプ）を持てます。

ブラウザに「これはファイルだよ、保存してね」と伝えるには、データを"ファイルの形"＝Blobにする必要があります。生の文字データのままでは、ただの文字列としか扱われません。

手紙に例えると

手紙の例え	実際のもの
書類（CSVの中身）	`response.data`
封筒に入れる	`new Blob(...)`
宛名シールを貼る	`createObjectURL` のURL
投函する＝保存	`<a download>` をクリック

コードの意味

// ① バイナリのまま受け取る（これを忘れるとCSVが壊れることがある）
const response = await api.get(url, { responseType: 'blob' })

// ② データを「CSVファイル」の箱に入れる
const blob = new Blob([response.data], { type: 'text/csv' })

// ③ その箱を指す一時的なURLを発行する
const objectURL = window.URL.createObjectURL(blob)

// ④ そのURLをファイルとして保存させる
downloadFile(objectURL, 'データ.csv')

ポイントは ③のURL。これは https://... のようなサーバー上の場所ではなく、
いま手元（ブラウザのメモリ）にあるデータを指す案内シール です。

downloadFile の中身も単純で、「download属性つきの<a>を作ってJSでクリックするだけ」。

function downloadFile(url, filename) {
  const a = document.createElement('a')
  a.href = url
  a.download = filename
  a.click()
}

リンク先が blob: URL なので、サーバーに行かず、手元のデータをそのままファイル保存 します。
つまり「URLをダウンロード」と言っても、落とし直しではなく、すでに持っているデータを保存しているだけなのです。

補足：使い終わったURLは片付ける

createObjectURL のURLはメモリを占有し続けるので、使い終わったら解放するのが丁寧です。

window.URL.revokeObjectURL(objectURL)

まとめ

Blob = ブラウザにとっての"ファイルのようなデータのかたまり"
createObjectURL のURLは、サーバーではなく手元データへの案内シール
<a download> クリックで、そのデータがファイルとして保存される
この流れは画像・PDF・ZIPなどどんなファイルでも同じ

Ruby のブロックと yield を一番簡単な例で

Kaziu — Thu, 10 Sep 2026 05:24:33 +0000

Ruby を書いていると必ず出てくる「ブロック」と「yield」。
難しく見えますが、要は 「処理を渡す」「渡された処理を実行する」 だけです。

ブロックとは

メソッドに渡す「処理のかたまり（コードの切れ端）」 のこと。
{ } か do...end で囲みます。

[1, 2, 3].each { |n| puts n }
#              └──────────┘ これがブロック

.each に「各要素で puts n してね」という指示書を渡しています。

1
2
3

{ } と do...end は同じもの。長いときは do...end を使うだけです。

[1, 2, 3].each do |n|
  puts n
end

yield とは

メソッドの中の「yield と書いた場所」で、渡されたブロックを実行する命令。

def あいさつ
  puts "こんにちは"
  yield              # ← ここで渡されたブロックを実行
  puts "さようなら"
end

あいさつ { puts "元気ですか？" }

こんにちは
元気ですか？    ← yield の場所にブロックが差し込まれる
さようなら

yield は好きな場所に置け、何回でも呼べ、値も渡せます。

def 数える
  yield 1
  yield 2
end

数える { |n| puts "#{n}番目" }
# 1番目
# 2番目

2つの関係

ブロック = 渡す「やることメモ」（呼ぶ側が書く）
yield = そのメモを実行する命令（メソッド側が書く）

差し込む場所を決めるのがメソッド、差し込む中身を決めるのが呼ぶ側。

実践編：yield で処理を「挟み込む」

yield の本当に便利な使い方が、共通の前処理と後始末で、渡された処理を挟むパターンです。

def with_debug
  old = Rails.logger.level
  Rails.logger.level = :debug   # 前処理：ログを debug に
  yield                         # 呼び出し側の処理を実行
ensure　# エラーが起きても起きなくても、最後に必ず実行される(=finally)
  Rails.logger.level = old      # 後始末：必ず元に戻す
end

使い方：

with_debug do
  # この中だけログが debug になる
  user.save!
end
# ここを抜けると自動で元のログレベルに戻る

なぜ便利か

共通部分（ログ切替と復元）を1か所にまとめられる。使う側は「何をしたいか」だけ書けばよい。
ensure で後始末が保証される。ブロックの中でエラーが起きても、ログレベルは必ず元に戻る。

もし yield を使わなければ、使う場所ごとに「切替 → 処理 → 復元」を毎回コピペする羽目になります。yield なら枠（前後処理）はメソッド側、中身は呼ぶ側、ときれいに分けられます。

もう一つの例：処理時間を測る

同じパターンで「実行時間の計測」も書けます。

def measure(label)
  start = Time.now
  yield
ensure
  puts "#{label}: #{Time.now - start}秒"
end

measure("重い処理") do
  heavy_task
end
# => 重い処理: 1.23秒

「共通の前後処理でブロックを挟む」 ——これは Ruby で頻出の設計パターンです。
File.open { |f| ... }（開いて必ず閉じる）なども、この仲間です。

OCRで名刺を一括登録する機能をつくった話 — “1ページ複数名刺”という落とし穴

Kaziu — Tue, 14 Jul 2026 11:38:57 +0000

はじめに

展示会などでたまっていく紙の名刺を、CRMに手入力するのはなかなか大変です。そこで 「名刺を詰め込んだPDF（や画像）をアップロードすると、取引先・担当者データを自動で一括登録する」 機能を実務にて作りました。

最初は「OCRに投げれば終わりだろう」と思っていたのですが、実際にやってみると OCRは意外と万能ではない こと、そして どこで処理を分けるか という設計判断が肝になることに気づかされました。この記事では、その勘所と、いちばん悩んだ 「1枚のページに複数の名刺が並んでいたらどうするか」 という問題を共有します。

全体の流れ

ファイル（PDF / JPEG / PNG）をアップロード
サーバー側でバリデーション（形式・サイズ・ページ数）
「取り込み中」の履歴レコードをつくり、すぐにレスポンスを返す
重い処理（OCR → 構造化 → 登録/更新）はバックグラウンドジョブで実行
フロントは履歴IDをポーリングして進捗を表示

ポイントは 「受付」と「処理本体」をきっぱり分ける ことです。OCRや名寄せは数十秒〜数分かかることもあるので、リクエストの中で同期的に全部やろうとするとタイムアウトします。受付APIは「ファイルを保存して履歴をつくり、ジョブを起動するところまで」で潔く終わらせます。

OCRは“2段構え”

名刺の読み取りは、実は2つの異なる処理に分かれます。

文字を読む（OCR） … 画像から文字列を抽出する。ここは Google Cloud Vision のような汎用OCRの担当。
項目に振り分ける（構造化） … 抽出したテキストのうち「どれが会社名で、どれが氏名で、どれが電話番号か」を判定する。ここは自前の項目抽出モデルの担当。

名刺画像 → ①OCR(文字を全部読む) → テキスト → ②構造化(項目に仕分け) → { 会社名, 氏名, email... }

「OCR＝構造化まで全部やってくれる」と思いがちですが、①は文字と位置を出すだけ、②はそれを項目に整理するだけ。役割が別なのです。

設計で効いたポイント

バリデーションは“中身”で判定する。
「PDFかどうか」を拡張子やContent-Typeで見ると、画像を .pdf にリネームするだけで突破されてしまいます。ファイル先頭のマジックバイトで実体を判定するのが安全です。

大きいファイルはメモリに載せない。
名刺100枚分ともなるとファイルは大きくなります。ストレージ（S3等）へ送る際は全体をメモリに読み込まず、そのままストリームで流す。サイズチェックもメタデータだけ見て、中身は読みません。

PDFのページ数チェックは軽い読み取りで。
「◯ページまで」を受付時に弾きたいだけなら、画像化ライブラリ（ImageMagick等）は重すぎます。ページ数を数えるだけならレンダリング不要で、軽量なPDFパーサでメタデータを読めば十分です。

いちばん悩んだ問題：「1ページに複数名刺」

要件を詰める中で出てきたのが、1枚のスキャン画像（PDFの1ページ）に名刺が複数枚並んでいるケースです。コピー機やフラットベッドスキャナで数枚まとめて取り込めば、当然こうなります。

OCRは“名刺単位”には分けてくれない

ここが盲点でした。汎用OCR（Vision等）は「ページ内の全文字＋各文字の位置座標」は返してくれますが、「どの文字がどの名刺のものか」を論理的に分離する機能はありません（Google Cloud Vision の公式ドキュメントにも、1ページ上の複数文書を識別・分離する組み込み機能はなく、ブロックの位置を解析する独自ロジックが必要、と明記されています）。

さらに、OCRの「ブロック（文字の塊）」は レイアウト上の近接 でまとめられるため、隣り合う名刺が1つに融合したり、1枚の名刺が複数に割れたりします。「1ブロック＝1名刺」にはなりません。

構造化モデルも「名刺1枚分のテキスト」を仕分ける前提なので、複数名刺のテキストが混ざったまま渡すと、「A社の会社名＋B氏の氏名」が合体した誤ったデータが生まれてしまいます。

つまり「名刺ごとに切り分ける工程」を自前で挟む必要がある

OCR(全文字＋座標) → 【自前】名刺ごとに切り分け → 名刺A分 → 構造化
                                            → 名刺B分 → 構造化 → …

この切り分けの難易度は、名刺の並び方で大きく変わります。

並び方	アプローチ	難易度
固定テンプレート（常に2×3等）	ページを決め打ちで等分	低（ただし全ユーザーが同じ並べ方を強制される）
整然と並ぶが枚数可変	座標の“すき間”から行・列を動的に検出	中（ルールベース。傾き・密着・空きマスに弱い）
完全にバラバラ	名刺領域を検出するAIモデルを用意	高（モデルの学習・運用が必要）

真ん中の「座標から格子を推測する」方法は、こんなイメージのルールベース処理です。

すべての文字の座標を集める
X座標の大きなすき間を「列の境界」とみなす
Y座標の大きなすき間を「行の境界」とみなす
各マスを1名刺として、文字をグルーピングする

AIではなく幾何計算なので比較的軽い一方、傾き・名刺同士の密着・不揃いなサイズ・空きマスがあると崩れます。堅牢にするほど実データでのチューニングが必要になり、突き詰めると「AIで名刺そのものを検出する」方向に近づいていきます。

学び：仕様側で“制約”できると一気にラクになる

技術で無理にバラバラ配置へ対応するよりも、「名刺は等間隔に並べてスキャンしてください」といった入力の制約を設けるほうが、開発コストも精度リスクも大きく下がります。「どこまでの入力を許すか」はエンジニアだけで決めず、プロダクト側と早めにすり合わせるべき論点でした。

重複データの扱い（名寄せ）

一括登録では「すでに登録済みの取引先/担当者」との重複が避けられません。ここは

取引先は「会社名」または「会社名＋住所」で一致判定（支店を区別したいニーズもあるため住所も選べる）
担当者はメールアドレスで一致判定

を事前に選ばせ、ヒットしたものは更新、しなかったものは新規登録として扱います。「重複時に既存データを名刺の値で上書きするか」もユーザーが選べるようにしました（勝手に上書きされたくないニーズがあるため）。

まとめ

OCRは「文字を読む」＋「項目に仕分ける」の2段構え。OCRだけで構造化まで完結はしない。
受付と処理本体を分離し、重い処理は非同期ジョブへ。大容量ファイルはストリーム、バリデーションは中身で。
最大の落とし穴は 「1ページ複数名刺」。OCRは名刺単位に分けてくれないので切り分けは自前実装が必要で、並び方次第で難易度が激変する。
だからこそ 「入力をどこまで制約できるか」をプロダクトと握ることが、技術選定と同じくらい重要。

“OCRに投げるだけ”に見える機能ほど、実は要件と制約の設計が肝になる——という良い事例でした。

(後日談)

さんざん「1ページに複数名刺だったらどう切り分けるか…」と唸っていたのですが、プロダクト側に確認したら——

「PDFは1ページに名刺1枚の想定です」

……でした。盛大な取り越し苦労。笑

しかし勉強にはなりました。技術で殴る前に、まず要件を疑う。良い教訓になりましたわい。

DEV Community: Kaziu

エンティティ・値オブジェクト・サービス・UseCase をざっくり整理

一覧

エンティティ ─ ID で見分けるもの

値オブジェクト ─ 中身で見分けるもの

サービスオブジェクト ─ 手続きを入れる箱

サービス ＝ ビジネスロジック？

UseCase ─ ユーザーがやりたいこと1つ

4つの関係

もうActiveJob - Job,Que,Adaptorもレストランに例えますかーー

登場人物

なぜ「あとでやる」必要があるのか

ジョブ = 注文票

注文票には「料理」ではなく「テーブル番号」を書く

キュー = 注文票ボード

「注文のたびに料理人を雇えばいいのでは？」

アダプター = ボードの種類

:async ─ 店員が頭の中で覚えておく

:inline ─ レジ係がその場で作る

:test ─ 研修用のボード

:solid_queue / :sidekiq / :sqs など ─ 店の外にあるボード

本番で気をつけたいこと

1. 同じ注文票が 2 枚届くことがある

2. 会計が確定する前に注文票を貼らない

レストランで理解する Rack・プロセス・スレッド・Unicorn・Puma・Action Cable

1. Rack：注文票の共通フォーマット

2. 層：ホール → 受付 → 厨房

3. プロセスとスレッド：店舗と店員

4. ブロッキング：テーブルの横で立ち尽くす店員

5. Unicorn：店員1人の店舗をたくさん出す

6. Puma：1店舗に店員をたくさん置く

7. Action Cable：呼び出しベルで見回るホール係

まとめ

ngrok で「手元のサーバー」を一時的に公開して Webhook の送信をテスト

はじめに

ngrok とは

使い方

1. 仮の受け口を作る

2. ngrok で公開する

3. 送信側に URL を設定して動かす

注意点

まとめ

「先頭カラムが同じインデックス、それ1つ無駄ちゃう？」— 冗長インデックスの見つけ方と消し方

なぜ「単独 (import_id)」が冗長なのか

冗長インデックスは「あって困る」

どうやって機械的に見つけるか

1. MySQL 標準ビュー sys.schema_redundant_indexes（おすすめ・導入不要）

2. pt-duplicate-key-checker（Percona Toolkit / CLI）

3. sys.schema_unused_indexes（未使用インデックスの検出）

4. ORM 付属のツール（例：Rails の active_record_doctor）

【重要】消してはいけない冗長候補：外部キー（FK）の索引

安全な消し方

マイグレーション

適用前に「本当に消せるか」を実地で裏取り

Railsのstructure.sqlって何？ 何のため?

結論：DBの「完成形の設計図」

前提知識：マイグレーションとの関係

何のためにあるの？

なぜマイグレーション全実行は遅いのか

たとえ話

だから2つを使い分ける

補足：schema.rb と structure.sql

まとめ

SQL複数カラムの計算結果をインデックスにまとめる設計手法と、書き込みオーバーヘッドの限界

1. 複数カラムの計算結果をインデックスにまとめる2つの手法

アプローチA：式インデックス（Expression Index）を直接貼る

SQL (PostgreSQL)

Rails migration

アプローチB：生成列（Generated Column） ＋ 複合インデックス【おすすめ】

Rails (Migration)

2. 書き込み（INSERT / UPDATE）オーバーヘッドのレベル感

どのくらいの「データ量」で影響が大きくなる？

特に遅くなりやすい「ワーストケース」のパターン

Rails の `dependent: :destroy` が激重になる話を簡単な例で

何が起きるか

対策：重い子だけ「コールバック無し」で先に消す

ポイント3つ

用語メモ

SQLの自己結合（self-join）を一番簡単な例で

例：社員テーブル（社員も上司も“社員”）

サービス＝ビジネスロジック？

`:async` ─ 店員が頭の中で覚えておく

`:inline` ─ レジ係がその場で作る

`:test` ─ 研修用のボード

`:solid_queue` / `:sidekiq` / `:sqs` など ─ 店の外にあるボード

なぜ「単独 `(import_id)`」が冗長なのか

1. MySQL 標準ビュー `sys.schema_redundant_indexes`（おすすめ・導入不要）

2. `pt-duplicate-key-checker`（Percona Toolkit / CLI）

3. `sys.schema_unused_indexes`（未使用インデックスの検出）

4. ORM 付属のツール（例：Rails の `active_record_doctor`）

Railsのstructure.sqlって何？何のため?

アプローチB：生成列（Generated Column）＋複合インデックス【おすすめ】

「Blob」って何？ブラウザでファイルをダウンロードする仕組み