go-notifier

README

🔔 Go Notifier

🚀 概要 (About) - 指数バックオフ・堅牢通信対応のマルチチャネル通知ツールキット

Go Notifier は、複数のチャネル（Slack, Backlog）に対して堅牢（Robust）にメッセージを投稿・通知するための Go 言語製 CLI アプリケーションです。通信の信頼性を最優先し、ビジネスロジックとインフラストラクチャ層を明確に分離した設計を採用しています。

主要な機能と特徴:

• 堅牢な通信基盤:
  • go-http-kit をコアに採用。全ての外部通信において、指数バックオフ（Exponential Backoff）によるインテリジェントなリトライ処理を備えた HTTP クライアントを共有します。
• 徹底した関心事の分離:
  • HTTP 通信、リトライロジック、タイムアウト制御を httpkit.Client に完全集約。パッケージ側のロジックは通信の不安定さを意識せず、純粋なビジネスルールに集中できます。
• 高度な表現力 (Slack Block Kit):
  • Slack への通知は Block Kit 形式をフルサポート。Markdown 形式のテキストを Slack 専用のフォーマットへ自動変換し、視認性の高い通知を実現します。
• クリーンなテキスト処理 (Emoji Sanitization):
  • Backlog 投稿時、go-utils/text を使用して不要な絵文字や不正な文字をサニタイズ。システム間の互換性を保ち、クリーンなログを維持します。
• 柔軟なコマンド設計:
  • メッセージ本文 (-m)、カスタムタイトル (-t)、グローバルな HTTP タイムアウト設定 (--timeout) など、Cobra ベースの強力なフラグ管理により柔軟な操作が可能です。
• インテリジェントな Backlog 連携:
  • 新規課題登録 (backlog create): 課題種別IDや優先度IDを動的に取得。デフォルトで「タスク」や「中」を自動適用するスマートな初期値設定。
  • 既存課題へのコメント (backlog comment): 既存のワークフローを止めない迅速な追記機能。
  • 課題一覧取得 (backlog list): 内部的なページネーション処理により、大規模なプロジェクトでも確実に課題をリストアップ。
  • 課題詳細取得 (backlog get): 課題キーまたはIDを指定して、単一課題の詳細を取得。

---

🚀 セットアップと実行

1. ビルド

プロジェクトルートで以下のコマンドを実行し、実行ファイル bin/notifier を生成します。

go build -o bin/notifier

🛠 共通フラグ (Persistent Flags)

slack や backlog などの各サブコマンドで共通して使用できるフラグです。

フラグ名	ショートカット	役割	スコープ
--title	-t	投稿タイトル / 課題サマリーとして使用。	グローバル
--message	-m	投稿メッセージ / 課題詳細として使用。	グローバル
--timeout	(なし)	HTTPリクエストのタイムアウト時間（秒）。	グローバル

---

⚙️ 環境変数設定 (Environment Variables)

コマンドライン引数（フラグ）ではなく、環境変数によって制御される設定項目です。Slack 設定と Backlog 接続設定は builder パッケージによって実行時に読み込まれます。

Slack 設定

変数名	役割	デフォルト値
SLACK_WEBHOOK_URL	(必須) 投稿先の Webhook URL。	(なし)
SLACK_USERNAME	投稿時の表示ユーザー名。	Bot
SLACK_ICON_EMOJI	投稿時のアイコン絵文字。	:robot_face:
SLACK_CHANNEL	投稿先のチャンネル（Webhookの設定を上書きする場合）。	(なし)

Backlog 設定

変数名	役割	デフォルト値
BACKLOG_SPACE_URL	(必須) スペースのベースURL。	(なし)
BACKLOG_API_KEY	(必須) APIアクセス用キー。	(なし)
BACKLOG_PROJECT_ID	対象のプロジェクトキーまたはID。	(なし)

---

🔹 Slack への投稿

SLACK_USERNAME="MonitorBot" SLACK_CHANNEL="#alerts" \
  ./bin/notifier slack -t "システムアラート" -m "**致命的なエラー**が発生しました。"

🔹 Backlog への課題登録

./bin/notifier backlog create -p "MYPROJ" -t "サーバー負荷増大" -m "速やかに調査が必要です。"

🔹 Backlog の課題詳細取得

./bin/notifier backlog get --key "MYPROJ-123"

📐 プロジェクト構成

Cobra CLI によるコマンドインターフェースと、internal/builder による依存性注入（DI）を軸とした、責務分離の明確な構成です。

go-notifier/
├── cmd/                 # CLIコマンド定義 (Cobra)
│   ├── root.go          # 基盤: グローバルフラグ、shared httpkit.Client の初期化
│   ├── slack.go         # slack: Webhookによる通知送信
│   ├── backlog.go       # backlog: 親コマンド
│   ├── backlog_read.go  # backlog list: 課題参照
│   └── backlog_write.go # backlog create/comment: 課題操作
├── internal/            # 内部ロジック
│   └── builder/         # Clients Builder: 共通Clientを注入し各サービスを構築
├── pkg/                 # コアロジック (外部公開可能なライブラリ)
│   ├── backlog/         # Backlog API 実装 (client.go, issues_read.go 等)
│   └── slack/           # Slack 実装 (blocks.go, client.go 等)
└── main.go              # エントリーポイント

---

🛠 コンポーネントの役割詳細

1. CLI コマンド (cmd/)

ユーザーの入力を解析し、適切なサービスを呼び出す「指揮官」の役割です。

• 依存性の注入: root.go で共通の httpkit.Client を作成し、それを internal/builder に渡して各コマンドが必要なインスタンスを取得します。
• 設定の集約: 環境変数やフラグから API キーなどの設定値を読み込み、クライアント生成時に流し込みます。

2. クライアントビルダー (internal/builder/)

プロジェクト内部で、複雑なインスタンス生成ロジックを隠蔽する「組み立てライン」です。

• 共通基盤の活用: pkg 側の各クライアントに対し、共通設定済みの httpkit.Requester を一貫して注入し、接続の最適化（リトライ等）を保証します。
• カプセル化: 外部（cmd）に対しては、構築済みのインターフェースや構造体を返すだけで、詳細な生成手順を見せません。

3. サービス実装 (pkg/backlog/, pkg/slack/)

外部 API とのやり取りに特化した「専門家」の役割です。

• slack: blocks.go で Block Kit の構築、client.go で Webhook 送信を担当。
• backlog: issues_read.go や issues_write.go など、機能ごとにファイルを分割し、Backlog API のエンドポイント操作を網羅します。

---

🔄 実行時の流れ（現在の実態）

1. cmd/root.go が、リトライ機能付きの httpkit.Client を生成。
2. コマンド（例: slack.go）内で internal/builder を呼び出し、共通クライアントをベースにした slack.Client をビルド。
3. pkg/slack 内のロジックが動き、実際の通知が送信される。

---

📜 ライセンス (License)

このプロジェクトは MIT License の下で公開されています。

---

Documentation

Overview

main.go (プロジェクトルート)