2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@raiton-boo(らいと)

FastAPIを使って、LINEBOTのテンプレートを作ってみた

Posted at

はじめに

LINE Bot 開発をもっと効率化したいと思い、実用的な Python テンプレートを作成しました。
単純なオウム返し Bot から一歩進んで、モジュール設計、エラー分析機能、パフォーマンス監視を備えた、実際の開発で使えるテンプレートです。

リポジトリ: https://github.com/raiton-boo/linebot-template-python

何を作ったのか

🎯 コンセプト

「LINE Bot 開発で毎回同じことを書くのが面倒」という課題を解決するため、以下を重視したテンプレートを作成：

  • すぐ使える: clone してすぐに動作する
  • 拡張しやすい: 機能追加が簡単な設計
  • 本番対応: エラーハンドリングとログ管理が充実
  • 学習しやすい: 豊富なドキュメントと実例

🛠 技術構成

FastAPI (Webフレームワーク)
├── LINE SDK v3 (最新版対応)
├── linebot-error-analyzer (エラー分析ライブラリ)
├── asyncio (非同期処理)
└── Uvicorn (ASGI サーバー)

📂 アーキテクチャ

app.py (メインアプリケーション)
├── BaseEventHandler (基底ハンドラクラス)
├── MessageEventHandler (メッセージ処理)
├── FollowEventHandler (友だち追加処理)
├── UnfollowEventHandler (ブロック処理)
└── その他各種イベントハンドラ

開発のポイントと工夫

1. 🧩 モジュール設計の採用

課題: 一般的な LINE Bot サンプルは一つのファイルにすべてを書くため、機能が増えると管理困難

解決策: イベントタイプごとにハンドラクラスを分離

# handlers/base_handler.py
class BaseEventHandler(ABC):
    def __init__(self, line_bot_api: AsyncMessagingApi):
        self.line_bot_api = line_bot_api
        self.logger = logging.getLogger(self.__class__.__name__)

    @abstractmethod
    async def handle(self, event) -> None:
        pass

# handlers/message_handler.py
class MessageEventHandler(BaseEventHandler):
    async def handle(self, event: MessageEvent) -> None:
        # メッセージ処理のロジック

メリット:

  • 新しいイベント処理を追加する際は新しいハンドラクラスを作るだけ
  • 各ハンドラが独立してテストしやすい
  • 責任が明確で保守性が高い

2. 📊 エラー分析機能の統合

課題: LINE API のエラーレスポンスは開発者向けで、ユーザーに分かりやすいメッセージを返すのが困難

解決策: 自作の linebot-error-analyzer ライブラリを活用

from linebot_error_analyzer import AsyncLineErrorAnalyzer, ApiPattern

async def _analyze_and_get_profile_error_message(self, error: Exception) -> str:
    try:
        analyzer = AsyncLineErrorAnalyzer()
        analysis_result = await analyzer.analyze(error, ApiPattern.USER_PROFILE)

        # ステータスコードに応じてユーザーフレンドリーなメッセージを返す
        if analysis_result.status_code == 400:
            return "無効なユーザーIDが指定されています。"
        elif analysis_result.status_code == 404:
            return "友だち追加してね！\nブロックしている場合は解除してください"
    except Exception as analyzer_error:
        self.logger.error(f"Analyzer error: {analyzer_error}")

    return "申し訳ございません。しばらく時間をおいてから再度お試しください"

効果:

  • API エラーを自動で分析してユーザーに適切なメッセージを表示
  • 開発者には詳細なログ、ユーザーには分かりやすいメッセージ
  • エラーの種類に応じた適切な対処法を提示

3. ⚡ パフォーマンス監視の実装

課題: 本番環境で Bot のパフォーマンス問題を早期発見したい

解決策: 軽量な監視機能を組み込み

async def handle_callback(request: Request):
    start_time = time.time()
    # ... イベント処理 ...

    processing_time = time.time() - start_time

    # 5件以上のイベントや1秒以上の処理時間で警告ログ
    if event_count > 5:
        logger.info(f"大量イベント処理: {event_count}件")
    if processing_time > 1.0:
        logger.warning(f"処理時間超過: {processing_time:.2f}秒")

メリット:

  • 処理時間やイベント数を監視して異常を早期発見
  • 軽量で本番環境のパフォーマンスに影響しない
  • ログレベルで詳細度を調整可能

4. 🔧 開発環境の整備

課題: ローカル開発で Webhook のテストが面倒

解決策: ngrok を使った詳細なセットアップ手順を用意

# ターミナル1: アプリケーション起動
python -m uvicorn app:app --reload --host 0.0.0.0 --port 8000

# ターミナル2: ngrok でトンネル作成
ngrok http 8000

文書化のポイント:

  • インストールから認証設定まで全手順を記載
  • 無料版の制限事項と対処法も明記
  • トラブルシューティングも充実

開発で苦労した部分

1. 🤔 エラーハンドリングの設計

問題: エラーログが多すぎると本当に重要な問題が埋もれる

最初の実装では全ての例外で詳細なスタックトレースを出力していましたが、これが裏目に：

# ❌ 初期実装（ログが多すぎる）
except Exception as e:
    self.logger.exception(f"エラーが発生しました: {e}")  # 毎回スタックトレース
    # ... エラー分析処理 ...

改善策: ログレベルを使い分けて情報の重要度を整理

# ✅ 改善後（必要な情報のみ）
except Exception as e:
    # ユーザー向けには最小限のログ
    self.logger.error(f"プロフィール取得失敗[{user_id}]: {type(e).__name__}")

    # 重要なエラーのみ詳細分析
    if any(keyword in str(e).lower() for keyword in ['rate', 'limit', 'timeout']):
        analysis_result = await analyzer.analyze(e)
        self.logger.warning(f"重要エラー: {analysis_result.recommended_action}")

2. 📚 ドキュメント構成の試行錯誤

問題: 全てを README に書くと長大になりすぎて読みづらい

最初は一つの README にすべてを詰め込みましたが、情報量が多すぎて逆に使いづらくなってしまいました。

解決策: 用途別にドキュメントを分離

README.md (概要とクイックスタート)
docs/
├── setup.md (詳細なセットアップ手順)
├── deployment.md (本番環境構築)
└── custom-handlers.md (カスタマイズ方法)

ポイント:

  • README は「5 分で概要を掴める」内容に限定
  • 詳細手順は別ファイルに分離して可読性を保つ
  • 実際の開発フローに沿った文書構成

3. 🎯 Python バージョン対応の悩み

問題: 最新機能を使いたいが、幅広い環境で使えるようにもしたい

最初は Python 3.12 の最新機能を使って実装しましたが、「テンプレートなら幅広い環境で使えるべき」と考え直し。

決断: Python 3.9+ で動作するように調整

理由:

  • 3.9 は多くの環境でサポートされている
  • async/await の安定性も十分
  • テンプレートとしての利用しやすさを優先

実装して良かった機能

1. 🔍 プロフィール取得機能

実装は簡単ですが、エラーハンドリングが非常に勉強になりました：

# プロフィール取得処理
try:
    profile = await self.line_bot_api.get_profile(user_id)
    profile_text = f"""
👤 プロフィール情報
名前: {profile.display_name}
ID: {profile.user_id}
画像: {profile.picture_url or "未設定"}
ステータス: {profile.status_message or "未設定"}
"""
except Exception as e:
    # エラー分析してユーザーに適切なメッセージを返す
    error_message = await self._analyze_and_get_profile_error_message(e)
    await self._send_reply(event.reply_token, error_message)

LINE API の GET /profile は、友だち関係にないユーザーには 404 を返します。
これを「友だち追加してね！」というメッセージに変換することで、UX が大幅に向上しました。

2. 📈 軽量な統計情報

# イベント処理の統計を軽量に記録
success_count = sum(1 for result in results if not isinstance(result, Exception))
error_count = len(results) - success_count

if error_count > 0:
    logger.warning(f"処理結果: 成功{success_count}件, エラー{error_count}件")

本格的なメトリクス収集は重いですが、この程度なら軽量でかつ有用な情報が得られます。

まとめ

🎉 完成したもの

  • すぐに使える LINE Bot のテンプレート
  • 実際の開発で使える設計パターン
  • ドキュメントとセットアップ手順
  • エラー分析と軽量なパフォーマンス監視機能

💡 学んだこと

  1. モジュール設計の重要性: 最初から整理された構造にすることで、後の拡張が劇的に楽になる
  2. エラーハンドリングの奥深さ: ログの量と質のバランスが重要
  3. ドキュメントの価値: 良いドキュメントは開発効率を大幅に向上させる
  4. ユーザー体験の重要性: 技術的に正しいだけでなく、使いやすさも同じく重要

🚀 今後の展開

  • より多くの LINE API 機能の対応
  • CI/CD パイプラインの追加
  • Docker 対応
  • テストカバレッジの向上

おわりに

LINE Bot 開発で毎回同じことを書くのが面倒だったので作ったテンプレートですが、
作っている過程でモジュール設計やエラーハンドリングなど、多くのことを学べました。

特に linebot-error-analyzer との組み合わせは、開発効率とユーザー体験の両方を向上させる良いアプローチだと感じています。

もし LINE Bot 開発をしている方がいれば、ぜひ使ってみてフィードバックをもらえると嬉しいです！

2
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?