仕事でWeb API開発するときに考えていること / 技育CAMPアカデミア2023

2023年5月10日(水) サポーターズ主催「技育CAMPアカデミア」で開催されたCARTA HOLDINGSセッションの発表資料です。

・登壇者
株式会社CARTA HOLDINGS
所属: 株式会社fluct アドプラットホーム事業本部 データエンジニアリングチーム
名前: 鈴木 進也 (すずき しんや)
twitterアカウント: @YangYang_pareto
自己紹介: fluctというアドテクの会社でWeb API開発をしたりデータエンジニアリングをしています。三度の飯よりキーボードが好きです。

Transcript

1. 仕事でWeb API開発するときに考えているこ と 技育CAMP 2023 CARTA HOLDINGS Inc.
2. • yanyan • 新卒3年目 • 株式会社fluct アドプラットフォーム事業本部 ◦ データエンジニアリングや API開発してます 自己紹介 CARTA HOLDINGS Inc.
3. 今日のサンプルコードは Githubにおいてあります https://github.com/shinya-ml/geeksai-backend-study サンプルプログラム CARTA HOLDINGS Inc.
4. ざっくりしたWebアプリケーションの構成 CARTA HOLDINGS Inc.
5. ざっくりしたWebアプリケーションの構成 CARTA HOLDINGS Inc. この部分を作るときに考えていることを話します
6. 認知負荷の話 01 アプリケーションのアーキテクチャの 話 02 APIの設計について 03 テストの話 04 CARTA HOLDINGS Inc. 思想を言語化する 04
7. 認知負荷の話
8. 人が学習する際にかかる記憶領域に対する負荷 • 開発には様々な認知負荷がかかる ◦ コードの意図を読み取る、アーキテクチャの理解 etc… • A Philosophy of Software Design では、ソフトウェアの複雑性が増大している兆候の一つとしてあ げられている • 自分は普段の開発で認知負荷が高くなりすぎていないか？を気にしている 認知負荷とは CARTA HOLDINGS Inc.
9. • 認知負荷が高いものは理解するのが難しい • 理解が不十分なままコードの修正や書き足しをすると、 より複雑度が高まってしまう ◦ 認知負荷の高いコードは、さらなる認知負荷の上昇をもたらす • 規模が大きくなるにつれて複雑性の増加は避けられない ◦ 工夫して複雑になりすぎないようにすることはできる なぜ認知負荷を気にしているのか CARTA HOLDINGS Inc.
10. アーキテクチャの話
11. 実際はインフラの構成とかもスコープだが今回はアプリケーションコードの構造の話 • アプリケーションの実装をレイヤーごとに分けて整理する • レイヤーに分けると何が嬉しい？ ◦ 関心事の分離 ◦ 依存関係の整理 1からコードを書いていくときに、どうやってレイヤー構造を考えていくか ここでいうアーキテクチャとは CARTA HOLDINGS Inc.
12. • レイヤードアーキテクチャ • ヘキサゴナルアーキテクチャ • オニオンアーキテクチャ • クリーンアーキテクチャ • etc… よく目にするアーキテクチャたち CARTA HOLDINGS Inc. [画像の出典] Ready for changes with Hexagonal Architecture, Clean Architecture
13. いかなるアプリケーションに対しても最適なアーキテクチャなどない 彼らは銀の弾丸ではない CARTA HOLDINGS Inc.
14. • そのアプリケーションにとって妥当なアーキテクチャは 開発が進むにつれて変化していく • 小規模な段階から壮大なアーキテクチャにすると大体辛い ◦ ほとんど何もしてないレイヤーが生まれる ◦ 意味のない抽象化 (具体的な実装が一つしか無い ) ◦ なぜそのレイヤーが存在しているのかわからない = 認知負荷が高い 必要なときに必要な変更をする CARTA HOLDINGS Inc.
15. • handler: HTTP リクエストを受けてレスポンス返す • repository: DBとやりとりする • entity: アプリケーションで扱うオブジェクトを定義する 例えば CARTA HOLDINGS Inc. handler repository entity DB 依存の流れ 単にCRUDするだけならこれくらい素朴な構成でもよい
16. • ビジネスロジックを書く層がほしい！ ◦ 必要になったら足せば良い 扱う関心事が増えた CARTA HOLDINGS Inc. handler repository entity DB usecase
17. • repositoryに依存する層のユニットテストをしたい ◦ repositoryの部分はフェイクに差し替えたい • インターフェースに依存する形にする 抽象化したい CARTA HOLDINGS Inc. handler repository interface repository implementation repository mock entity DB
18. 1. 関心事の分離 2. 依存の流れを1方向にする これらを守りながら、 その時々でベストな設計を模索する 何が大事かは関わる人とかサービスの特性によって変わってくる 依存関係を整理するときに大事なこと CARTA HOLDINGS Inc.
19. • 関心事とは ◦ 自分が主に取り扱おうとしているトピック、対象 ◦ e.g.) DBとのやりとり、HTTP req/resについて etc… 関心事の分離 CARTA HOLDINGS Inc.
20. • まずはどんな関心事が存在するのか言語化することが大事 • 1レイヤーが複数の関心事を扱わないようにする ◦ e.g.) ファットコントローラー 関心事の分離 CARTA HOLDINGS Inc.
21. • 認知負荷が低い ◦ 触りたい実装がどこにあるか把握しやすい ◦ e.g.) DB周りはrepository層をみればいい • 変更しやすい ◦ どこを修正すればいいか明確 • 壊れたときに直しやすい ◦ どこで壊れたか特定しやすい 各層が１つの関心事だけを扱っていると何が嬉しい？ CARTA HOLDINGS Inc.
22. • レイヤー構造を成すので、レイヤー間に 依存関係が生まれる • 依存とは ◦ 依存される側の知識が依存する側に漏れ出ている状態 ◦ メソッドの呼び出しに必要な引数とか • 依存される側に変更が入ると、する側も影響を受ける ◦ あるモジュールが依存したりされまくったりしている（密結合）と辛い 依存関係 CARTA HOLDINGS Inc.
23. • 依存の向きを交通整理する • 具体的な関心事を扱うレイヤー → 抽象的な関心事を扱うレイヤーという依存の流れを作る ◦ 具体的な関心事: 特定の技術に関すること (DBとかGraphQLとか...) ◦ 抽象的な関心事: アプリケーションが扱うドメインコアなこと (ビジネスロジックとか ...) 依存の流れを1方向にする CARTA HOLDINGS Inc.
24. • サービスのコアとなる部分が特定の技術に依存しない ◦ 変更しやすい • ある技術を差し替えてもサービスのコアには影響しない 具象 → 抽象の向きで依存させる CARTA HOLDINGS Inc.
25. つまり、具体的な知識がビジネスロジックに漏れ出る • e.g.) MySQLの知識がusecase層で必要になる 具体的な関心事が漏洩すると ... • 円の外側に対する変更で内側も影響を受ける • 技術の差し替えが難しくなる 抽象 → 具象という依存があるとどうなる？ CARTA HOLDINGS Inc.
26. • アプリケーションにレイヤー構造を設けることで依存関係が整理される • 関心事を適切に分けよう • 何を守りたいか？を考えながら、必要に応じてアーキテクチャは変化させよう まとめ CARTA HOLDINGS Inc.
27. API設計の話
28. APIをどういう形式で提供するかは、いくつか選択肢がある • REST ◦ リソースベースのURI ◦ JSON形式でデータをやり取りする ◦ 長いこと使われてる • gRPC ◦ Protobuf形式でやり取りする ◦ マイクロサービス間の通信とかで使われてる • GraphQL ◦ クエリ言語 + クエリに対するサーバーサイド実装 ◦ クエリする側が柔軟に欲しいデータを持ってこれる APIのスタイル CARTA HOLDINGS Inc.
29. • ユースケースに応じて使い分けよう ◦ 銀の弾丸などない • GraphQLはRESTの上位互換とか、そんなことはない ◦ RESTのほうがいい場合もある 大前提 CARTA HOLDINGS Inc.
30. • APIの利用者 ◦ 誰が使うんだっけ ◦ どのくらい使われるんだっけ • ユースケースの数 ◦ 利用者が多様でユースケースも様々なんだよねーとか • サービス的になにを重要視するか ◦ APIとしての柔軟性？ ◦ パフォーマンス？ etc… どういう軸で考えるのか CARTA HOLDINGS Inc.
31. • REST ◦ リソースベースでエンドポイントを生やすので、 1つのAPIで色々なユースケースに対応しよう とすると辛くなりがち ◦ 1APIのユースケースが単純ならわかりやすい • GraphQL ◦ クエリによって利用者側が柔軟に欲しいデータを記述できるのでユースケースが多様な場合 に対応しやすい ◦ エラーハンドリングが難しい • gRPC ◦ パフォーマンス重視ならこれかな ◦ 内部向けのAPIかくなら、型もかっちり書けるしよさげ ざっくりとした私の所感 CARTA HOLDINGS Inc.
32. 正しい使い方をするのが簡単で、間違った使い方をするのが難しい • APIを使う側のことを考えて設計する • 適切にドキュメンテーションする • 命名の一貫性 • レスポンスの設計 良いAPIとは？ CARTA HOLDINGS Inc.
33. APIの形式によって気をつけたいことも変わってくる RESTなら... • エンドポイントのURIはわかりやすいか • クエリパラメータやリクエストボディの設計 GraphQLなら... • スキーマ設計 ◦ 命名の一貫性 ◦ nullの使い分け • Production Ready GraphQL という本がおすすめ 例えば CARTA HOLDINGS Inc.
34. テストの話
35. • ユニットテスト ◦ あるモジュール単体の振る舞いに対するテスト • インテグレーションテスト ◦ 複数のモジュールを跨いだテスト ◦ DBのような、アプリケーションの外側とのテストも含む APIサービスに対するテストは色々ある CARTA HOLDINGS Inc.
36. Q. どのテストを書けばいい？ CARTA HOLDINGS Inc.
37. A. 全部書けばいいやん Q. どのテストを書けばいい？ CARTA HOLDINGS Inc.
38. A. 全部書けばいいやん Q. どのテストを書けばいい？ CARTA HOLDINGS Inc.
39. • リリース前にバグに気づく • 変更することに対する安全性、容易性 • テスト対象のコードの理解を助ける • etc… つまり、開発における様々な不安を取り除く なぜテストを書きたいのか CARTA HOLDINGS Inc.
40. テストを書くことで、不安を取り除きたい箇所 • リリース後に壊れると致命的な箇所 ◦ お金が絡んだりしてあとから直すのが辛いとか • サービス的に大事なロジックが書かれている ◦ ECサイトなら決済とか、注文のキャンセルとか ◦ いわゆるビジネスロジック どこにテストを書きたい？ CARTA HOLDINGS Inc.
41. 特段不安がないとか、テストのコスパが悪そうな箇所にはテストは書かない • テストコードにもメンテコストはかかる • テストの実行に時間がかかると人々はテストしなくなる → テストしたいところだけテストする テストを書かないという選択 CARTA HOLDINGS Inc.
42. • 公開された振る舞い ◦ 依存しているモジュールから呼び出されるようなメソッド • 実装詳細 ◦ モジュール内で完結しているメソッド ◦ 外部から利用されることはない 公開された振る舞いと実装詳細 CARTA HOLDINGS Inc.
43. 基本的に公開された振る舞いしかテストしない • 外部から見える振る舞いが担保されてればよい • 詳細がテストされていると、リファクタリングしにくい ◦ 振る舞いは変わらないがその中身が変わるときに、テストも直す必要が出てくる 実装の詳細はテストしない CARTA HOLDINGS Inc.
44. 右図のような構造で、以下のことを考えてみる • 何のテストを書きたいか • 何のテストを書かないか 各レイヤーの関心事 • handler: HTTP req/res • usecase: ビジネスロジック • repository: DBとのやりとり • entiry: ビジネスオブジェクトとその振る舞い 例 CARTA HOLDINGS Inc.
45. あくまで例、サービスの特徴によって変わる 単純な構造なので、書きたいテストはそんな多くない • usecase層のユニットテスト • （ロジックがあれば）entity層のユニットテスト • handler ~ repositoryまで一気通貫のインテグレーションテスト 何のテストを書きたいか CARTA HOLDINGS Inc.
46. あくまで例(ry • handlerのユニットテスト • repositoryのユニットテスト • repository - DB間のインテグレーションテスト 何のテストを書かないか CARTA HOLDINGS Inc.
47. handlerのユニットテスト • HTTP req/resが関心事 ◦ それ以外の殆どの処理は他の層に移譲している ◦ つまり、テストしたいロジックがほとんどない • この層にテストしたいロジックがあったら、関心事の分離がうまくできていないかも？ なんで書かない？の一例 CARTA HOLDINGS Inc.
48. • なぜテストを書き、何をテストしたいのか • 意図がわからないテストは後々辛い ◦ プロダクションコードの変更でテストがコケたとき直しづらい ◦ そのテストの存在理由がわからないとメンテもされない 本当にテストしたいところにテストを書こう テストは意図が大事 CARTA HOLDINGS Inc.
49. 思想を言語化しよう
50. • なぜこのアーキテクチャにした？ • なぜこの言語を選んだ？ • なぜGraphQLを採用した？ こうしたWhyに対する答えは、意図的に言語化しないと残らない Whyはコードを読んでもわからない CARTA HOLDINGS Inc.
51. • 理解の助けになる • あとから反省する材料になる • アーキテクチャやテストに手を入れる際、既存のものの意図を知ることは大事 ◦ 今あるものがなぜこうなっているかを知った上で、どう変えると良いかを考える Whyの言語化はなぜ大事なのか CARTA HOLDINGS Inc.
52. システムを作り始める前に書く地図のようなもの • これから作るシステムが目指すゴール • どういう設計で作るのか • システムがスコープとしないこと、やらないこと などを書く • システムを作るにあたって必要な意思決定が言語化される • 意思決定に至ったWhyも書く Design Docを見ればシステムのゴール、意思決定の Whyが分かる状態にする Design Doc CARTA HOLDINGS Inc.
53. 特定の意思決定に関することを記述する • 背景 • なぜこの意思決定をしたのか • 他にどんな選択肢があったのか 作り始めてから行われる変化の意思決定は ADRで言語化するとわかりやすい Architecture Decision Record (ADR) CARTA HOLDINGS Inc.
54. • 認知負荷を意識して開発する • アーキテクチャもテストも必要だと思ったことをやればよい ◦ 必要に応じてあとから変化させれば良い • なぜやる（やらない）のかが大事 • コードでは伝わらないことは積極的に言語化していこう おわりに CARTA HOLDINGS Inc.
55. CARTA HOLDINGSのテックブログを読んでみてね • https://techblog.cartaholdings.co.jp/entry/2022/10/20/100730 今日の内容を実践した話 CARTA HOLDINGS Inc.
56. もの創り実践プログラム 「Treasure」 • 内容 「Go言語を使って学ぶ、 価値のあるもの創りとチーム開発」 • 日時 8/7～8/25（10:00～18:30） • 形式 オンライン＋オフィス開催（渋谷） • 定員：30名程度 • 学年：2025年4月以降に入社可能な方 　　　　　 ※文理不問、条件に合えば学年不問
57. 大規模サービス構築プログラム 「Sunrise」 • 内容 Goの広告アプリケーションサーバを AWSに構築し、改修 大規模リクエストを捌くために必要な 設計・構築について学べます • 日時 9/11～9/15（10:00～18:30） • 形式 オフライン開催（渋谷オフィス) • 定員：16名程度 • 学年：2025年4月以降に入社可能な方 　　　　　 ※文理不問、条件に合えば学年不問