Engineer Blog

Kazuki Katsurada

masashi kobayashi

lapla

Takehiko Okayama

Kotaro Ito

Yuhei Yasuda

naoyashiga

Takumi Ishii

Sojiro Nishimura

Katsumi Kobayashi

Kota Momoki

Calloc

Shohei Shiraki

Takaaki Kanetsuki

Yui Taniyama

Kota Yatagai

Shuhei Kondo

kenshin tanaka

KARTE Team

Security Team

Tomoya Koike

Haruki Tosa

Daiki Sakuma

Takuma Shibuya

plaidinc

Takami Yamada

Blocks Team

Takanori Koga

Takumi Katayama

Yu Nishimura

Takuya Ogawa

akira.kasuga

Kosuke Oya

Yoshiyuki Komazaki

mizchi

Ryosuke Suzuki

koichi tanaka

Arnaud Avondet

kazupon

daigo.isamatsu

Jun Kusahana

Shinnosuke Ozawa

Rei Ishikawa

Hiroto Harada

Kei Tamiya

Nobuhiro Ito

kazushi oohira

Yohei Meguro

Kazuto Kojima

Tomoki Koga

Kenichi Suzuki

Takaaki Nakama

Takahiro Tokunaga

Kohei Kadowaki

kantetsu

Makoto Kataigi

Tatsuya Monoi

Jumpei Ikegami

Masahiro Yamauchi

Shinji Eto

Yuta Nishimura

Hideyuki Okada

Wataru Ikarashi

Naoto Kato

Yuki Makino

Atsushi Fujikawa

Naohiko Takemura

Daikichi Sasamori

Atsushi Kobayashi

Naoki Shibayama

Daiki Matsui

Yohei Noda

Developer Experience & Performance チームでエンジニアをしている大矢です。今回は JavaScript の非同期処理で使われている callback を Promise に移行する手法について、具体的な事例をもとに紹介します。

Mongoose の callback を Promise に移行する手法

KARTEの複数のシステム間で共有する定数ファイルを、これまで社内向けのnpmパッケージとして配布していたところから、代わりとなる独自の仕組みを構築して管理する方式に切り替えたことと、その移行プロセスについて。

npmパッケージの代わりに独自の仕組みを構築して定数ファイルを配布する運用に切り替えた経緯と移行プロセス

<h1>はじめに</h1>
<p>こんにちは、桂田一輝と申します。2024年8月から10月の3ヶ月間、プレイドのEcosystemチームでソフトウェアエンジニアとしてインターンシップを行いました。インターンを通じて、Ecosystemチームが開発しているKARTE Craftというプロダクトの改善業務に携わってきました。そこで得られた学びについてお伝えします。</p>
<h1>EcosystemチームとKARTE Craftについて</h1>
<p>私が配属されたEcosystemチームは、KARTEと外部サービスを繋ぐ連携機能のオーナーを務めています。Ecosystemチームがオーナーとなっているプロダクトの一つに、<strong>KARTE Craft</strong>があります。</p>
<p>KARTE Craftはアプリケーション開発機能を提供するPaaSです。KARTEの機能拡張や独自のカスタマードリブンなサイト、アプリケーションを作成することができるため、KARTEの特徴であるユーザーの状態変化に応じた適切なアプリケーションの開発が可能になります。</p>
<p><a href="https://craft.developers.karte.io/get-started/about-karte-craft/">https://craft.developers.karte.io/get-started/about-karte-craft/</a></p>
<p>今回のインターンで私が担当したのは、KARTE Craftの <strong>Craft Functions</strong> という機能の改善でした。</p>
<h2>Craft Functionsとは</h2>
<p>Craft Functionsは、KARTE内外で発生するユーザーの状態変化に関するイベントをトリガーにして、任意のバックエンドプログラムを実行する機能です。外部サービスや自社システムとの連携、シンプルな連携から複雑な作り込みまで、あらゆるカスタマードリブンな独自のアプリケーションを作成できます。</p>
<p><a href="https://craft.developers.karte.io/get-started/about-karte-craft/#craft-functions%E3%81%AE%E4%BB%95%E7%B5%84%E3%81%BF">https://craft.developers.karte.io/get-started/about-karte-craft/#craft-functionsの仕組み</a></p>
<p>Craft Functionsで実行するプログラムを<strong>ファンクション</strong>と呼びます。ファンクションの作成時には、インフラの構築・運用は不要で、AIによるサポートも搭載されているため、手軽に作成することができます。</p>
<h1>インターンで行ったタスク</h1>
<p>インターン期間中は、大きく3つのタスクに取り組みました。配属後の初めのタスクとして、KARTEのサーバーインフラを理解するための設定変更を行いました。その後は、Craft Functionsの改善として、次の2つのタスクを担当しました。</p>
<ul>
<li>ファンクションが意図せず操作不能となる事象を回避するためのジョブ機能の構築</li>
<li>ファンクション一覧をタイプ別に取得するサービス間APIの作成</li>
</ul>
<p>今回は、上記の2つのタスクを紹介し、そこから得られた学びを説明します。</p>
<h2>タスク1: ファンクションが意図せず操作不能となる事象を回避するためのジョブ機能の構築</h2>
<p>最初のタスクは、作成したファンクションの状態管理に関する課題を解決するものです。ファンクションの作成処理の流れ、課題、そして解決方法を説明します。</p>
<h3>課題</h3>
<p>Craft Functionsでファンクションを作成する際のシステム概要図は次のとおりです。</p>
<p><img src="https://ik.imagekit.io/plaid/b48943b2-5706-4e92-9a4e-97345c8f456e/image.png" alt="image.png"></p>
<p>KARTEは複数のマイクロサービスで構成されており、サービス間通信にはAPIやqueueが使われています。図のwebサービスはKARTE Craftの管理画面を提供しています。workerサービスではファンクション用のコンピューティングリソース作成、更新、削除などの時間のかかる処理を非同期で行っています。</p>
<p>ファンクションの作成順序は次のとおりです。</p>
<ol>
<li>webサービスはファンクション作成リクエストを受け取り、MongoDBにstatus: <code>IN_PROGRESS</code> でファンクションの設定情報を保存し、workerサービスにファンクション作成メッセージを送信します。</li>
<li>workerサービスはファンクションを実行するためのコンピューティングリソースを作成します。</li>
<li>workerサービスはコンピューティングリソースの作成結果に基づき、ファンクションの設定情報を更新します。
<ul>
<li>リソース作成に成功した場合は設定情報のstatusを<code>SUCCESS</code>に変更します。</li>
<li>何らかのエラーで失敗した場合は<code>FAILED</code>に変更します。</li>
</ul>
</li>
</ol>
<p>KARTE Craftのアプリケーション上で予期しない不具合が発生した場合、ファンクションのstatusが <code>IN_PROGRESS</code> のままで操作ができなくなるという課題がありました。ユーザー自身でできる解決手段がないため、問題になっていました。</p>
<h3>解決策</h3>
<p>この課題の解決策として、ファンクションの設定情報を確認し、「最終更新から1時間以上経過」かつ「status: <code>IN_PROGRESS</code> 」なファンクションを作成失敗したとみなして <code>FAILED</code> に更新する仕組みを考えました。</p>
<p>実装方法として、以下の2つの方法を検討し、それぞれの長所と短所を比較しました。</p>
<ol>
<li>KubernetesのCronJobリソースを使用する。
<ul>
<li>メリット: 構成がシンプルで直感的に理解しやすい</li>
<li>デメリット: 新しいインフラの設定を追加する必要があり構成が複雑化する</li>
</ul>
</li>
<li>フロントエンドからファンクションに対するAPIを投げる
<ul>
<li>メリット: サーバーサイドの計算負荷が少ない</li>
<li>デメリット: フロントエンドの計算負荷が増える。APIの露出が増える。</li>
</ul>
</li>
</ol>
<p>今回はフロントエンドに対する余計な計算負荷やAPIの露出を避けることを優先し、方法1を選択しました。方法1を用いた際の構成図は次のとおりです。</p>
<p><img src="https://ik.imagekit.io/plaid/d206cc8d-2e89-4677-b5b5-a669d2a9eee4/image(1).png" alt="image(1).png"></p>
<p>cron-jobというサービスをKubernetesのCronJobとして作成し、定期的にMongoDBにクエリを実行することで、上記で説明した状態のファンクションを<code>FAILED</code>に更新します。</p>
<h3>実装</h3>
<p>実装において工夫した点を3点説明します。</p>
<ul>
<li>汎用的なジョブ実行コンテナの整備</li>
<li>ファンクション設定の更新方法</li>
<li>テストの実装</li>
</ul>
<p><strong>汎用的なジョブ実行コンテナの整備</strong></p>
<p>今回の実装時点で、KARTE Craft上でスケジュール実行しているのはこのCronJobリソースのみでした。そのため、プログラムを単純に実装して実行すれば十分でした。しかし、他のKARTEプロダクトのコードを見ると、より汎用的にジョブを起動できる構造になっていたので、それを参考に実装しました。</p>
<p>次のコードは、その実装を抜粋し、説明用に改変したものです。</p>
<pre><code class="language-jsx">const argv = minimist(process.argv.slice(2));
const { jobname } = argv;

import(`./path/to/${jobname}`)
  .then(async cronjob =&gt; {
    await cronjob.default(argv);
  })
  .catch(err =&gt; {
    logger.error(err);
    process.exit(1);
  });
</code></pre>
<p><code>jobname</code>は引数としてプログラムを実行する際に渡します。今回はCronJobリソースの <code>command</code> 属性でコンテナ起動時に渡すようにしました。これにより、スケジュールの異なる複数のプログラムを1つのコンテナイメージで呼び出すことが可能になりました。</p>
<p><strong>ファンクション設定の更新方法</strong></p>
<p>CronJobで定期的に実行する関数では、「最終更新から1時間以上が経過」かつ「statusが<code>IN_PROGRESS</code>」という条件を満たすファンクションのドキュメントを全件取得し、それらを<code>FAILED</code>に更新します。</p>
<p>当初はMongooseの<code>updateMany()</code>メソッドで一括更新しようとしましたが、このメソッドでは更新したドキュメントの内容が確認できないことがわかりました。ジョブでは更新したドキュメントをログ出力したいので、今回は条件を満たすドキュメント一式を <code>find()</code> メソッドで取得し、 <code>findOneAndUpdate()</code>メソッドで1件ずつ更新しました。</p>
<p><strong>テストの実装</strong></p>
<p>作成した処理が正常に動作することを確かめるため、テストコードも実装しました。テストでは、更新日時が異なる複数のドキュメントを作成し、当該処理の結果を想定の値と比較しました。</p>
<h2>得られた学び</h2>
<p>このタスクでは、KARTE Craft上にジョブシステムを作成しました。タスクを通じて次の学びを得られました。</p>
<ul>
<li>インフラ〜バックエンドを跨いだ機能の実装
<ul>
<li>ジョブ用のプログラムを記述し、それをKubernetesのワークロードとして動かす方法がわかりました。</li>
</ul>
</li>
<li>設計・実装レベルでの取捨選択の方法
<ul>
<li>構成や実装を検討する際に、候補を挙げてその良し悪しを検討することで、より説得力のある設計・実装になることがわかりました。</li>
</ul>
</li>
</ul>
<h2>タスク2: ファンクション一覧をタイプ別に取得するサービス間APIの作成</h2>
<p>次に取り組んだのが、KARTEのHook機能経由でファンクションを起動する設定をする際に必要となる、ファンクション一覧APIの改善タスクでした。マイクロサービス間の通信に必要なAPIを作成し、サービス間通信の実装を行いました。</p>
<h3>Hook v2</h3>
<p>Hook v2は、KARTE内で発生した特定の変更や追加などの変化をトリガーとして、そのデータをリアルタイムで外部のシステムに送信する機能です。</p>
<p><a href="https://developers.karte.io/reference/about-hook-v2">https://developers.karte.io/reference/about-Hook-v2</a></p>
<p>Hook v2を使うことで、KARTE内で起きた出来事をトリガーとして、外部システムで処理を行うことができます。例えば、ユーザーからメッセージが送信された際にそれをトリガーとして特定のファンクションを実行させることができ、顧客のリアルタイムな行動に合わせたアクションを提供することができます。参考として、以下の記事では汎用のWebhookリクエストを行う方法を説明しています。</p>
<p><a href="https://solution.karte.io/blog/2023/06/craft-webhook/index.html">https://solution.karte.io/blog/2023/06/craft-webhook/index.html</a></p>
<h3>課題</h3>
<p>次の図はHook v2の設定画面です。この画面では、トリガーとなるイベントと、そのトリガーで起動するファンクションを指定します。</p>
<p><img src="https://ik.imagekit.io/plaid/80d8a018-8062-4657-8928-5f4da923980c/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-10-2316.14.09.png" alt="スクリーンショット2024-10-2316.14.09.png"></p>
<p>Craft Functionsのファンクションには、2種類のタイプがあります。HTTPタイプとイベント駆動タイプです。</p>
<div class="iframely-embed" data-embedded-url="https://craft.developers.karte.io/craft-functions/craft-functions-types/"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://craft.developers.karte.io/craft-functions/craft-functions-types/" data-iframely-url="//cdn.iframe.ly/api/iframe?url=https%3A%2F%2Fcraft.developers.karte.io%2Fcraft-functions%2Fcraft-functions-types%2F&key=878c5bef402f0b2911bf6d4ce6261abd">ファンクションのタイプ</a></div></div><script async src="//cdn.iframe.ly/embed.js" charset="utf-8"></script>
<p>Hook v2において指定できるファンクションはイベント駆動タイプのみです。しかし、管理画面上はHTTPタイプ、イベント駆動タイプの両方が指定できるようになっていました。この相違を解決するため、管理画面上において指定できるファンクションからHTTPタイプを除き、イベント駆動タイプのみを表示する必要がありました。</p>
<h3>解決策と実装</h3>
<p>Hook v2機能はKARTE Craftとは異なるサービスで動作するため、マイクロサービス間でAPI通信を行いファンクション一覧を取得しています。今回はAPIの改善を行いました。具体的には、ファンクション一覧取得のリクエスト時に、タイプを指定できるAPIを追加し、それを利用するように変更しました。</p>
<p>Hook v2の管理画面においてファンクションの取得を行う際の構成図は次のとおりです。赤字で示すように、タイプを指定できるAPIへの切り替えを行いました。</p>
<p><img src="https://ik.imagekit.io/plaid/4745c925-fff4-4836-bda8-0a42cb293e9b/image(2).png" alt="image(2).png"></p>
<p>具体的な実装として、次の作業を行いました。</p>
<ul>
<li>Craft側にサービス間通信用のAPIを追加し、バックエンドを実装しました。</li>
<li>クライアントをOpenAPI Specから自動生成する仕組みを使って、サービス間通信用のクライアントを生成しました。</li>
<li>Hook v2のバックエンド処理で、新たに作成したサービス間通信用APIを利用するように変更しました。</li>
</ul>
<h2>得られた学び</h2>
<p>このタスクでは、マイクロサービス間の通信を行う仕組みを理解し、その改善を実施しました。タスクを通じて、次の学びが得られました。</p>
<ul>
<li>本番稼働するシステム上で、どのようにマイクロサービスが稼働しているかの全体像が掴めました。</li>
<li>インターフェース仕様（OpenAPI Spec）を活用してクライアントを自動生成することで、良い開発体験を提供できることがわかりました。</li>
</ul>
<h1>あとがき</h1>
<p>3ヶ月に渡って参加したインターンシップの感想を端的に言えば、非常に充実した経験でした。</p>
<p>今回のインターンシップを通して、次のような学びが得られました。</p>
<ul>
<li>実際に社員が担当するレベルのタスクを担当することで、本番稼働するプロダクトを開発する際に必要なレベル感を実感しました。</li>
<li>タスクを通じて、PaaSのインフラからバックエンドまで、一気通貫の開発を経験できました。</li>
<li>システム特性の面でも、Webシステムだけではなく、ジョブシステムを新たに作成する経験を通じて、開発の幅を広げることができました。</li>
</ul>
<p>これまでの私の開発経験は個人的なプロジェクトに限られており、実際のプロダクトに対する開発は初めてでした。今回のインターンシップで、実際に世の中に出ているシステムの開発に携わることで、多くの刺激を受けることができました。KARTEというアプリケーションの裏側の設計や動作原理を知った時の感動、そこで発生している課題に対して解決策を考え、技術選定をし、実装する楽しさ、そして自分が開発したものが実際にデプロイされる喜びを強く感じました。これらの経験を通じて、エンジニアリングそのものへの好奇心が大いに高まりました。また、この過程でコードを読み解き構造を把握する能力や、未知の技術を調査して組み込む力を養うことができたと考えています。</p>
<p>さらに、インターンシップの環境は非常に学びやすいものでした。メンターの方はいつ質問しても丁寧に答えてくださり、質問しやすい雰囲気が整っていました。加えて、インターンシップ期間中は他のチームの方々も交えたランチに頻繁に誘っていただき、様々なチームや職種の方々の話を聞くことで、多様な視点を知ることができました。</p>
<p>お世話になった社員の皆様に心から感謝申し上げます。本当にありがとうございました。</p>
<div class="iframely-embed" data-embedded-url="https://recruit.plaid.co.jp/requisitions/new-graduate-engineer"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://recruit.plaid.co.jp/requisitions/new-graduate-engineer" data-iframely-url="//cdn.iframe.ly/api/iframe?card=small&url=https%3A%2F%2Frecruit.plaid.co.jp%2Frequisitions%2Fnew-graduate-engineer&key=878c5bef402f0b2911bf6d4ce6261abd">新卒採用 & インターン (Product) | 募集ポジション | 株式会社プレイド</a></div></div><script async src="//cdn.iframe.ly/embed.js" charset="utf-8"></script>

こんにちは、桂田一輝と申します。2024年8月から10月の3ヶ月間、プレイドのEcosystemチームでソフトウェアエンジニアとしてインターンシップを行いました。インターンを通じて、Ecosystemチームが開発しているKARTE Craftというプロダクトの改善業務に携わってきました。そこで得られた学びについてお伝えします。

プレイドインターン体験記：プロダクトの改善活動から得た学び_プレイドエンジニアブログ

プレイドインターン体験記：プロダクトの改善活動から得た学び

<h1>自己紹介</h1>
<p>初めまして、プレイドでエンジニアインターンをしている小林雅史と申します。プレイド内ではあだ名である<a href="https://x.com/mercy34mercy">mercy</a>(マーシー)で呼ばれています。</p>
<p>立命館大学の修士1年生で、大学は情報理工学部、大学院は情報理工学研究科とコンピュータやプログラミングについて学び、研究しています。プログラミングは大学入学と同時に授業で取り組んできました。プログラミングに関しては授業だけでなく、ハッカソンなどでさまざまなアプリケーションを作成しました。特に<a href="https://cup.hackz.team/">ハックツハッカソン</a>が大好きで2度優勝しています。また<a href="https://ritsumeikanunivpress.com/07/11/4430/">大学生向けのバス時刻表アプリ</a>を先輩から引き継ぎ運用していたりもしています。3年生の時には学生IT団体<a href="http://www.watnow.jp/">watnow</a>の代表として<a href="http://www.watnow.jp/2022/10/20/%E9%96%A2%E8%A5%BF%E3%82%A8%E3%83%B3%E3%82%B8%E3%83%8B%E3%82%A2%E3%82%AB%E3%83%B3%E3%83%95%E3%82%A1%E3%83%AC%E3%83%B3%E3%82%B92022%E3%82%92%E9%96%8B%E5%82%AC%E3%81%97%E3%81%BE%E3%81%97%E3%81%9F/">企業様とのイベント</a>や<a href="http://www.watnow.jp/2022/08/24/watnow%e3%83%8f%e3%83%83%e3%82%ab%e3%82%bd%e3%83%b3-beginners-cup%e3%82%92%e9%96%8b%e5%82%ac%e3%81%97%e3%81%be%e3%81%97%e3%81%9f%ef%bc%81/">団体内ハッカソン</a>を立ち上げたりとコミュニティの運営も行いました。</p>
<p>プレイドでは2023年の4月からインターンとして勤務していて、最初は<a href="https://tech.plaid.co.jp/platform-engineering-kaigi-2024-report">認証基盤の開発</a>を行いました。その後Redisの監視を簡単にDatadogで行うための社内向けツールを開発し、2023年10月ごろから<a href="https://karte.io/package/message/">KARTE Message</a>というプロダクトの開発を行うチームに加わり、開発を行っています。</p>
<h1>KARTE Messageについて</h1>
<p>KARTE Messageは、データを元にメールやプッシュ通知、LINE メッセージの送信をノーコードで行うことができるため、マーケターなどの非エンジニアの方でも簡単に大規模なコンテンツ配信が可能なマーケティングオートメーションツールとなっています。</p>
<div class="iframely-embed" data-embedded-url="https://karte.io/package/message/"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://karte.io/package/message/" data-iframely-url="//cdn.iframe.ly/api/iframe?card=small&url=https%3A%2F%2Fkarte.io%2Fpackage%2Fmessage%2F&key=878c5bef402f0b2911bf6d4ce6261abd">KARTE Message（マーケティングオートメーション/MA）｜顧客体験を磨きこみ、自動化のその先へ【KARTE（カルテ）】</a></div></div><script async src="//cdn.iframe.ly/embed.js" charset="utf-8"></script> 
<h1>課題</h1>
<p>KARTE Messageの機能であるスマホアプリ向けのプッシュ通知配信では月間1億通を超える規模の配信を行っています。</p>
<p>今回、プッシュ通知に利用しているFCMの<a href="https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.messaging.md?hl=ja#messagingsendall">sendAll API</a>が2024年の6月20日に廃止されることが決定し、この期日までに今後も引き続き使用できるAPIに乗り換える必要がありました。</p>
<p>また、これまで使用していたsendAll APIでは、最大500件の通知をバッチ的に送信することができましたが、これと完全に互換性のあるAPIは現在用意されておらず、1通1通を個別に送信する必要があります。</p>
<p>今回私はこのリプレース作業を担当することになりました。</p>
<h1>テスト送信の実装・切り替え</h1>
<p>最初に、移行時のリスクが小さいテスト送信から置き換えることとなりました。本番送信もテスト送信も1通1通を個別に送信するロジックは同じであり、違いは送信数です。そのため、テスト送信の実装を先に行いリリースすることで、バグがあった際の影響範囲をテスト送信のみに抑えつつ新しい実装の信頼性を検証することができます。テスト送信の置き換えで行った作業は次の通りです。</p>
<ol>
<li>既存のコードとドキュメントを読み理解する</li>
<li>テスト送信の実装</li>
<li>テスト送信の実装の置き換え</li>
</ol>
<h3>1. 既存のコードとドキュメントを読み理解する</h3>
<p>既に動いているシステムをリプレースするため、まずは既存のコードを理解する必要がありました。コードを読むだけではなかなかコードの振る舞いを把握するのが難しいので、単体テストを新たに追加しました。</p>
<h3>2. テスト送信の実装</h3>
<p>リプレースする際のリスクを最小にするために、新規実装では既存の実装と同じケースの単体テストを書き、既存実装、新規実装ともにテストケースと結果が同じになることを確認することで、実装ミスがないかを検証しました。また、新規実装では、Goの実装が約1200行なのに対してテストコードは約5600行あります。テストはローカル環境で実行することができ、キャッシュがない状態でも30秒ほどで終了します。また、これらのテストはGithubActionsで自動で実行されており、生産性向上につながっています。</p>
<h3>3. テスト送信の実装の置き換え</h3>
<p>無事に実装が終わりテストも通ったら本番環境のテスト送信をリプレースしました。これまでの業務でバグの修正や新機能の実装をした事はあったものの、今正常に動いているものを全く新しいコードで作成されたシステムに置き換える経験は初めてでとても緊張しました。リリースの実行は社員さんに行ってもらい、検証環境で最終動作確認を行いました。テスト送信のリプレース後には、ユーザ企業様からバグ報告が数件ありました。その中でもGoへのリクエストのJSONのフィールドにnullがあった場合、Goのjson packageではnilに変換されるという仕様があり、nilのハンドリングがうまくできていないコードでバグが発生したのが印象的です。いくつかのバグを修正し、無事テスト送信の実装をsendAll APIからsend APIに切り替えることができました。</p>
<h1>本番配信の実装・負荷試験・切り替え</h1>
<p>テスト送信の置き換えが終了しバグの修正も終わると、本番配信も新しいAPIに置き換えます。本番配信の置き換えで行った作業は次の通りです。</p>
<ol>
<li>本番送信の実装</li>
<li>負荷試験</li>
<li>カナリアリリース</li>
</ol>
<h3>1. 本番送信の実装</h3>
<p>本番送信の実装に関しては本番送信とテスト送信のロジックを共通化したため、基本的にテスト送信の実装を流用する形で実装しました。</p>
<h3>2.  負荷試験</h3>
<p>本番配信では、KARTE Messageを使用されている企業様が大量のアプリユーザに向けてプッシュ通知を送信します。また、お客様が設定した速度で正しく配信する必要があります。そのため、アプリケーションに負荷がかかっても正常に動作することを検証する必要がありました。KARTE MessageはインフラにGCPのGKEを使用しているため、正しい速度で負荷がかかっても送信できる適切なk8sのスケーリング設定を見つける必要がありました。</p>
<p>負荷試験の環境には本番環境とは完全に切り離された検証環境を使用しました。検証環境は本番環境と同じシステムが動作しており、スケーリングの設定などが違うだけで本番環境と同じようにシステムが動作します。</p>
<p>負荷試験に関しては、社員さんからは時間かかってもいいからとりあえずやってみよう！といった感じで言われたので、ほぼ初めてGKEとその設定が書かれたk8s用のyamlファイルと戦うこととなりました。本番配信は、データベース、配信サーバ(今回作成したもの)、配信準備サーバなどさまざまなシステムが連携して動くことで実行されます。サーバやデータベースの状況はリアルタイムでdatadogで確認しました。</p>
<p>負荷試験の目標値は16667rps(時速6000万)となりました。これはAPI置き換え前のシステムで過去に負荷試験をした際の最大値となっています。</p>
<p>最初はスケーリングの設定を何も変えずに、2.7prs、277rps、1667rps、5555rpsと上げて行きました。すると、時速5555rpsの試験では設定した速度で配信されず1100rpsほどでしか配信できませんでした。ここから数時間悩んで色々設定を見ているうちに、配信サーバのスケーリング設定が問題になっていることに気づきました。最大node数とpod数が非常に小さい数に設定されていて、一定以上の負荷に耐えられないようになっていました。そこで、podの最大数を500、nodeの最大数を250に設定し再度負荷試験を行ったところ、16667rpsを達成できました。この時、配信サーバのpod数は100台ほどにスケーリングしていました。</p>
<p>目標値をクリアしたので、次に最適な設定を探します。KARTE Messageではサービスの性質上、リクエストのスパイクが発生しやすいです。また、深夜帯などは配信がなくサーバに負荷がかからない状態になります。そのため、スパイクに耐えられる最小pod数と、最大負荷に耐えられる最大pod数を見つける必要があります。そこで、1podあたりどれくらいの配信数を捌けるのかを調査しました。調査するために、pod数を20台固定にし少しづつ少ない配信数から負荷試験を行い、限界の配信速度を見つけ出しました。20台のpodで2700万/hの配信を行うことができました。pod1台で約135万/hの配信が可能です。そこで、6000万/hの配信に耐えられるpod数より少し余裕を持たせた50を、最大pod数としました。</p>
<p>負荷試験だけで10営業日ほどかかりました、負荷試験の勘所やk8sの特性を理解するのに時間を要しました。初めてやることは、手探りで頑張ってみることも大事ですが、社員さんなど経験がある人にある程度、勘所を先に教わっておくともっと効率良くできたかなと感じました。学生が簡単に経験することができない、k8sを用いたシステムの負荷試験ができたことは非常に良い経験となりました。</p>
<h3>3. カナリアリリース</h3>
<p>負荷試験も終わり、ついに本番配信を新しいAPIに置き換えます。全ユーザに一斉に適用してしまうと、もしもバグなどがあった場合に影響範囲が広くなってしまうため、一部のお客様から順次新しいAPIを適用しました。APIの切り替えは環境変数で指定した特定のお客様の時のみ新しいAPIが実行されるように実装を行いました。環境変数で切り替えを行うことで、もし新しいAPIの実装に問題があった際に、修正やロールバックしたアプリケーションをデプロイすることなく、環境変数を切り替えるだけで既存のAPIの実装に戻せるため、環境変数を活用したカナリアリリースを行いました。カナリアリリースは、置き換え前と比べて、悪化している指標がないか確認しながら約1ヶ月かけて全てのお客様の配信APIを新しいAPIに切り替えました。</p>
<h1>リプレース結果</h1>
<p>リプレースは実装を始めてから約5ヶ月で終了しました。結果として、新しいAPIに切り替えたことによる大きな障害はありませんでした。そして、既存実装よりもエラー率も下がりました。</p>
<h1>最後に</h1>
<p>今回のプッシュ通知配信で使用するAPIのリプレースの実装、試験、移行は全て自分の手で行いました。もちろん社員さんの助けなしではできなかったです。今回のプロジェクトを通して長期インターンでしか体験できない貴重な経験ができました。また、自分は京都に住んでいるのでリモート勤務だったですが、地方に住んでいる学生についてはリモートでも受け入れてくれる環境は非常にありがたかったです。他のインターン生が行ったことについては、ぜひプレイドのエンジニアブログをご覧ください[1][2][3][4][5]。このような経験をしてみたい方、プレイドに興味を持った方は下記からプレイドのエンジニアインターンに応募してみてください！</p>
<div class="iframely-embed" data-embedded-url="https://recruit.plaid.co.jp/requisitions/new-graduate-engineer"><div class="iframely-responsive" style="padding-bottom: 28.2577%; padding-top: 120px;"><a href="https://recruit.plaid.co.jp/requisitions/new-graduate-engineer" data-iframely-url="//cdn.iframe.ly/api/iframe?url=https%3A%2F%2Frecruit.plaid.co.jp%2Frequisitions%2Fnew-graduate-engineer&key=878c5bef402f0b2911bf6d4ce6261abd">新卒採用 & インターン (Product) | 募集ポジション | 株式会社プレイド</a></div></div><script async src="//cdn.iframe.ly/embed.js" charset="utf-8"></script>
<p>[1] <a href="https://tech.plaid.co.jp/internship-mongodb-update">インターンシップで全社のMongoDBをアップデートした話</a></p>
<p>[2] <a href="https://tech.plaid.co.jp/intern-at-plaid-calloc">プレイドインターン体験記: はじめての開発インターンを通じて得た学び</a></p>
<p>[3] <a href="https://tech.plaid.co.jp/intern-at-plaid-kenshin">プレイドでの開発インターン: 3ヶ月のフルタイムエンジニアとしての挑戦を経て</a></p>
<p>[4] <a href="https://tech.plaid.co.jp/intern-at-plaid-shohei-shiraki">プレイドのインターン体験記：分散システムとプロダクト貢献意識の両面からの学び</a></p>
<p>[5] <a href="https://tech.plaid.co.jp/mongo-atlas-to-bigquery">MongoDB AtlasからBigQueryへのリアルタイムレプリケーション</a></p>


KARTE Messageで使用しているFCMのsendAll APIが廃止となるため、APIの置き換えを行った後負荷試験を行なった。

FCMのSendAll API廃止対応

KARTE MessageにおけるFCMのSendAll API廃止対応について

カラムナフォーマットの利点を最大限活かすために書き込み処理、特にリアルタイムの書き込み処理における技術的な課題とOSS DBの具体的なアプローチを紹介しています

OLAP-DBでのreal-time ingestionをカラムナに最適化する技術 - PLAID engineer blog

OLAP-DBでのreal-time ingestionをカラムナに最適化する技術 

<h2>はじめに</h2>
<p>こんにちは，プレイドのCore Platformチーム<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup>（プレイドで社内の全てのプロダクト基盤やリアルタイム解析基盤<sup class="footnote-ref"><a href="#fn2" id="fnref2">[2]</a></sup><sup class="footnote-ref"><a href="#fn3" id="fnref3">[3]</a></sup>を扱っているチーム）でインターンをしている<a href="https://lapla.dev/about/">lapla</a>といいます．プレイドでは2024年6月より働いており，この度社内で広く用いられているデータベースであるMongoDBのバージョンアップ業務に携わったので，その過程で得られた知見についてまとめようと思います．<br>
データベースのバージョンアップは，データベースを使用しているシステムにとって避け難いタスクであり，それはプレイドも同様です．そこでプレイドでは， 単に公式のアップデートドキュメントを読むだけではなく， MongoDBの内部構造も理解した上で作業することにより，安全なバージョンアップを継続的にかつサービス無停止で行っています．今回はその点について説明しようと思います．<br>
なお，本記事はデータベースのいわゆるHow To記事ではなく， データベースの構造に興味のある方や， 既に他のデータベースを使用していて， 今後MongoDBを使ってみようという方向けに記述を行っているため， 前半にデータベースのバージョンアップに関する一般的な話や，プレイドでの使用状況を述べ，後半にMongoDBの内部構造に触れるという構成を取っています．</p>
<h2>自己紹介</h2>
<p>現在，筑波大学情報学群情報科学類の4年生で，主にシステムプログラミングやクラウドネイティブな技術に興味がありますが，OSから機械学習までレイヤを問わずにプログラムを書きます．<br>
趣味のプログラミングについて触れると，学部1年の頃に手が滑って，主にC++でx86_64向けのTCP/IPプロトコルスタックが搭載されたGUI操作可能なOSを書いた結果，その後も手が滑り続けて学部3，4年の頃にはRustで64bit RISC-V向けのOSを書いていました．他にもRust言語が好きなので，RustでELFのタイムトラベルデバッガを書いたり，ELFバイナリ難読化器（ELFバイナリの実行時の動作を変えずに，解析からの妨害対策がなされたバイナリを作り出す）を作っていたりしました．最近は内部でRISC-VバイナリをエミュレートするようなOCIコンテナランタイムを開発しています．<br>
比較的高いレイヤも好きで，例えば学部2年の頃には文章から音を生成するCGANを研究していたりしました．</p>
<h2>プレイドにおけるMongoDBとその周辺ソフトウェアの利用</h2>
<p>プレイドでは，主力プロダクトであるCXプラットフォーム<a href="https://karte.io/">KARTE</a>の様々な場面で主にMongoDBを使用しています．また，ODM（Object Document Mapper）として<a href="https://github.com/Automattic/mongoose">Mongoose</a>を用いていて，Node.js経由でMongoDBを操作しています．プレイドではサーバーサイドがほとんどNode.jsで書かれており，MongoDBは内部的にデータをBSONで保持している点や非同期処理との相性の良さという点でNode.jsとの親和性が高いため，積極的にMongoDBを使用しています．この辺りについては弊社のgamiが書いた「 <a href="https://tech.plaid.co.jp/plaid_loves_nodejs">PLAIDがNode.jsを採用し、5年間で12万行書いてわかったこと</a>」 をご覧ください．</p>
<h2>データベースのバージョンアップ</h2>
<p>さて， 冒頭にも述べた通り，データベースの定期的なバージョンアップは，多くのソフトウェア企業に付いて回るタスクの1つです．<br>
主にOSSとして公開されているような一般的なRDBをセルフホストしている場合において，バージョンアップなどの作業を行うためには，データの整合性を取るために一旦データベースへの書き込み処理を停止した上でレプリケーションをおこなってから，アプリケーションが参照するデータベースの接続先を変更する手順を踏むのが一般的と思われます．しかし，いわゆるNewSQLに属するMongoDBでは内部で複数同じ状態のデータを持つノードが複数おり、この特性を活用することで，プレイドでは平日の昼間であっても安全にバージョンアップの作業を行うことができています．<br>
なぜMongoDBの場合にはサービスを停止させずに， 安全にバージョンアップできるのかに関しては，本記事後半で紹介する，MongoDBの内部構造を，論文などを元にして理解することにより達成されています．平日昼間など，通常は忌避される時間帯であっても，安全性の根拠を持ってメンテナンスウィンドウなどを設けずにバージョンアップを行うことは，開発速度の向上などの開発者体験の向上に繋がります．また， サービスを停止させる時間が不要なことは，KARTEをご利用いただくユーザー様にとっても大きな恩恵があると考えます．</p>
<h2>今回のバージョンアップ完了までの手順</h2>
<p>ここでは今回行ったバージョンアップの大まかな手順について説明します．大枠としては以前にMongoDBをバージョン4からバージョン5に上げた際のものと同様です．当時の記録については以前インターンされていた方が書いた「<a href="https://tech.plaid.co.jp/internship-mongodb-update">インターンシップで全社のMongoDBをアップデートした話</a>」に詳しく記載されていますので，ぜひご覧ください．</p>
<ol>
<li>アプリケーションコードに影響を与えそうな変更の調査<br>
まずはMongooseやMongoDB Serverの現在のバージョンから，バージョンアップする目標のバージョンまでの変更を確認し，主にプロダクトの動作に影響を与えそうなものをピックアップして調査しました</li>
<li>社内ライブラリのアップデート<br>
プレイド社内には，様々なアプリケーションが共用するライブラリが存在します．その中にはMongoDBのラッパーなども含まれているため，これらの更新を行いました</li>
<li>各アプリケーションのアップデート<br>
新しくなった社内のライブラリを用いて，各アプリケーションが動作するように修正を行います．この作業は基本的に各アプリケーションチームに依頼し，書き換えを行なってもらいました</li>
<li>データベースのアップデート<br>
最初に検証環境のデータベースのバージョンを上げ，問題がなさそうであれば本番環境のデータベースもバージョンアップを行います．この際に，本記事後半で触れる内部構造の理解により，安心感をもったバージョンアップを行えています．</li>
</ol>
<h2>バージョンアップ作業の今後</h2>
<p>現在は，バージョン7へのバージョンアップに必要な調査や実装を行っています．バージョン7へのバージョンアップに伴う，現状の我々のユースケースに大きな影響を与えそうなMongooseでの変更をいくつか紹介すると，次のようなものがあります：</p>
<ul>
<li>callbackを用いた処理を書くことができないようになる（社内のアプリケーションコードには，比較的昔に書かれたものではしばしばcallbackが使われている）</li>
<li>社内実装で多く使われている関数を使用できなくなる（findOneAndRemoveなど）</li>
</ul>
<p>このように，今後に控えているアップデートではより困難なアップグレード作業が予想されますが，今回のアップグレードで得られた経験も積極的に用いて，無事に作業を成功させるべく動いています．</p>
<p>—</p>
<p>ここからはよりMongoDBの内部構造を理解したい方向けに記述します．</p>
<h2>MongoDBの内部構造を想像する</h2>
<p>さて，冒頭でも述べた通り，本記事の後半ではMongoDBの内部構造について見ていきます. ここではあくまでも公開論文などをもとに内部の仕組みなどを想像して書いているため， 間違っている可能性は否定できないことを述べておきます.<br>
MongoDBの内部では，分散合意アルゴリズムとして著名なRaftを独自に改良したアルゴリズムを用いて合意を取っています．この機序を理解するためには次の3つの論文が特に参考になります：</p>
<ul>
<li><a href="https://raft.github.io/raft.pdf">In Search of an Understandable Consensus Algorithm (Extended Version)</a>（以下論文1）: 分散合意アルゴリズムのRaftについて紹介されている論文です</li>
<li><a href="https://www.usenix.org/conference/nsdi21/presentation/zhou">Fault-Tolerant Replication with Pull-Based Consensus in MongoDB</a>（以下論文2）: MongoDBの内部では，純粋なRaftアルゴリズムではなく，後述するPull-Based Consensusと呼ばれるアルゴリズムを用いてノード間での合意を取っています．このアルゴリズムについて解説した論文です</li>
<li><a href="https://dl.acm.org/doi/10.14778/3352063.3352125">Tunable consistency in MongoDB</a>: MongoDBでは，書き込みと読み込みの整合性をある程度自由に設定することができます（Tunable Consistency）．これによりアプリケーション特性に合わせた整合性を取ることができます．この内容についての説明がなされています</li>
</ul>
<p>今回はスペースの都合上，論文1で紹介されている純粋なRaftの動作についての説明はある程度既知のものとし，以降は論文2で提案されているpull-based Raftの動作について説明を行うことにします．</p>
<h3>Pull-Based Consensus</h3>
<p>先に述べた通り，MongoDBの内部では純粋なRaftではなく，動作が改造されたRaftアルゴリズムが用いられていて，これは論文内ではPull-Based Consensusとされています．本記事では，純粋なRaftの改造版であるということを強調するために，Pull-Based Raftと呼ぶことにします．<br>
まず一般的なRaftアルゴリズムは，次の図のように，LeaderノードからFollowerノードに対してログが配信され，Followerノードはそれを個々に有しているという構造を取っています．Leaderノードで何らかの不具合が起きると，クラスターはvotingを行い，新たなLeaderノードを選出します：<br>
<img src="https://ik.imagekit.io/plaid/0bd8ed16-d589-473f-8b78-7f10558ba122/image1.png" alt="image1.png"><sup class="footnote-ref"><a href="#fn4" id="fnref4">[4]</a></sup><br>
また，次図に示すように，クライアント側からのリクエストに対しては複数のモジュールにログが分散して保存されます：<br>
<img src="https://ik.imagekit.io/plaid/77f8ba01-c659-4897-84a7-0d49418acd13/image3.png" alt="image3.png"><sup class="footnote-ref"><a href="#fn5" id="fnref5">[5]</a></sup></p>
<p>分散合意を取るという目的であればこれで十分ですが，スケーリングやバージョンアップの際など，クラスター内のノードが増減する場合においては，データの同期を柔軟に行うのが難しいといった課題があります．<br>
これに対して，MongoDBは独自のPull-Based Raftアルゴリズムを実装しており，これはFollowerノードが自律的にLeaderノードに対してログの配信を要求しにいくような構造になっています．<br>
<img src="https://ik.imagekit.io/plaid/72eac0ca-f319-44ab-9df9-46c81ce2ed6b/image2_1.png" alt="image2_1.png"><sup class="footnote-ref"><a href="#fn6" id="fnref6">[6]</a></sup></p>
<p>これはレプリカのデータ同期を任意の2つのレプリカで行うことができるという特徴があり，様々なネットワークトポロジーを取ることができるようになります．また，これによりネットワークの帯域幅を削減できるという特徴も存在します．<br>
また，バージョンアップの作業を行うにあたっては，クラスター内の古いバージョンのノードが1つ，新しいバージョンのものと入れ替わって，問題が無ければ他の古いバージョンのものも順々に取り替えていくという方式を取っているものと思われます．このことは， MongoDBの公式のドキュメントには記述がありませんが，バージョンアップ時のメトリクスを観察した結果得られたヒューリスティックな観測です．この挙動が可能なのは， Pull-Based Raftによって任意のレプリカ間でのデータ同期を柔軟に行えるためだと考えています．このような挙動は，バージョンアップ時に何か不具合が生じてもサービスを停止させることなくロールバックできるという点で利点があります．</p>
<h2>最後に</h2>
<p>ここまで見てきたように，論文などのある程度信頼できるソースを元にした，ソフトウェアの内部構造理解は，より安全なシステム設計・運用につながるものであると言えます．<br>
私自身は今回のバージョンアップ作業に際して，こういった理論面から実装までの理解を一気通貫で行うことができたので，貴重な経験を積めたと思います．<br>
本記事ではその一端をお伝えすることができたと思うのですが，プレイドは計算機的に面白い業務が様々な場所に存在する環境であると思います．プレイドで働くことに興味を持たれた方は，ぜひ次のリンクもご覧ください．</p>
<div class="iframely-embed" data-embedded-url="https://recruit.plaid.co.jp/engineer"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://recruit.plaid.co.jp/engineer" data-iframely-url="//cdn.iframe.ly/api/iframe?card=small&url=https%3A%2F%2Frecruit.plaid.co.jp%2Fengineer&key=878c5bef402f0b2911bf6d4ce6261abd">エンジニアについて | 採用情報 | 株式会社プレイド</a></div></div><script async src="//cdn.iframe.ly/embed.js" charset="utf-8"></script>
<hr class="footnotes-sep">
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn1" class="footnote-item"><p><a href="https://blog.plaid.co.jp/n/nfa3642bf9871">“エンドユーザーに露出するプラットフォーム”をつくる。Core Platformチームの仕事はなぜチャレンジングなのか</a> <a href="#fnref1" class="footnote-backref">↩︎</a></p>
</li>
<li id="fn2" class="footnote-item"><p><a href="https://tech.plaid.co.jp/blits_pre_aggregation">Blitz（前編）: 自由度と即時更新性を担保したAggregation</a> <a href="#fnref2" class="footnote-backref">↩︎</a></p>
</li>
<li id="fn3" class="footnote-item"><p><a href="https://tech.plaid.co.jp/blitz_realtime_analytics_architecture">Blitz（後編）：リアルタイムユーザー解析エンジンを実現する技術 - 強整合な解析 -</a> <a href="#fnref3" class="footnote-backref">↩︎</a></p>
</li>
<li id="fn4" class="footnote-item"><p>Diego Ongaro and John Ousterhout. 2014. In search of an understandable consensus algorithm. In Proceedings of the 2014 USENIX conference on USENIX Annual Technical Conference (USENIX ATC'14). USENIX Association， USA， 305–320. <a href="#fnref4" class="footnote-backref">↩︎</a></p>
</li>
<li id="fn5" class="footnote-item"><p><a href="https://www.yugabyte.com/tech/raft-consensus-algorithm/">What is the Raft Consensus Algorithm?</a> <a href="#fnref5" class="footnote-backref">↩︎</a></p>
</li>
<li id="fn6" class="footnote-item"><p><a href="https://www.usenix.org/system/files/nsdi21_slides_zhou-siyuan.pdf">Fault-Tolerant Replication with Pull-Based Consensus in MongoDB</a> <a href="#fnref6" class="footnote-backref">↩︎</a></p>
</li>
</ol>
</section>


社内で広く用いられているデータベースであるMongoDBのバージョンアップ業務に携わったので，その過程で得られた知見についてまとめようと思います．

MongoDBをサービス無停止で継続的かつ安全にバージョンアップしている話_プレイドエンジニアブログ

MongoDBをサービス無停止で継続的かつ安全にバージョンアップしている話

こんにちは。プレイドでWicleを開発しているchakeです。 Wicleはプロダクトを使うユーザーの行動を分析し、改善するサイクルを助けるプロダクトアナリティクスサービスです。先日パブリックベータ版をリリースし、だれでもオンライン上からサインアップすることができるようになりました。

新進気鋭の認証サービスClerkを実プロダクトで使いこなせ

こんにちは！6月から8月までの3ヶ月間、プレイドでエンジニアインターンとして勤務しておりました伊藤孝太朗です。私は現在、カナダ・バンクーバーにあるブリティッシュコロンビア大学（University of British Columbia, UBC）で学部3年生としてコンピュータサイエンスを専攻しています。このブログでは、私がプレイドでインターンとしてどのような課題に取り組んだか、そこから何を学んだかについてお話しさせていただきたいと思います。

プレイドインターン体験記：エンジニアとしての学びを深めた3ヶ月_プレイドエンジニアブログ

プレイドインターン体験記：エンジニアとしての学びを深めた3ヶ月

長期運用システムにおけるNode.js / npmアップデート工程を紹介します

KARTEの分析システムのNode.jsを16から20にアップデートしました

<p>株式会社プレイドでデザインエンジニアをしている安田です。</p>
<p>この記事では、社内向けに提供しているライブラリの使用状況を把握すべく作成した、プロダクト全体のソースコードを解析して、提供しているモジュールおよびそれを使用しているプロダクトごとに個別に自動集計する仕組みとその実装方法について解説します。</p>
<h2>ライブラリ開発の問題と使用状況の解析</h2>
<p>弊社では、KARTEのプロダクト群全体のデザインシステムである「Sour」を開発しています。その一環として、React製のUIライブラリ「sour-react」を作成し、社内向けのnpmパッケージとして提供しています。現在、sour-reactはKARTEのいくつものプロダクトにおいて採用されており、UI開発に欠かせないものになるほど浸透しています。</p>
<p>作成したライブラリが広く使われるようになるのは喜ばしくもありますが、一方、それに伴って新たな問題が生じることもあります。その一つが、後からの仕様変更、とりわけ破壊的変更が難しくなってしまうことです。</p>
<p>原則的には、できるだけライブラリの破壊的変更を起こさないように開発を進めるべきではあります。しかし、ライブラリの機能が増え続けたり運用期間が長期化したりした結果、いずれその必要に迫られることは多かれ少なかれ避けがたいものです。</p>
<p>もし、ライブラリのユーザー数が少なく、その使用範囲も微々たるものであれば、破壊的変更が発生しても対応は容易です。しかしsour-reactは、数多くのプロダクトのUIにふんだんに組み込まれているため、破壊的変更に伴う影響を軽視できなくなりつつあります。また、破壊的変更に対応するためのユーザー側の労力が大きくなればなるほど、バージョンアップ作業が滞ってしまい、UIの不具合が放置される結果に繋がってしまうこともあります。とはいえ、その影響を必要以上に懸念して、変更すべきものを変更せずに誤魔化し続けるのも不健全です。</p>
<p>そこで、仕様変更に伴う影響範囲を適切に把握すべく、ライブラリの使用状況を解析して可視化する仕組みを作成しました。具体的に言えば、KARTEのすべてのソースコードの中から、sour-reactが読み込まれている箇所を検出して、どのプロダクトからどのモジュールが参照されているかを個別に自動集計するというプログラムを作成しています。これを用いて、マークダウンファイルとして次のような集計結果を出力しています。</p>
<p><img src="https://ik.imagekit.io/plaid/b771e07d-ef2a-4f12-a1cb-05c25b971b8a/1.png" alt="表形式で「Accordion」「AdminLayout」「AutoComplete」などの行が並び、列ごとに数値がそれぞれ表示されている"></p>
<p><img src="https://ik.imagekit.io/plaid/0f570cbc-c10d-414a-9123-a67b638c14e1/2.png" alt="「sour-reactのモジュールごとの集計」という大見出しがあり、「Button (422)」という中見出しに続いて「XXX (140)」という小見出しがある。続いてファイルパスがリストで表示されている"></p>
<p><img src="https://ik.imagekit.io/plaid/02a8f29d-635b-4b2e-99dc-2eb40a111be7/3.png" alt="「sour-reactを利用するパッケージごとの集計」という大見出しがあり、「XXX (1720)」という中見出しに続いて「Button (140)」という小見出しがある。続いてファイルパスがリストで表示されている"></p>
<p>これらの集計はGitHub Actionsによって定期的に自動実行され、毎朝9時になるたび最新の状態にアップデートされるようになっています。</p>
<p>この仕組みによって、実際にモジュールが参照されている箇所や、どのモジュールの使用頻度が高いか、どのプロダクトにおいて積極的に採用されているかなどを、効率的に調査できるようになりました。</p>
<p>一つの活用例としては、不要なモジュールをライブラリから削除するために、この集計結果を参考にして選定したことが挙げられます。Sourにはその歴史的な経緯により、特定のプロダクトでしか使われないような特殊なモジュールや機能が多く含まれていました。それらは本来的には、共有ライブラリとしてではなく、それぞれのプロダクト側のソースコードとして管理されるべきです。とはいえ、すでにライブラリとしての提供を行なってしまっている以上、意図せずそれらが使用されてしまっている可能性もあり、その疑念が晴れない限りは削除してしまうことが必ずしも得策とは言い切れませんでした。そこで、こうした集計結果を参考にすることで、各モジュールの使用状況を正確に把握し、確信を持って安全に変更を行うことができました。</p>
<h2>実装方法の解説</h2>
<p>続いて、先述した仕組みの実装方法について解説します。なお、この記事で紹介する仕組みは、OSSとしてGitHubに公開しています。解説と併せて参照してください。</p>
<p><a href="https://github.com/yuheiy/internal-library-reference-stats">yuheiy/internal-library-reference-stats</a></p>
<p>集計結果の出力形式は次の3種類とします。</p>
<ol>
<li><code>README.md</code>: 横軸がsour-reactのモジュール名、縦軸がプロダクト名になったテーブルを出力する。セルにはそれに対応する参照箇所数を表示する。最終列と最終行には合計値を表示する。</li>
<li><code>by-module-export-name.md</code>: 見出し2がsour-reactのエクスポート名、見出し3がプロダクト名という文書構造になり、参照箇所のファイル一覧がそれに続く。</li>
<li><code>by-user-package.md</code>: 見出し2がプロダクト名、見出し3がsour-reactのエクスポート名という文書構造になり、参照箇所のファイル一覧がそれに続く。</li>
</ol>
<p>処理の流れは主に次のようになります。</p>
<ol>
<li>
<p>KARTEのソースコードを含むGitリポジトリから、拡張子が<code>js,ts,jsx,tsx</code>のいずれかに当たるファイルすべてを読み込む</p>
</li>
<li>
<p>TypeScriptのCompiler APIを使って、sour-reactを読み込むimport文を抽出する</p>
</li>
<li>
<p>import文の形式がnamed importsであれば、そのエクスポートの名前とimport文が出現する行数を取得する</p>
</li>
<li>
<p>named importsの解析結果をフラットな配列としてまとめる</p>
<pre><code class="language-tsx">export type NamedImportsStat = {
  sourcePath: string;
  moduleExportName: string;
  lineRange: LineRange;
};

export function getNamedImportsStats(filePaths: string[]): NamedImportsStats[] {
  // ...
}
</code></pre>
</li>
<li>
<p>解析結果をまとめたものを出力形式に応じて加工して出力する</p>
</li>
</ol>
<p>これらについて、いくつかにポイントを絞って解説します。</p>
<p>まず、ソースコードを解析するに当たって、対象となるソースコードを用意します。この仕組みをGitリポジトリとして管理するのであれば、解析対象のソースコードは<a href="https://git-scm.com/book/ja/v2/Git-%E3%81%AE%E3%81%95%E3%81%BE%E3%81%96%E3%81%BE%E3%81%AA%E3%83%84%E3%83%BC%E3%83%AB-%E3%82%B5%E3%83%96%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB">サブモジュール</a>として取り込むのがよいでしょう。</p>
<p>それらのソースコードからimport文を抽出するには、ASTを使用するのが最適です。ソースコードからASTを生成するためにはいくつかのやり方がありますが、今回は<a href="https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API">TypeScriptのCompiler API</a>を使用することとします。</p>
<p>sour-reactでは、必要なモジュールを都度named importsによって読み込むことを推奨しています。具体的な使用例は次の通りです。</p>
<pre><code class="language-tsx">import { Button, Tabs } from '@plaidev/sour-react';
</code></pre>
<p>このようなソースコードを解析して、named importsによって読み込まれているエクスポート名と、ソースコード内でimport文が出現する行数を取得します。たとえば次のような実装になります。</p>
<pre><code class="language-tsx">import fs from 'node:fs';
import ts from 'typescript';

type LineRange = {
  start: number;
  end: number;
};

type NamedImports = Record&lt;string, { lineRange: LineRange }&gt;

export function analyzeNamedImports(filePath: string, targetModuleName: string): NamedImports {
  const fileContent = fs.readFileSync(filePath, 'utf8');
  const sourceFile = ts.createSourceFile(filePath, fileContent, ts.ScriptTarget.Latest, true);

  const namedImports: NamedImports = {};

  function visit(node: ts.Node) {
    if (ts.isImportDeclaration(node)) {
      const moduleSpecifier = node.moduleSpecifier.getText().slice(1, -1); // Remove quotes

      if (moduleSpecifier === targetModuleName) {
        const start = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;
        const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
        const lineRange: LineRange = { start, end };

        const importClause = node.importClause;

        if (importClause) {
          if (importClause.namedBindings &amp;&amp; ts.isNamedImports(importClause.namedBindings)) {
            importClause.namedBindings.elements.forEach((element) =&gt; {
              const importName = element.propertyName?.text ?? element.name.text;
              if (!(importName in namedImports)) {
                namedImports[importName] = { lineRange };
              }
            });
          }
        }
      }
    }

    ts.forEachChild(node, visit);
  }

  visit(sourceFile);

  return namedImports;
}
</code></pre>
<p>そして、この結果を後続の処理で扱えるように、フラットな配列としてまとめます。</p>
<pre><code class="language-tsx">import { analyzeNamedImports, type LineRange } from './import-analyzer';

const targetModuleName = '@plaidev/sour-react';

export type NamedImportsStat = {
  sourcePath: string;
  moduleExportName: string;
  lineRange: LineRange;
};

export function getNamedImportsStats(filePaths: string[]) {
  const result: NamedImportsStat[] = [];

  for (const filePath of filePaths) {
    const namedImports = analyzeNamedImports(filePath, targetModuleName);

    for (const [moduleExportName, { lineRange }] of Object.entries(namedImports)) {
      result.push({
        sourcePath: filePath,
        moduleExportName,
        lineRange,
      });
    }
  }

  return result;
}
</code></pre>
<pre><code class="language-tsx">import fg from 'fast-glob';
import { analyzeFiles } from './import-analysis-organizer';

async function main() {
  const filePaths = await fg.glob('internal-library-reference-stats-user-a/**/*.{js,ts,jsx,tsx}');
  const namedImportsStats = getNamedImportsStats(filePaths);
  // ...
}

main().catch((e) =&gt; {
  throw e;
});
</code></pre>
<p>こうして作成した配列を、データの出力形式に応じて分類します。モジュールのエクスポート名とプロダクト名というそれぞれの軸に応じて処理します。</p>
<pre><code class="language-tsx">function groupByModuleExportName(namedImportsStats: NamedImportsStat[]): Map&lt;string, NamedImportsStat[]&gt; {
  // ...
}

function groupByUserPackage(namedImportsStats: NamedImportsStat[]): Map&lt;string, NamedImportsStat[]&gt; {
  // ...
}

const byModuleExportName = groupByModuleExportName(namedImportsStats);
const byUserPackage = groupByUserPackage(namedImportsStats);
</code></pre>
<p>データをプロダクトごとに分類する際には、import文が書かれているファイルがどの<code>package.json</code>に属しているかに基づいて処理します。<a href="https://github.com/sindresorhus/pkg-dir">pkg-dir</a>を使うことで、そのファイルの親に当たる<code>package.json</code>のパスを取得できます。</p>
<pre><code class="language-ts">import path from 'node:path';
import { packageDirectorySync } from 'pkg-dir';

function groupByUserPackage(namedImportsStats: NamedImportsStat[]): Map&lt;string, NamedImportsStat[]&gt; {
  const result = Map.groupBy(namedImportsStats, ({ sourcePath }) =&gt;
    packageDirectorySync({ cwd: path.dirname(sourcePath) })
  );
  // ...
}
</code></pre>
<p>これらのような操作によって、最終的に出力するコンテンツを生成します。実際の処理はやや複雑であるため、説明は割愛します。ご興味があればソースコードを見てみてください。</p>
<p><a href="https://github.com/yuheiy/internal-library-reference-stats/blob/main/scripts/renderers.ts">internal-library-reference-stats/scripts/renderers.ts</a></p>
<p>最後に、これらの処理を定期的に実行させるために、GitHub Actionsのワークフローをセットアップします。ソースコードの解析を行う前に、サブモジュールとsour-reactのバージョンを最新の状態にアップデートするようにします。ワークフローは、日本時間で午前9時になるたび毎日実行されるように設定します。</p>
<pre><code class="language-yaml">name: Auto update

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  auto-update:
    permissions:
      contents: write
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true
      - name: Update submodules
        run: git submodule update --remote
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
          cache: npm
      - name: Install dependencies
        run: |
          npm ci
          npm update @plaidev/sour-react
      - name: Build
        run: npm run build
      - name: Commit changes
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
          git add --all
          git commit -m &quot;Automated build&quot;
          git push
</code></pre>
<h2>internal-library-reference-statsの使い方</h2>
<p><a href="https://github.com/yuheiy/internal-library-reference-stats">internal-library-reference-stats</a>はOSSとして公開されているので、どなたでもご自由に利用することができます。基本的には、次のようにすることで使い始められます。</p>
<ol>
<li>
<p>internal-library-reference-statsをテンプレートリポジトリとして新規リポジトリを作成する</p>
</li>
<li>
<p>作成したGitリポジトリをクローンする。<code>git clone</code>に<code>--recursive</code>フラグを付与するとサブモジュールも併せてクローンできるが、この時点では不要</p>
</li>
<li>
<p>サンプル用のサブモジュールとその設定を削除する</p>
<pre><code class="language-sh">rm -rf user-repositories/*/
rm .gitmodules
git add .
git commit -m &quot;deinit submodules&quot;
</code></pre>
</li>
<li>
<p>解析対象のGitリポジトリをサブモジュールとして追加する</p>
<pre><code class="language-sh">git submodule add https://github.com/&lt;user&gt;/&lt;name&gt; user-repositories/&lt;name&gt;
</code></pre>
</li>
<li>
<p>サブモジュールをクローンするためにトークンが必要であれば、<code>.github/workflows/auto-update.yml</code>でのチェックアウトのステップにトークンを設定する</p>
<pre><code class="language-yml">- name: Checkout
  uses: actions/checkout@v4
  with:
    token: ${{ secrets.GITHUB_ACCESS_TOKEN }}
    submodules: true
</code></pre>
</li>
<li>
<p><code>package.json</code>の<code>name</code>を任意の名前に変更する。これが<code>README.md</code>のタイトルになる</p>
</li>
<li>
<p>解析対象のモジュールをインストールする</p>
<pre><code class="language-sh">npm remove antd
npm install @plaidev/sour-react
</code></pre>
</li>
<li>
<p><code>scripts/config.ts</code>の設定を書き換える</p>
<ul>
<li><code>targetModuleName</code>は解析対象のモジュール名。この記事で言うところの<code>@plaidev/sour-react</code></li>
<li><code>targetModuleTitle</code>は解析対象のモジュールのタイトル。<code>README.md</code>に表示される。<code>targetModuleName</code>と同じでも構わない</li>
<li><code>targetModuleUrl</code>は解析対象のモジュールのURL。<code>README.md</code>からリンクされる</li>
<li><code>userPackageNameMap</code>はプロダクトの表示名。対象となるプロダクトのディレクトリへのパスと、その名前の対応関係を設定する。未設定の場合は、ディレクトリのパスが表示名として出力される。ビルドを実行することで対象ディレクトリを把握できるので、一度ビルドを行ってからの方が設定しやすい</li>
</ul>
</li>
<li>
<p><code>.github/workflows/auto-update.yml</code>でのインストールのステップで、解析対象のモジュールをアップデートするように設定する</p>
<pre><code class="language-yml">- name: Install dependencies
  run: |
    npm ci
    npm install @plaidev/sour-react@latest
</code></pre>
</li>
<li>
<p>依存関係をインストールしてからビルドする。プロダクトの表示名が未設定の場合はディレクトリのパスが出力されるので、別の表示名にしたければ<code>scripts/config.ts</code>で設定する</p>
<pre><code class="language-sh">npm ci
npm run build
</code></pre>
</li>
<li>
<p><code>.github/workflows/auto-update.yml</code>でコメントアウトされた<code>schedule</code>を有効化する</p>
<pre><code class="language-yml">on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:
</code></pre>
</li>
<li>
<p>変更をコミットしてプッシュする</p>
</li>
</ol>
<h2>最後に</h2>
<p>ライブラリの使用状況を解析する仕組みについては、ライブラリを開発するエンジニアであれば一度は考えたことがあるかと思いますが、開発コストや実現可能性などの問題により、実際に作成された例はあまり多くはないのではないでしょうか。</p>
<p>今回作成したこの仕組みをオープンソースとして公開することで、みなさんの開発現場においても、使用状況の可視化を実現するための助けになれば幸いです。</p>


プロダクト全体のソースコードを解析して、提供しているモジュールおよびそれを使用しているプロダクトごとに個別に自動集計する仕組みとその実装方法について解説します。

ソースコードを解析して社内向けUIライブラリの使用状況を自動で集計する