https://rindrics.com/tags/postmortem/ Postmortem Hugo -- gohugo.io en Tue, 14 Jul 2026 00:00:00 +0900 https://rindrics.com/posts/stock-assess-api-contract-postmortem/ Tue, 14 Jul 2026 00:00:00 +0900 https://rindrics.com/posts/stock-assess-api-contract-postmortem/ <p>良かれと思って進めていた設計が、とんでもなく悪かったのでメモ。</p> <p>ここのところ取り組んでいる frasyr のモノリスサービス化について、ひどい設計ミスをしていた（下記は前回記事）。 <div class="card"> <a href="https://rindrics.com/posts/stock-assess-api-contract/" target="_blank" rel="noopener noreferrer" class="card-link"> <div class="card-content"> <h4 class="card-title">API 契約駆動で開発できるようにした | rindrics.com</h4> <span class="card-url">https://rindrics.com/posts/stock-assess-api-contract/</span> </div> </a> </div> </p> <h2 id="懺悔">懺悔</h2> <p>ちょうど contract test のしくみを導入したところだったので、その扱いにばかり注意が行ってしまっていたのも要因かもしれない。 そもそもペイロードの構造が完全に悪手だった。</p> <p><a href="../stock-assess-api-contract/">前記事</a>時点で設計したペイロードはこうだった:</p> <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#268bd2">example</span>: </span></span><span style="display:flex;"><span> <span style="color:#268bd2">data</span>: </span></span><span style="display:flex;"><span> <span style="color:#268bd2">caa_url</span>: https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_caa.csv </span></span><span style="display:flex;"><span> <span style="color:#268bd2">waa_url</span>: https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_waa.csv </span></span><span style="display:flex;"><span> <span style="color:#268bd2">maa_url</span>: https://raw.githubusercontent.com/ichimomo/frasyr/dev/data-raw/ex2_maa.csv </span></span><span style="display:flex;"><span> <span style="color:#268bd2">params</span>: </span></span><span style="display:flex;"><span> <span style="color:#268bd2">m</span>: <span style="color:#2aa198">0.5</span> </span></span><span style="display:flex;"><span> <span style="color:#268bd2">fc_year</span>: [<span style="color:#2aa198">2015</span>, <span style="color:#2aa198">2016</span>, <span style="color:#2aa198">2017</span>] </span></span><span style="display:flex;"><span> <span style="color:#268bd2">tf_year</span>: [<span style="color:#2aa198">2015</span>, <span style="color:#2aa198">2016</span>] </span></span><span style="display:flex;"><span> <span style="color:#268bd2">term_f</span>: max </span></span><span style="display:flex;"><span> <span style="color:#268bd2">stat_tf</span>: mean </span></span><span style="display:flex;"><span> <span style="color:#268bd2">pope</span>: <span style="color:#cb4b16">true</span> </span></span><span style="display:flex;"><span> <span style="color:#268bd2">tune</span>: <span style="color:#cb4b16">false</span> </span></span><span style="display:flex;"><span> <span style="color:#268bd2">p_init</span>: <span style="color:#2aa198">0.5</span> </span></span></code></pre></div><p>ここまでパラメータが多いと、API の境界における入力検証がいくらなんでも重すぎる。 frasyr の <code>vpa()</code> をラップしていたとしても、API は独立して設計できるはずだ。</p> <p>本来あるべきペイロードは、こうではないか<sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup>:</p> <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#268bd2">example</span>: </span></span><span style="display:flex;"><span> <span style="color:#268bd2">dataSetVersion</span>: &lt;version&gt; </span></span><span style="display:flex;"><span> <span style="color:#268bd2">parameterSetVersion</span>: &lt;version&gt; </span></span></code></pre></div><p>計算に必要な入力一式を、あらかじめ登録されたリソースへの参照に畳んでおき、ペイロードはその参照だけを受け取る。 リソースの ID を参照してもいいが、資源評価の監査性・再現可能性を考えるとバージョンみたいなものを参照したほうがよい気がする。</p> <h2 id="気づいたこと">気づいたこと</h2> <p>ペイロードがここまで内部処理と疎結合になると、contract test で叩くべき異常系がほとんど無いことに気づく。 まして前回やっていたような、ドメイン的な要件まで染み出してしまっていた contract test は、責務の整理ができていないことの表れだと思う。</p> <p>ところで、<code>dataSetVersion</code> や <code>parameterSetVersion</code> が手に入るまでには、当然ながら踏んでおくべきユースケースがいくつかあるはずだ。 caa や waa を登録し、それらを組み合わせてひとつの入力セットにする。 データの値を更新したら version が更新される。 これらは計算の再現性の確保には不可欠だが、計算サービスの責務ではない。</p> <p>ということで、data service のような独立したサービスが必要に思われる。 現時点で考えているユースケースは例えば下記のような感じ:</p> <table> <thead> <tr> <th style="text-align: left">リクエスト</th> <th style="text-align: left">レスポンス</th> <th style="text-align: left">備考</th> </tr> </thead> <tbody> <tr> <td style="text-align: left">データ要素（caa、waa、maa など）の登録</td> <td style="text-align: left"><code>dataVersion</code></td> <td style="text-align: left">エンドユーザーからみた更新処理も含む</td> </tr> <tr> <td style="text-align: left">複数の登録済みデータを組み合わせてデータセットを作る</td> <td style="text-align: left"><code>dataSetVersion</code></td> <td></td> </tr> <tr> <td style="text-align: left">パラメータセットを登録する</td> <td style="text-align: left"><code>parameterSetVersion</code></td> <td></td> </tr> <tr> <td style="text-align: left">パラメータセットのパラメータを更新する</td> <td style="text-align: left"><code>parameterSetVersion</code></td> <td></td> </tr> </tbody> </table> <p>データについては「データ要素」と呼べるようなものの単位で登録できてほしいが、一方パラメータセットについては「パラメータ」の単位で登録してもあまり意味がないような気がする。</p> <p>ちなみに、ここで示したユースケースはあくまでも data service のクライアントから見たユースケースであって、資源評価アプリケーションのエンドユーザーの体験と一致するとは限らない。 実際、資源計算したいユーザーは、パラメータセットなるものを &ldquo;登録&rdquo; するように言われたら不満に思うだろう。 考えられるユーザーの体験の例としては、画面に各パラメータを入力して「VPA を実行」を押すと、ユーザーには見えない背後でパラメータセットが登録され、発行された <code>parameterSetVersion</code> を参照して VPA job がリクエストされる、といったものが考えられる。</p> <p>もう一つ、最近 DOP（Data Oriented Programming）について知ったので、不変性の文脈でメモしておくと、エンドユーザーが登録済みデータの「更新」のつもりで実施した操作も、data service では新データの登録と新バージョン発行として扱いたい。 もちろん、エンドユーザーには更新処理に見せかけていい。</p> <h2 id="学んだこと">学んだこと</h2> <ul> <li>内部的に利用している処理のシグネチャと、自分が設計する API は独立して設計してよい</li> <li>ドメイン要件を API 契約に過結合させてはならない</li> <li>API のユースケースとエンドユーザーの体験は必ずしも一致しない</li> </ul> <div class="footnotes" role="doc-endnotes"> <hr> <ol> <li id="fn:1"> <p><code>type: &quot;vpa&quot;</code> のように、エンドポイントを分けずに計算タイプを受け取る設計もあり得る&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> </li> </ol> </div>