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

<html><head></head><body><h1 id="はじめに">はじめに</h1>
<p>こんにちは、桂田一輝と申します。2024年8月から10月の3ヶ月間、プレイドのEcosystemチームでソフトウェアエンジニアとしてインターンシップを行いました。インターンを通じて、Ecosystemチームが開発しているKARTE Craftというプロダクトの改善業務に携わってきました。そこで得られた学びについてお伝えします。</p>
<h1 id="EcosystemチームとKARTE Craftについて">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/" target="_blank" rel="noreferrer">https://craft.developers.karte.io/get-started/about-karte-craft/</a></p>
<p>今回のインターンで私が担当したのは、KARTE Craftの <strong>Craft Functions</strong> という機能の改善でした。</p>
<h2 id="Craft Functionsとは">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" target="_blank" rel="noreferrer">https://craft.developers.karte.io/get-started/about-karte-craft/#craft-functionsの仕組み</a></p>
<p>Craft Functionsで実行するプログラムを<strong>ファンクション</strong>と呼びます。ファンクションの作成時には、インフラの構築・運用は不要で、AIによるサポートも搭載されているため、手軽に作成することができます。</p>
<h1 id="インターンで行ったタスク">インターンで行ったタスク</h1>
<p>インターン期間中は、大きく3つのタスクに取り組みました。配属後の初めのタスクとして、KARTEのサーバーインフラを理解するための設定変更を行いました。その後は、Craft Functionsの改善として、次の2つのタスクを担当しました。</p>
<ul>
<li>ファンクションが意図せず操作不能となる事象を回避するためのジョブ機能の構築</li>
<li>ファンクション一覧をタイプ別に取得するサービス間APIの作成</li>
</ul>
<p>今回は、上記の2つのタスクを紹介し、そこから得られた学びを説明します。</p>
<h2 id="タスク1: ファンクションが意図せず操作不能となる事象を回避するためのジョブ機能の構築">タスク1: ファンクションが意図せず操作不能となる事象を回避するためのジョブ機能の構築</h2>
<p>最初のタスクは、作成したファンクションの状態管理に関する課題を解決するものです。ファンクションの作成処理の流れ、課題、そして解決方法を説明します。</p>
<h3 id="課題">課題</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 id="解決策">解決策</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 id="実装">実装</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 hljs"><span class="hljs-keyword">const</span> argv = <span class="hljs-title function_">minimist</span>(process.<span class="hljs-property">argv</span>.<span class="hljs-title function_">slice</span>(<span class="hljs-number">2</span>));
<span class="hljs-keyword">const</span> { jobname } = argv;

<span class="hljs-title function_">import</span>(<span class="hljs-string">`./path/to/<span class="hljs-subst">${jobname}</span>`</span>)
  .<span class="hljs-title function_">then</span>(<span class="hljs-keyword">async</span> cronjob =&gt; {
    <span class="hljs-keyword">await</span> cronjob.<span class="hljs-title function_">default</span>(argv);
  })
  .<span class="hljs-title function_">catch</span>(<span class="hljs-function"><span class="hljs-params">err</span> =&gt;</span> {
    logger.<span class="hljs-title function_">error</span>(err);
    process.<span class="hljs-title function_">exit</span>(<span class="hljs-number">1</span>);
  });
</code></pre>
<p><code>jobname</code>は引数としてプログラムを実行する際に渡します。今回はCronJobリソースの&nbsp;<code>command</code>&nbsp;属性でコンテナ起動時に渡すようにしました。これにより、スケジュールの異なる複数のプログラムを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 id="得られた学び">得られた学び</h2>
<p>このタスクでは、KARTE Craft上にジョブシステムを作成しました。タスクを通じて次の学びを得られました。</p>
<ul>
<li>インフラ〜バックエンドを跨いだ機能の実装
<ul>
<li>ジョブ用のプログラムを記述し、それをKubernetesのワークロードとして動かす方法がわかりました。</li>
</ul>
</li>
<li>設計・実装レベルでの取捨選択の方法
<ul>
<li>構成や実装を検討する際に、候補を挙げてその良し悪しを検討することで、より説得力のある設計・実装になることがわかりました。</li>
</ul>
</li>
</ul>
<h2 id="タスク2: ファンクション一覧をタイプ別に取得するサービス間APIの作成">タスク2: ファンクション一覧をタイプ別に取得するサービス間APIの作成</h2>
<p>次に取り組んだのが、KARTEのHook機能経由でファンクションを起動する設定をする際に必要となる、ファンクション一覧APIの改善タスクでした。マイクロサービス間の通信に必要なAPIを作成し、サービス間通信の実装を行いました。</p>
<h3 id="Hook v2">Hook v2</h3>
<p>Hook v2は、KARTE内で発生した特定の変更や追加などの変化をトリガーとして、そのデータをリアルタイムで外部のシステムに送信する機能です。</p>
<p><a href="https://developers.karte.io/reference/about-hook-v2" target="_blank" rel="noreferrer">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" target="_blank" rel="noreferrer">https://solution.karte.io/blog/2023/06/craft-webhook/index.html</a></p>
<h3 id="課題">課題</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&amp;key=878c5bef402f0b2911bf6d4ce6261abd" target="_blank" rel="noreferrer">ファンクションのタイプ</a></div></div><script async="" src="//cdn.iframe.ly/embed.js" charset="utf-8"></script>
<p>Hook v2において指定できるファンクションはイベント駆動タイプのみです。しかし、管理画面上はHTTPタイプ、イベント駆動タイプの両方が指定できるようになっていました。この相違を解決するため、管理画面上において指定できるファンクションからHTTPタイプを除き、イベント駆動タイプのみを表示する必要がありました。</p>
<h3 id="解決策と実装">解決策と実装</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 id="得られた学び">得られた学び</h2>
<p>このタスクでは、マイクロサービス間の通信を行う仕組みを理解し、その改善を実施しました。タスクを通じて、次の学びが得られました。</p>
<ul>
<li>本番稼働するシステム上で、どのようにマイクロサービスが稼働しているかの全体像が掴めました。</li>
<li>インターフェース仕様（OpenAPI Spec）を活用してクライアントを自動生成することで、良い開発体験を提供できることがわかりました。</li>
</ul>
<h1 id="あとがき">あとがき</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&amp;url=https%3A%2F%2Frecruit.plaid.co.jp%2Frequisitions%2Fnew-graduate-engineer&amp;key=878c5bef402f0b2911bf6d4ce6261abd" target="_blank" rel="noreferrer">新卒採用 &amp; インターン (Product) | 募集ポジション | 株式会社プレイド</a></div></div><script async="" src="//cdn.iframe.ly/embed.js" charset="utf-8"></script></body></html>

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

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