Upgrade to Pro — share decks privately, control downloads, hide ads and more …

変わりゆくAPI連携仕様との付き合い方 / Good practice of using API

Logy
November 18, 2021

変わりゆくAPI連携仕様との付き合い方 / Good practice of using API

JJUG CCC 2021 Fall 登壇資料

Logy

November 18, 2021
Tweet

More Decks by Logy

Other Decks in Programming

Transcript

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

    View Slide

  2. 自己紹介
    ● 太田拓也
    ● 株式会社ラクス
    ● HR Tech SaaSの開発
    ● Spring / Vue.js / Docker / AWS
    ● 最近はプライベートでReact, Firebaseを触ってます
    22

    View Slide

  3. 目次
    ● API連携してますか?
    ○ API連携のメリット/デメリット
    ● デメリットとどう付き合うか
    ○ 前提知識
    ○ 具体例と対策
    ■ 仕様変更
    ■ テスト
    ■ モデルの違い
    ● まとめ
    33

    View Slide

  4. API連携してますか?
    44

    View Slide

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

    View Slide

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

    View Slide

  7. 補足:ドメインとモデル
    77

    View Slide

  8. 用語
    ● ドメイン駆動設計の用語と解説(抜粋版)
    ○ 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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  13. 前提知識
    13
    13

    View Slide

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

    View Slide

  15. チェックリスト 

    行政への提出 

    従業員情報の更新 

    チェックリスト 

    届出書の作成 

    チェックリスト 

    紙
 電子申請

    社内手続き 

    社内申請

    参照
    入社手続き 

    退職手続き 

    ...

    参照
    届出書

    提出方法

    モデル
    ● 社内手続きで作られたデータ
    が届出書の作成に使われる
    ● 紙と電子申請のデータは同じ
    データを元に作成される
    データの流れ
    15
    15

    View Slide

  16. 具体例
    16
    16

    View Slide

  17. ケース1:仕様変更
    17
    17

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  21. 実装イメージ
    21
    21

    View Slide

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

    View Slide

  23. ケース2:テスト
    23
    23

    View Slide

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

    View Slide

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

    View Slide

  26. 実装イメージ
    26
    26

    View Slide

  27. 実装イメージ
    27
    27

    View Slide

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

    View Slide

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

    View Slide

  30. ケース3:モデルの違い
    30
    30

    View Slide

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

    View Slide

  32. チェックリスト 

    行政への提出 

    従業員情報の更新 

    チェックリスト 

    届出書の作成 

    チェックリスト 

    紙
 電子申請

    社内手続き 

    社内申請

    参照
    入社手続き 

    退職手続き 

    ...

    参照
    届出書

    提出方法

    (再掲)モデル
    データの流れ
    32
    32

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  36. まとめ
    36
    36

    View Slide

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

    View Slide