JJUG CCC 2021 Fall 登壇資料
変わりゆくAPI連携仕様との付き合い方JJUG CCC 2021 Fall太田拓也
View Slide
自己紹介● 太田拓也● 株式会社ラクス● HR Tech SaaSの開発● Spring / Vue.js / Docker / AWS● 最近はプライベートでReact, Firebaseを触ってます22
目次● API連携してますか?○ API連携のメリット/デメリット● デメリットとどう付き合うか○ 前提知識○ 具体例と対策■ 仕様変更■ テスト■ モデルの違い● まとめ33
API連携してますか?44
API連携のメリット/デメリット● メリット:開発コストの削減○ 既に開発された機能を利用することで、自社開発しなくて済む● デメリット:連携先システムへの依存○ 障害の影響を受ける○ 仕様変更の影響を受ける○ テストしづらい○ 同じようなドメインでもモデルが異なる可能性がある55
API連携のメリット/デメリット● メリット:開発コストの削減○ 既に開発された機能を利用することで、自社開発しなくて済む● デメリット:連携先システムへの依存○ 障害の影響を受ける○ 仕様変更の影響を受ける○ テストしづらい○ 同じようなドメインでもモデルが異なる可能性がある66
補足:ドメインとモデル77
用語● ドメイン駆動設計の用語と解説(抜粋版)○ https://qiita.com/nunulk/items/84438605eb4d75dbef00● ドメイン駆動設計における「良いモデル」と「悪いモデル」とは○ https://logmi.jp/tech/articles/322831● wikipedia「ドメイン駆動設計」○ https://ja.wikipedia.org/wiki/%E3%83%89%E3%83%A1%E3%82%A4%E3%83%B3%E9%A7%86%E5%8B%95%E8%A8%AD%E8%A8%88用語 意味ドメイン システムが解決しようとしている問題領域モデル 問題解決のために、特定の物事の側面を抽象化したものドメイン駆動設計(DDD) ソフトウェアの設計手法であり、「複雑なドメインの設計は、モデルベースで行うべき」であり、また「大半のソフトウェアプロジェクトでは、システムを実装するための特定の技術ではなく、ドメインそのものとドメインのロジックに焦点を置くべき」であるとする。この名称は、 Eric Evans が同名の著作で用いた88
同じようなドメインを対象としたモデルでも...● 映画館のチケット料金ドメインモデリングの例○ https://togetter.com/li/1378684● モデリングによって、概念の構成単位や用語が異なる● システムが異なれば、当然モデルも異なる99
(再掲)API連携のメリット/デメリット● メリット:開発コストの削減○ 既に開発された機能を利用することで、自社開発しなくて済む● デメリット:連携先システムへの依存○ 障害の影響を受ける○ 仕様変更の影響を受ける○ テストしづらい○ 同じようなドメインでもモデルが異なる可能性がある1010
(再掲)API連携のメリット/デメリット● メリット:開発コストの削減○ 既に開発された機能を利用することで、自社開発しなくて済む● デメリット:連携先システムへの依存○ 障害の影響を受ける○ 仕様変更の影響を受ける○ テストしづらい○ 同じようなドメインでもモデルが異なる可能性がある1111
デメリットとどう付き合うか1212
前提知識1313
サービスについて● 人事労務管理のサービス○ 従業員情報を収集し、届出書を作成できる○ 主に電子申請部分でAPI連携を利用○ 初期リリース時には、電子申請機能は存在しなかった● AWS ECS, RDS, S3を使ったシンプルな構成○ 今回のテーマには直接関係しないので、図などは省略1414
チェックリスト 行政への提出 従業員情報の更新 チェックリスト 届出書の作成 チェックリスト 紙 電子申請 社内手続き 社内申請 参照入社手続き 退職手続き ... 参照届出書 提出方法 モデル● 社内手続きで作られたデータが届出書の作成に使われる● 紙と電子申請のデータは同じデータを元に作成されるデータの流れ1515
具体例1616
ケース1:仕様変更1717
仕様変更● 届出書の性質上、法改正によって不定期に仕様が変わりうる○ 項目が増えたり、減ったり、入力ルールが変わったり...● APIの仕様も連動して変わることが多い○ ほとんどの場合、猶予期間が設けられるが、いずれにしても期限が存在する● 物理的な届出書様式と、APIにおける電子申請の様式は1:1で対応しているわけではない1818
● 値オブジェクトで再利用性を高める対策1919
● 値オブジェクトとは○ たとえば「色」や「量」のように、その属性だけが重要で、アイデンティティを考えることに意味のないオブジェクトもある。そうしたオブジェクトは、値オブジェクトに分類する。値オブジェクトとは、事物の性質を表現するものである。値オブジェクトは状態を変更できないもの(immutable)として扱う値オブジェクトで再利用性を高める● DDD難民に捧げる Domain-Driven Designのエッセンス 第2回 DDDの基礎と実践○ https://www.ogis-ri.co.jp/otc/hiroba/technical/DDDEssence/chap2.html2020
実装イメージ2121
● 再利用性が高まり、仕様変更に強くなる● ドメインの知識がコードに表現される○ 先ほどの例では「郵便番号はハイフンつなぎで出力」という出力仕様が該当値オブジェクトを使うと2222
ケース2:テスト2323
テスト● 連携先がメンテ中だとCIがFailする● バッチ処理を受け付けるAPIがあり、真面目にテストしようとすると、連携先の処理結果まで確認する必要がある○ 結果がわかるまで15分前後かかる○ リードタイム大○ 事前のデータ準備を間違えたりすると、大きな手戻りに2424
対策● APIとの通信を責務とするクラスをインターフェースとして作成し、設定によって実装をモックと切り替えられるようにする○ Springのapplication.ymlの仕組みで実装● システム間連携レベルの自動テストについては、モックを使わずに低頻度で実行するようにし、極力リードタイムを抑えた形での継続的な品質担保を行う2525
実装イメージ2626
実装イメージ2727
モックを使うと● CIがメンテの状況に左右されない● テストケースに合わせて、APIの動作をこちらで規定できる○ テストしやすい2828
異なる性質のテストを組み合わせることで● コストを極力抑えつつ、最低限の品質を担保できる○ 副次的には連携先の意図せぬデグレを検知できたり2929
ケース3:モデルの違い3030
モデルの違いどちらの用語か 用語 意味自サービス 社内手続き 社内申請で回収した情報から届出書を作成すること自サービス 社内申請 従業員が人事労務に情報を提出すること自サービス 届出書 行政へ提出するための書類自サービス 電子申請の提出 届出書を行政に電子申請すること連携先システム 申請書 各行政手続において、申請・届出事項を記入する様式のこと特に〇〇(連携先システム名)においては、申請・届出事項を格納するXML様式のことを申請書と呼ぶ連携先システム 手続 各行政手続に対応した電子申請の構成単位連携先システム 一括申請 1件以上の手続を電子申請すること※連携先システムについては、仕様書などから類推したものを含む3131
チェックリスト 行政への提出 従業員情報の更新 チェックリスト 届出書の作成 チェックリスト 紙 電子申請 社内手続き 社内申請 参照入社手続き 退職手続き ... 参照届出書 提出方法 (再掲)モデルデータの流れ3232
対策● 腐敗防止層を設ける● 腐敗防止層とは○ DDDの文脈で語られる、戦略的設計プラクティス「コンテキストマップ」のパターンの一つ○ 既存システムと新たなシステムとの変換層を設けて、両者のドメインモデルを独立させる3333
自サービス連携先システム実装イメージ3434腐敗防止層Id UserId
腐敗防止層を使うと● ややこしい用語を一定のモジュールに閉じ込めることができる○ 混乱を防ぐ● 用語の対応関係が整理できる3535
まとめ3636
まとめ● API連携にはメリットもデメリットもある● デメリットとうまく付き合うには、以下のような解決策がある○ 値オブジェクト○ インターフェース + テストの組み合わせ○ 腐敗防止層● うまく活用してメリットを享受しよう!3737