PDF生成を自前実装すると、なぜ6か月後に負債になるのか

「PDF生成を自前実装すると、なぜ6か月後に負債になるのか」のカバー画像

「この画面をPDFで出せるようにしてください」

要件だけを見ると、小さな追加機能に見えます。

HTMLを作り、ヘッドレスブラウザでPDF化する。あるいはPDFライブラリで文字と罫線を配置する。最初の1種類を出力するだけなら、短期間で実装できることもあります。

問題は、その機能が半年後にも同じ規模であることはほとんどない点です。

なぜ最初に増えるのは、帳票の種類ではなく例外なのか

顧客名が長い。住所が2行になる。備考欄だけ文字数が多い。明細が1ページに収まらない。印影を追加したい。会社ごとにロゴを変えたい。税率ごとに集計したい。過去の版を再発行したい。

PDF生成の保守コストは、帳票数よりも例外の組み合わせで増えます。

しかも、画面上で正しく見えることと、PDFで正しく印刷されることは同じではありません。

自前実装で後から発生する7つの負債

  1. 日本語フォント
  2. 改ページ
  3. プレビュー差異
  4. デザイン変更
  5. 同期処理の限界
  6. バージョン管理
  7. 視覚的な品質保証

作るべきなのはPDFコードではなく、境界

帳票機能を安定させるには、次の3つを分離します。

  1. 業務データ
  2. 帳票テンプレート
  3. PDF生成処理

アプリケーションは、どのテンプレートへどのデータを渡すかだけを決める。デザイン変更はテンプレート側で行う。生成処理はAPIへ任せる。

この境界を作ることで、帳票の変更がアプリケーションの変更にならなくなります。

自前実装とPDF生成APIの選び方

判断材料は帳票の数ではなく、例外と変更の量です。次の条件がそろっているうちは、自前実装でも保守が破綻しにくい領域です。

  • 帳票が1種類で、今後もほぼ変わらない
  • レイアウトが非常に単純
  • 出力件数が少ない
  • 専任の保守担当がいる
  • データを外部サービスへ送れない明確な制約がある
  • PDFレンダリング自体が競争力である

逆に、複数帳票、可変明細、日本語、顧客別デザイン、業務担当による変更、大量生成のいずれかがあるなら、生成基盤を切り出す価値が高くなります。

「一度作れば終わる機能」ではない

帳票生成は、完成後に最も変更要求が届きやすい機能の一つです。

法令、会社情報、ロゴ、振込先、注記、顧客要望、社内ルール。外部要因で書式が変わります。

比較すべきなのは、半年後、1年後に発生する変更・障害・テスト・運用を含む総コストです。

Re:port Flowは、ブラウザで作成したテンプレートへJSONデータを送り、同期・非同期・一括でPDFを生成できます。月30ファイルまで無料でAPIを試せます。

APIドキュメント: https://go.re-port-flow.com/rf30-09

よくある質問

PDF生成の自前実装とPDF生成APIの違いは何ですか？

自前実装では、日本語フォントの埋め込み、改ページ、非同期処理、テンプレートの版管理まで自分たちで保守します。PDF生成APIはその生成基盤を外部に預け、アプリケーション側は「どのテンプレートへどのデータを渡すか」だけを持ちます。分かれ目は帳票の数ではなく、例外と変更がどれだけ発生するかです。

PDF生成で日本語が文字化けするのはなぜですか？

生成環境に必要な日本語フォントが無く、代替フォントに置き換わることが主な原因です（いわゆる豆腐化）。画面表示はブラウザ側のフォントで成立するため開発中は気づきにくく、印刷や別環境での生成で表面化します。フォントを埋め込む場合は、ファイルサイズの肥大化と禁則処理の扱いもあわせて決める必要があります。

帳票のレイアウト変更を開発者以外が行う方法はありますか？

帳票テンプレートを業務データと生成処理から分離し、テンプレート側だけを編集できる形にすれば可能です。ロゴの差し替えや注記の追加にコード修正とデプロイが不要になり、帳票の変更が開発チームの作業待ちになりません。レイアウトがコードに直接書かれた実装では、どんな小さな変更でも開発工数が発生します。

大量のPDF生成でタイムアウトする場合はどうすればよいですか？

リクエスト内で同期生成する方式は、件数が増えると応答時間に収まらなくなります。キューとワーカーで非同期に生成し、完了後にダウンロードさせる構成へ切り替えるのが基本で、リトライと失敗通知もあわせて必要になります。この非同期基盤を自前で持つか、生成APIの非同期・一括モードに任せるかが判断の分かれ目です。