変わりゆくAPI連携仕様との付き合い方 JJUG CCC 2021 Fall 太田拓也

自己紹介 ● 太田拓也 ● 株式会社ラクス ● 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%E 5%8B%95%E8%A8%AD%E8%A8%88 用語 意味 ドメイン システムが解決しようとしている問題領域 モデル 問題解決のために、特定の物事の側面を抽象化したもの ドメイン駆動設計（DDD） ソフトウェアの設計手法であり、「複雑なドメインの設計は、モデルベースで行 うべき」であり、また「大半のソフトウェアプロジェクトでは、システムを実装する ための特定の技術ではなく、ドメインそのものとドメインのロジックに焦点を置 くべき」であるとする。この名称は、 Eric Evans が同名の著作で用いた 88

同じようなドメインを対象としたモデルでも... ● 映画館のチケット料金ドメインモデリングの例 ○ https://togetter.com/li/1378684 ● モデリングによって、概念の構成単位や用語が異なる ● システムが異なれば、当然モデルも異なる 99

（再掲）API連携のメリット/デメリット ● メリット：開発コストの削減 ○ 既に開発された機能を利用することで、自社開発しなくて済む ● デメリット：連携先システムへの依存 ○ 障害の影響を受ける ○ 仕様変更の影響を受ける ○ テストしづらい ○ 同じようなドメインでもモデルが異なる可能性がある 10 10

（再掲）API連携のメリット/デメリット ● メリット：開発コストの削減 ○ 既に開発された機能を利用することで、自社開発しなくて済む ● デメリット：連携先システムへの依存 ○ 障害の影響を受ける ○ 仕様変更の影響を受ける ○ テストしづらい ○ 同じようなドメインでもモデルが異なる可能性がある 11 11

デメリットとどう付き合うか 12 12

前提知識 13 13

サービスについて ● 人事労務管理のサービス ○ 従業員情報を収集し、届出書を作成できる ○ 主に電子申請部分でAPI連携を利用 ○ 初期リリース時には、電子申請機能は存在しなかった ● AWS ECS, RDS, S3を使ったシンプルな構成 ○ 今回のテーマには直接関係しないので、図などは省略 14 14

チェックリスト 
 行政への提出 
 従業員情報の更新 
 チェックリスト 
 届出書の作成 
 チェックリスト 
 紙
 電子申請
 社内手続き 
 社内申請
 参照 入社手続き 
 退職手続き 
 ...
 参照 届出書
 提出方法
 モデル ● 社内手続きで作られたデータ が届出書の作成に使われる ● 紙と電子申請のデータは同じ データを元に作成される データの流れ 15 15

具体例 16 16

ケース１：仕様変更 17 17

仕様変更 ● 届出書の性質上、法改正によって不定期に仕様が変わりうる ○ 項目が増えたり、減ったり、入力ルールが変わったり... ● APIの仕様も連動して変わることが多い ○ ほとんどの場合、猶予期間が設けられるが、いずれにしても期限が存 在する ● 物理的な届出書様式と、APIにおける電子申請の様式は1：1で対応してい るわけではない 18 18

● 値オブジェクトで再利用性を高める 対策 19 19

● 値オブジェクトとは ○ たとえば「色」や「量」のように、その属性だけが重要で、アイデンティ ティを考えることに意味のないオブジェクトもある。そうしたオブジェクト は、値オブジェクトに分類する。値オブジェクトとは、事物の性質を表 現するものである。値オブジェクトは状態を変更できないもの （immutable）として扱う 値オブジェクトで再利用性を高める ● DDD難民に捧げる Domain-Driven Designのエッセンス 第2回　DDDの基礎と実践 ○ https://www.ogis-ri.co.jp/otc/hiroba/technical/DDDEssence/chap2.html 20 20

実装イメージ 21 21

● 再利用性が高まり、仕様変更に強くなる ● ドメインの知識がコードに表現される ○ 先ほどの例では「郵便番号はハイフンつなぎで出力」という出力仕様が該当 値オブジェクトを使うと 22 22

ケース２：テスト 23 23

テスト ● 連携先がメンテ中だとCIがFailする ● バッチ処理を受け付けるAPIがあり、真面目にテストしようとすると、連携先の処理 結果まで確認する必要がある ○ 結果がわかるまで15分前後かかる ○ リードタイム大 ○ 事前のデータ準備を間違えたりすると、大きな手戻りに 24 24

対策 ● APIとの通信を責務とするクラスをインターフェースとして作成し、設定に よって実装をモックと切り替えられるようにする ○ Springのapplication.ymlの仕組みで実装 ● システム間連携レベルの自動テストについては、モックを使わずに低頻度 で実行するようにし、極力リードタイムを抑えた形での継続的な品質担保を 行う 25 25

実装イメージ 26 26

実装イメージ 27 27

モックを使うと ● CIがメンテの状況に左右されない ● テストケースに合わせて、APIの動作をこちらで規定できる ○ テストしやすい 28 28

異なる性質のテストを組み合わせることで ● コストを極力抑えつつ、最低限の品質を担保できる ○ 副次的には連携先の意図せぬデグレを検知できたり 29 29

ケース３：モデルの違い 30 30

モデルの違い どちらの用語か 用語 意味 自サービス 社内手続き 社内申請で回収した情報から届出書を作成すること 自サービス 社内申請 従業員が人事労務に情報を提出すること 自サービス 届出書 行政へ提出するための書類 自サービス 電子申請の提出 届出書を行政に電子申請すること 連携先システム 申請書 各行政手続において、申請・届出事項を記入する様式のこと 特に〇〇（連携先システム名）においては、申請・届出事項を格納する XML様式のことを申請書と呼ぶ 連携先システム 手続 各行政手続に対応した電子申請の構成単位 連携先システム 一括申請 1件以上の手続を電子申請すること ※連携先システムについては、仕様書などから類推したものを含む 31 31

チェックリスト 
 行政への提出 
 従業員情報の更新 
 チェックリスト 
 届出書の作成 
 チェックリスト 
 紙
 電子申請
 社内手続き 
 社内申請
 参照 入社手続き 
 退職手続き 
 ...
 参照 届出書
 提出方法
 （再掲）モデル データの流れ 32 32

対策 ● 腐敗防止層を設ける ● 腐敗防止層とは ○ DDDの文脈で語られる、戦略的設計プラクティス「コンテキストマップ」の パターンの一つ ○ 既存システムと新たなシステムとの変換層を設けて、両者のドメインモデ ルを独立させる 33 33

自サービス 連携先システム 実装イメージ 34 34 腐敗防止層 Id UserId

腐敗防止層を使うと ● ややこしい用語を一定のモジュールに閉じ込めることができる ○ 混乱を防ぐ ● 用語の対応関係が整理できる 35 35

まとめ 36 36

まとめ ● API連携にはメリットもデメリットもある ● デメリットとうまく付き合うには、以下のような解決策がある ○ 値オブジェクト ○ インターフェース + テストの組み合わせ ○ 腐敗防止層 ● うまく活用してメリットを享受しよう！ 37 37