便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

Rust で Telegram ボットを作る：carapax フレームワーク完全ガイド

タグ RustTelegram BotcarapaxTokio非同期処理型安全ボット開発columnコラムlinuxLinuxwindowsWindowsGitHubオープンソースtg-rs
📦 GitHubで見る

Rust で Telegram ボットを作る：carapax フレームワーク完全ガイド

ひとことでいうと

carapax（カラパクス）は、**Rust というプログラミング言語で Telegram ボットを作るためのフレームワーク（開発の土台となるツール集）**です。メッセージの受け取り方や返し方、複数の機能を組み合わせる仕組みなど、ボット開発に必要なパーツがひとまとまりになっています。Rust の得意とする「速さ」「省メモリ」「型安全」を活かしながら、実用的なボットをすっきりと書けるのが特長です。最新バージョンは 0.38.0 で、0.x 系を意図的に維持する ZeroVer というポリシーに従ってリリースされています。名前はラテン語で「甲羅（carapace）」を意味し、ボットの核心部分を守るシェルというコンセプトが込められています。

こんな人におすすめ

1. Rust でパフォーマンス重視のボットを作りたい開発者

非同期 I/O ライブラリの Tokio をベースにしているため、多数のメッセージを同時に処理しても軽快に動きます。VPS（仮想専用サーバー）のような限られたリソース環境でも省メモリで動作するのが魅力です。

2. 型安全性を重視するバックエンドエンジニア

Rust の強力な型システムにより、「この変数に想定外の値が入る」というミスをコンパイル時（プログラムを実行する前の変換ステップ）に防げます。メッセージの種別ごとにハンドラー（処理担当の関数）の正しさをあらかじめ確認できるため、実行時エラーを大幅に減らせます。

3. 既存の Python や Node.js ボットを置き換えたいチーム

Rust はコンパイル後にスタンドアロン（単独で動く）バイナリを生成できるため、Docker イメージを小さく保てます。メモリ使用量が少なく、本番環境でのコスト削減にも直結します。

インストール・使い方

ターミナル（文字で命令を送る画面）を開いて、以下のステップを順番に実行してください。コマンドはそのままコピー＆ペーストして使えます。

Step 1: Rust ツールチェインの準備

Rust がまだ入っていない場合は rustup（ラストアップ）という公式インストーラーを使います。

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustc --version   # rustc 1.7x.x 以上が表示されれば OK

インストールスクリプトをダウンロードして自動的に Rust 環境をセットアップします。完了後、ターミナルを再起動するか source ~/.cargo/env を実行すると rustc コマンドが使えるようになります。

Step 2: 新規プロジェクトの作成と依存の追加

cargo（カーゴ）は Rust の標準パッケージ管理ツールで、プロジェクトの作成から依存ライブラリの管理まで担います。

cargo new my-telegram-bot
cd my-telegram-bot

次に、プロジェクトの設定ファイル Cargo.toml を開き、[dependencies] のセクションに以下を追記します。

[dependencies]
carapax = "0.38.0"
tokio = { version = "1", features = ["full"] }

これで carapax 本体と、非同期処理エンジンの Tokio が依存として追加されます。

Step 3: 環境変数の設定

ボットを動かすには Telegram の「BotFather」から取得した認証トークン（API キー）が必要です。リポジトリには sample.env というサンプルファイルが含まれているので、それをコピーして編集します。

cp sample.env .env
# .env をテキストエディタで開いて以下の行を書き換える
# CARAPAX_TOKEN=ここに BotFather から取得したトークンを貼り付ける

環境変数（プログラムが参照する設定値）として渡すことで、トークンをソースコードに直書きせずに済みます。ソースコードに直書きするとセキュリティ上のリスクになるため、この方法を使ってください。

Step 4: エコーボットの実装

examples/echo.rs を参考に、受信したメッセージをそのまま返す最もシンプルなボットを書けます。

use carapax::prelude::*;

#[tokio::main]
async fn main() {
    let token = std::env::var("CARAPAX_TOKEN").expect("CARAPAX_TOKEN が未設定");
    let api = Api::new(token).unwrap();
    let mut dispatcher = Dispatcher::new(api.clone());
    dispatcher.add_handler(echo_handler);
    LongPoll::new(api, dispatcher).run().await;
}

async fn echo_handler(context: Arc<Context>, update: Arc<Update>) -> HandlerResult {
    if let Some(message) = update.get_message() {
        if let Some(text) = message.get_text() {
            let chat_id = message.get_chat_id();
            context.api.execute(SendMessage::new(chat_id, text.data.clone())).await?;
        }
    }
    Ok(HandlerResult::Continue)
}

Dispatcher がメッセージを振り分け、echo_handler 関数がテキストを受け取って同じ内容を返送します。Ok(HandlerResult::Continue) は「次のハンドラーへ処理を渡す」という意味です。

Step 5: ビルドと実行

cargo run --example echo

cargo run でコンパイル（機械語への変換）と実行を同時に行います。初回はライブラリのダウンロードとコンパイルがあるため数分かかることがあります。起動後、Telegram でボットにメッセージを送ると、同じ内容がそのまま返ってきます。

動かしてみた

リポジトリをクローン（ダウンロード）すると、Rust の標準的なクレート（ライブラリ）レイアウトに沿ったファイル構成が確認できます。

./Cargo.toml         # プロジェクト設定と依存関係
./src/lib.rs         # ライブラリ本体
./examples/echo.rs   # エコーボットのサンプル
./tests/versions.rs  # クレートバージョン一貫性チェック
./sample.env         # 環境変数のサンプル

src/ にライブラリ本体、examples/ にすぐ動かせるサンプル、tests/ に統合テストが置かれています。Rust エコシステムに慣れた人なら迷わずコードを読み進められる、見通しのよい構成です。tests/versions.rs はクレートのバージョンが一致しているかを自動確認するテストで、CI（継続的インテグレーション＝コードをプッシュするたびに自動でテストが走る仕組み）は GitHub Actions で管理されています。codecov によるカバレッジ（テストがコードのどの割合を網羅しているか）の測定もバッジで確認でき、品質管理への取り組みが感じられます。

デモについて

carapax は Telegram Bot API へのリアルタイム接続が前提のフレームワークです。そのため、CARAPAX_TOKEN（BotFather で発行する認証トークン）がなければボットを起動できず、ブラウザ上でのインタラクティブデモの自動提供は構造上難しい状況です。実際に試す場合は、Telegram の公式ボット「BotFather」で新しいボットを作成してトークンを取得し、sample.env に設定した上で cargo run --example echo を実行してみてください。

実践のコツ・はじめの一歩

  • sample.env を必ずコピーしてから使う — CARAPAX_TOKEN 以外にも変数が定義されている場合があります。上書きせずコピーして、中身を確認してから編集してください。
  • HandlerResult の使い分けを覚える — Continue を返すと後続のハンドラーへ処理が渡り、Stop で打ち切ります。複数のハンドラーを登録するときの優先順位設計に直結します。
  • #[tokio::main] マクロを忘れない — Rust の async fn main は、Tokio の #[tokio::main] マクロがないとコンパイルエラーになります。Cargo.toml で tokio に features = ["full"] を指定しておくと安心です。
  • ドキュメントは docs.rs で読める — docs.rs/carapax に API リファレンスが公開されています。マスターブランチの最新ドキュメントは tg-rs.github.io でも確認できます。
  • まずエコーボットを動かすことを最初のゴールに — 凝った機能は後から足せます。最初は examples/echo.rs をそのまま動かして、Telegram とのやり取りが成立することを確認するのが近道です。

活用例

  • 社内 CI/CD 通知ボット — ビルドやデプロイの結果を Telegram グループに自動送信します。Rust 製なので省メモリで常駐でき、VPS の小さなインスタンスでもコストを抑えて運用できます。
  • スラッシュコマンド対応のコマンドボット — /status や /deploy など複数のコマンドを carapax のハンドラー登録機能でルーティングします。権限チェックのミドルウェアと組み合わせれば、管理者だけが実行できるコマンドも簡単に実装できます。
  • ファイル受信・変換パイプライン — Telegram はファイルの送受信 API を持っているため、ユーザーから画像や CSV を受け取り、Rust の高速処理で変換して返すボットとして活用できます。
  • 学習用コードレビューボット — チームの勉強会でコードスニペットをボットに送ると、外部 API と連携して解析結果を返す、という学習支援ツールとして使えます。
  • サーバー監視アラートゲートウェイ — 監視ツールと連携し、ディスク使用率やメモリ超過などのアラートを Telegram に転送するゲートウェイとして運用できます。Rust のバイナリは起動が速く、ダウン後の素早い復旧にも有利です。
  • 個人用タスク管理ボット — Telegram をフロントエンド（操作画面）として、テキストメッセージでタスクの追加・完了・一覧表示を操作する個人ツールとして活用できます。ローカルで動かすだけでクラウドサービスに頼らない運用が可能です。

用語とポイント解説

carapax（カラパクス） Rust 製の Telegram Bot フレームワークです。かんたんに言うと、ボットに必要な機能を詰め合わせた「開発キット」です。低レベルな API の細かい通信処理を代わりにやってくれるため、ボットのロジック（処理の流れ）に集中して開発できます。

tgbot（ティージーボット） carapax が内部で依存している低レベルの Telegram API クライアントです。かんたんに言うと、Telegram のサーバーと実際に通信する「窓口」にあたるライブラリです。carapax はこの上に、より使いやすい高レベルな仕組みを追加したものです。

Dispatcher（ディスパッチャー） Telegram から届いた Update（更新情報）を適切なハンドラーに振り分けるルーターです。かんたんに言うと、「このメッセージはこの担当者へ」と仕分けする「受付係」です。ハンドラーを複数登録することで、メッセージの種類や内容によって処理を分岐させられます。

HandlerResult（ハンドラーリザルト） ハンドラー関数が返す列挙型（決まった選択肢のある型）で、Continue（次のハンドラーへ渡す）と Stop（ここで処理を終える）の 2 種類があります。かんたんに言うと、「次の担当者に回すか、ここで終わりにするか」を決めるスイッチです。複数ハンドラーの優先順位設計に直結します。

LongPoll（ロングポール） Telegram のロングポーリング方式を管理する構造体です。かんたんに言うと、「新しいメッセージが来ていないか、定期的に Telegram のサーバーへ問い合わせる」仕組みを担当するパーツです。Webhook（ウェブフック）と異なり、サーバーが公開 URL を持たなくても動かせます。

ZeroVer（ゼロバー） 0.x 系バージョンを意図的に維持するバージョニングポリシーです。かんたんに言うと、「まだ API が変わる可能性があるので 1.0 にはしない」という開発姿勢の表明です。0.38.0 のように細かくリリースしながら機能を追加・改善していく方針です。

CARAPAX_TOKEN（カラパクストークン） Telegram 公式の「BotFather」から発行される認証トークン（パスワードに相当する文字列）です。かんたんに言うと、「このボットが本物であることを証明する合言葉」です。.env ファイルに記載して環境変数として読み込み、ソースコードへの直書きは避けてください。

Tokio（トキオ） Rust の非同期処理ランタイム（実行基盤）です。かんたんに言うと、「複数の処理を同時並行でこなすための土台エンジン」です。carapax はこれを使って多数のメッセージを効率よく処理します。#[tokio::main] マクロを付けることで async fn main が動くようになります。

クレート（crate） Rust のライブラリ・パッケージの単位です。かんたんに言うと、「他の人が作った便利な部品」のことで、Cargo.toml に名前とバージョンを書くだけで利用できます。carapax も tgbot も、それぞれひとつのクレートとして配布されています。

ぜひ社内の CI/CD 通知ボットや個人用タスク管理ツールなどに活用してみてはいかがでしょうか。