新規事業におけるWebAPI開発をよしなにリードする方法

新規事業×WebAPI開発に立ち向かう話
よしなに
@shibadog39

Transcript

1. 新規事業におけるWebAPI開発を よしなにリードする方法 2020/07/30 リードエンジニアから学ぶ MedPeerのプロダクト開発 Takahisa Sakurai
2. Rails Engineer • [2019/01~] MedPeer • [2020/05~] kakari for Clinicのリードエンジニア • ミーハーです。梨泰院クラスにハマっています。 Takahisa Sakurai @shibadog39 shibadog39
3. オンラインでの医師と患者の繋がりを支援する かかりつけクリニック支援サービス 2020年9月末リリース予定 患者が利用するモバイルアプリとクリニックが 利用するWebアプリ 大手ジェネリック医薬品メーカーの 日医工株式会社との共同事業 kakari for Clinic
4. kakari for clinicの機能と提供価値 クリニックPR 待ち時間負担 二次感染リスク の削減 診療予約 双方向の繋がり （かかりつけ）の提 供 双方向チャット 集患支援 アプリ・HP双方から時間帯予約 が出来る機能の提供 予約の変更や予約前日通知もア プリ経由で可能に クリニック受付と患者さんを双 方向で繋ぐチャット機能の提供 これまで電話で行っていた各種 問い合わせをチャットで効率化 これまでＨＰから行っていた情 報発信をより機動的に実施 PUSH通知を伴ったお知らせ配信 等で、確実に患者さんに情報を 届ける
5. kakari for Clinicの構想 クリニック 薬局向けかかりつけ薬局化支援サービス「kakari」と連携し、 診療から服薬フォローまで一気通貫で支援する kakariを通じて医療体験を変える！ • 診療予約 • 双方向チャット • クリニックPR • オンライン診療 • 処方せん送信 • 双方向チャット • 服薬フォロー • オンライン服薬指導 薬局
6. 利用技術とチーム構成 クリニック用Webフロント 患者用モバイルアプリ Android/iOS 2人ずつ 計4名 2名 3名 APIサーバー
7. (様式美) We’re hiring!!
8. 新規事業におけるWebAPI開発を よしなにリードする方法 ここから本編
9. 新規事業におけるWebAPI開発を 「よしな」にリードする方法
10. よしな ＝ 「いい感じ」
11. リードエンジニアとして何がいい感じになると嬉しいか • 開発スピード • 開発品質 • 開発継続性
12. 新規事業 • 不確定事項が多く仕様の流動性が高い • 開発スケジュールがタイトになりがち • 自分にとっては初のリードエンジニアポジション • はじめましてのメンバーもいる WebAPI開発 • 協働が前提 • 開発スピードが上がりにくい • 仕様変更コストが大きい フルリモート • コミュニケーションコスト増 • 心理的安全性の醸成難易度高 「よしな」の実現がハードモードな状況 この状況にいかに立ち向かったかの話
13. 発表のターゲット • これからAPI開発に携わることになりそうな人 • 現状のAPI開発フローを改善したいと思っている人 • スキーマ駆動開発興味あるけどどうデビューしたらいいかわからない人
14. 個人的に設定している裏Goal この発表を聞いてスキーマ駆動開発はじめてみたというtweetを1ヶ月以内に観測すること @shibadog39
15. 01 02 03 いい感じのAPI設計 いい感じの開発フロー いい感じのRails実装 -スタンダードを知る -巨人の肩に乗る 新規事業における WebAPI開発を よしなにリードする方法 -スキーマ駆動開発とは -明日からはじめるスキーマ駆動開発 -実践編：具体的な開発フロー -json serializer 選定 -言語の命名規則の壁を乗り越える
16. 01 02 03 いい感じのAPI設計 いい感じのAPI開発フロー いい感じのRails実装 -スタンダードを知る -巨人の肩に乗る 新規事業における WebAPI開発を よしなにリードする方法 -スキーマ駆動開発とは -明日からはじめるスキーマ駆動開発 -実践編：具体的な開発フロー -json serializer 選定 -言語の命名規則の壁を乗り越える
17. 01 いい感じのAPI設計 • これまでの自分：先輩エンジニアの見よう見まねのAPI設計 • 「かくあるべき」というAPI設計の基礎知識が粗いと設計意図の言語化がうま くできず、リードとしてイケていない • 「戦略の失敗は戦術で補うことはできない」よろしく、設計の失敗を実装で 補うことは難しいのでまずは設計をいい感じにする
18. 01 いい感じのAPI設計 1. スタンダードを知る 2. 巨人の肩に乗る
19. スタンダードを知る 01 いい感じのAPI設計 スタンダードを知る レスポンス設計 変更への柔軟性 エンドポイント 設計 RESTful リソースの命名 リクエスト設計 API設計 XSRF JSONハイジャック セキュリティ関係のHTTPヘッダ セキュリティ 検索とクエリパラメータ ページングとクエリパラメータ クエリ/パスパラメータの違い フラットにするべきか 配列の返し方 日付のフォーマット エラーの表現 モバイル/SPAでの考え方の違い APIのバージョン管理
20. スタンダードを知る 01 いい感じのAPI設計 スタンダードを知る これを読むのがよい エッセンスをサクッと読める Web API: The Good Parts: https://www.oreilly.co.jp/books/9784873116860/
21. 巨人の肩に乗る 01 いい感じのAPI設計 巨人の肩に乗る • 困ったら偉大な先人の設計をパクるのがよい • 広く認められているサービスなら、大きくハズレた設計はしていない
22. 巨人の肩に乗る 01 いい感じのAPI設計 巨人の肩に乗る github twitter slack trello gmail https://docs.github .com/en/rest https://github.com /github/rest-api-de scription https://developer.t witter.com/en/docs https://api.slack.co m/methods https://github.com /slackapi/slack-api- specs https://developer.a tlassian.com/cloud/ trello/rest/api-grou p-actions/ https://developers. google.com/gmail/a pi/v1/reference 身近な巨人たちのAPI定義
23. 巨人の肩に乗った例 01 いい感じのAPI設計 巨人の肩に乗る 仕様：リストの並び替えをドラッグアンドドロップで行うことができる 1: item_a 2: item_b 3: item_c 4: item_d 1: item_b 2: item_c 3: item_a 4: item_d e.g. item_aを移動 【まっさきに思いついた案】 item_aのidと並び替え後の番号(例の場合：3)をリクエストに送る その上で順番がずれ込むitemすべての順番を更新する
24. 1: item_b (position: 131070.0) 2: item_c (position: 196605.0) 3: item_a (position: 229372.5) 4: item_d (position: 262140.0) 巨人の肩に乗った例 01 いい感じのAPI設計 巨人の肩に乗る 仕様：リストの並び替えをドラッグアンドドロップで行うことができる 1: item_a (position: 65535.0) 2: item_b (position: 131070.0) 3: item_c (position: 196605.0) 4: item_d (position: 262140.0) e.g. item_aを移動 item_aの新しいposition = (c_pos + d_pos)/2 【trelloはどうやっているか】 要素の位置を浮動小数点で表現することで解決 https://developer.atlassian.com/cloud/trello/rest/api-group-cards/#api-cards-id-put Ref: https://qiita.com/gypsy/items/7bd2a4aeb1b419ce8914
25. 01 02 03 いい感じのAPI設計 いい感じの開発フロー いい感じのRails実装 -スタンダードを知る -巨人の肩に乗る 新規事業における WebAPI開発を よしなにリードする方法 -スキーマ駆動開発とは -明日からはじめるスキーマ駆動開発 -実践編：具体的な開発フロー -json serializer 選定 -言語の命名規則の壁を乗り越える
26. 02 いい感じの開発フロー • API開発＝協働が前提 • スムーズに協働できるフローを目指すと良い ◦ 認識の齟齬が少ない ◦ 並行して稼働できる
27. 1. スキーマ駆動開発とは 2. 明日からはじめるスキーマ駆動開発 3. 実践編：具体的な開発フロー 02 いい感じの開発フロー
28. スキーマ駆動開発とは 02 いい感じの開発フロー スキーマ駆動開発とは • API開発手法のひとつ • API記述言語※を用いてスキーマ(＝API定義)を表現 ◦ ※OpenAPI / API Blue Print / RAML 等が有名どころ • スキーマを開発の中心に据えて進める
29. 02 いい感じの開発フロー スキーマ駆動開発とは スキーマを中心に据えて。。？
30. 02 いい感じの開発フロー スキーマ駆動開発とは WebAPI開発なんだから API定義が中心なのは当たり前では？
31. 思い当たることありませんか 02 いい感じの開発フロー スキーマ駆動開発とは • API定義のドキュメント準備していたがメンテナンスがいつからかストップ • 仕様変更が一部の人にしか伝達されておらず、定義にも反映されず 結合テストでバグとなり発見される • ？ 「実装見ればわかるっしょ」
32. 02 いい感じの開発フロー スキーマ駆動開発とは API定義は置いてけぼりにされがち
33. スキーマを書くこと＝開発行為の一環 いつだってスキーマを書くことから開発がはじまる 一環というよりは要となる 02 いい感じの開発フロー スキーマ駆動開発とは スキーマを中心に据えた開発
34. 02 いい感じの開発フロー スキーマ駆動開発とは スキーマを中心に据えた開発 スキーマから • ドキュメントの自動生成 • コードを自動生成する • モックサーバーを立ち上げる • 単体テストのバリデーションを行う
35. スキーマ駆動のAPI開発 02 いい感じの開発フロー スキーマ駆動開発とは クライアントサイド サーバーサイド API定義を 一緒に決める リリース エンジニアによる 結合テスト QAテスト 実装 実装 モックの提供 コードの自動生成 スキーマによる 単体テスト補強
36. これを読むのがよい エッセンスをサクッと読める WEB+DB PRESS Vol.108 https://gihyo.jp/magazine/wdpress/archive/2019/vol108 スキーマ駆動のAPI開発 02 いい感じの開発フロー スキーマ駆動開発とは
37. 明日から始めるスキーマ駆動開発 02 いい感じの開発フロー 明日から始めるスキーマ駆動開発 OpenAPIを知る みんながスキーマに アクセスできる状態 にする スキーマを頑張って書く 01 02 03 まずはこれだけやれば大丈夫 簡単3ステップ
38. 明日から始めるスキーマ駆動開発 01 OpenAPIを知る • 何なのか：スキーマを記述するフォーマット ◦ 公式 ◦ ぐぐると出てくる各社のテックブログ ◦ (再掲) WEB+DB PRESS Vol.108 • 周辺ツール ◦ ドキュメント生成、コード生成、モックサーバー等 ◦ ここにまとまっている 02 いい感じの開発フロー 明日から始めるスキーマ駆動開発
39. 明日から始めるスキーマ駆動開発 スキーマを頑張って書く • エンドポイント/リクエスト/レスポンスの定義をひたす ら書く • OpenAPI Specification ここを見ながらひたすらに • json/yamlが辛ければ周辺ツールを利用するのもあり ◦ e.g. Stoplight 02 02 いい感じの開発フロー 明日から始めるスキーマ駆動開発
40. 明日から始めるスキーマ駆動開発 みんながスキーマにアクセスできるようにする • Chrome拡張の swagger-viewer を入れてもらう • github上でSwaggerUIを開くことができる • e.g. 公式のexample 03 02 いい感じの開発フロー 明日から始めるスキーマ駆動開発
41. 明日から始めるスキーマ駆動開発 OpenAPIを知る みんながスキーマに アクセスできる状態 にする スキーマを頑張って書く 01 02 03 ぜひはじめてみては！ 02 いい感じの開発フロー 明日から始めるスキーマ駆動開発
42. 実践編：具体的な開発フロー 02 いい感じの開発フロー 実践編：具体的な開発フロー 実務ではどのようにスキーマ駆動開発を進めているのか 定義設計フェーズ 200 1 実装フェーズ テストフェーズ
43. クライアントサイド サーバーサイド API定義を 一緒に決める リリース エンジニアによる 結合テスト QAテスト 実装 実装 モックの提供 コードの自動生成 スキーマによる 単体テスト補強 02 いい感じの開発フロー 実践編：具体的な開発フロー 定義設計フェーズ 実装フェーズ テストフェーズ 実践編：具体的な開発フロー
44. 実践編：具体的な開発フロー 02 いい感じの開発フロー 実践編：具体的な開発フロー 定義設計フェーズ 200 1 実装フェーズ テストフェーズ
45. 定義設計フェーズ 02 いい感じの開発フロー 実践編：具体的な開発フロー • 1人がたたき台を作成の上、全関係者を集めその場で修正 • クライアントサイドの事情・サーバーサイドの事情を顧みた設計にできる • もともとはスキーマファイルを書くところから、モブプロ的にやっていたが yamlを書く作業時間の待ちがもったいないのでこの形に
46. 定義設計フェーズ 誰がたたき台をつくるべきか？ • dbのカラム名とAPIのプロパティ名はなるべくあわせたい → サーバーサイド？ • 画面表示・制御と密なのだから →フロントサイド？ 基本的にサーバーサイドが作成、複雑な画面に関しては相談しながら作っていく 事が多い 02 いい感じの開発フロー 実践編：具体的な開発フロー
47. 実践編：具体的な開発フロー 02 いい感じの開発フロー 実践編：具体的な開発フロー 定義設計フェーズ 200 1 実装フェーズ テストフェーズ
48. 実装フェーズ 02 いい感じの開発フロー 実践編：具体的な開発フロー 1.スキーマへのアクセス容易さ 2.コスパの高い形でモックを提供 重要なことは4つ 3.スキーマ通りの実装になっていることを 技術で担保 4.機能群の優先順位の認識を揃えること • API定義を簡単に参照できること • リクエスト • レスポンス • 並行して稼働するためにまずはモック を提供 • 機能群ごとに結合テスト実施のマイル ストーンを決める
49. 1.スキーマへのアクセス容易さ 02 いい感じの開発フロー 実践編：具体的な開発フロー • Chrome拡張の swagger-viewer で実現 • なにか確認したいことがあるときにAPI定義をお互いに見ながら議論
50. 2.コスパの高い形でモックを提供 02 いい感じの開発フロー 実践編：具体的な開発フロー • 開発スピードを上げるためにはモックの提供は必須 • とはいえ本実装に置き換わるまでの一時的なものなので少ない労力で実現す ることが重要
51. 2.コスパの高い形でモックを提供 02 いい感じの開発フロー 実践編：具体的な開発フロー mockの実現方法3選 A. mockサーバー立ち上げる B. controllerにjsonべた書き C. クライアントサイドで準備
52. 2.コスパの高い形でモックを提供 02 いい感じの開発フロー 実践編：具体的な開発フロー A . mockサーバー立ち上げる • Toolがいくつかある ◦ 本家 openapi-generator ◦ Sprout ◦ Prism • スキーマ駆動開発ぽくてかっこいい • スキーマファイルに値を書いていくことになるので柔軟なことはそこまでで きない＆スキーマファイルが冗長になっていく
53. 2.コスパの高い形でモックを提供 02 いい感じの開発フロー 実践編：具体的な開発フロー B . controllerにjsonべた書き • Swagger UIに表示されるexampleをもとにrailsのcontrollerにベタ書き • 楽 • やろうとすれば分岐も柔軟に対応できる • スキーマ駆動の自動生成感は薄れる
54. 2.コスパの高い形でモックを提供 02 いい感じの開発フロー 実践編：具体的な開発フロー C . クライアントサイドで準備 • クライアント側がスキーマをもとに勝手に準備する • 欲しいデータをクライアント側が作成するので柔軟性はとても高い • スキーマ駆動の自動生成感はとても薄い • クライアントサイドのsnapshotテスト等でも使い回すとしたらクライアント 側で作成するのがコスパがよくなる
55. 2.コスパの高い形でモックを提供 02 いい感じの開発フロー 実践編：具体的な開発フロー • もともとは「A . mockサーバー立ち上げる」方法をとっていたが、 今は「B . controllerにjsonべた書き」、「C . クライアントサイドで準備」 をメインで進めている ◦ ちょっとした調整がしたい場合が多いため ◦ クライアントサイドのsnapshotテストを考慮 • どの方法が適しているかは、チームで話し合って決めるのが良い • 個人的なおすすめは「B . controllerにjsonべた書き」
56. 3.スキーマ通りの実装になっていることを 技術で担保 02 いい感じの開発フロー 実践編：具体的な開発フロー • リクエスト： スキーマからクライアントライブラリを自動生成 ◦ Web側の実装ではopenapi-generatorを利用してtypescriptのコードを 自動生成して利用している • レスポンス： スキーマ通りかのバリデーションをrspecで実施 ◦ Committee / committee-rails を利用している • 詳細はぐぐるとたくさん出てくると思うので割愛
57. 4.機能群の優先順位の認識を揃えること 02 いい感じの開発フロー 実践編：具体的な開発フロー • サーバー・クライアントの両者の実装が完了した機能群から順次結合テスト を実施していく • 両者の着手する順番がバラバラだといつまでも結合テストに進めないことが 起きうる • 機能群ごとに、結合テスト実施日のマイルストーンを決めておいて日々の開 発では次のマイルストーンに向けて実装を進める
58. 実践編：具体的な開発フロー 02 いい感じの開発フロー 実践編：具体的な開発フロー 定義設計フェーズ 200 1 実装フェーズ テストフェーズ
59. テストフェーズ 02 いい感じの開発フロー 実践編：具体的な開発フロー • 結合テストに先んじてデザイン・UIレビューを実施する ◦ どうしてもサーバー側の実装が遅れてしまう事が多い。 ◦ mockによるクライアントサイドの実装が先に完了した場合は、デザイン・UI だけのテストと称して画面をディレクターにテストしてもらう ◦ デザイン系の指摘事項を先に上げてもらうことが可能 • 結合テストはサーバー・クライアントで一緒に行う ◦ 考慮もれを防ぐ
60. 01 02 03 いい感じのAPI設計 いい感じの開発フロー いい感じのRails実装 -スタンダードを知る -巨人の肩に乗る 新規事業における WebAPI開発を よしなにリードする方法 -スキーマ駆動開発とは -明日からはじめるスキーマ駆動開発 -実践編：具体的な開発フロー -json serializer 選定 -言語の命名規則の壁を乗り越える
61. 03 いい感じのRails実装 サーバーサイドの実装にしぼってtipsを紹介
62. json serializer選定 03 いい感じのRails実装 json serializer選定 • 絶対的正解はない印象 • kakari for clinicではjsonapi-serializer (fork of fast_jsonapi)を使用 • Kakariという前任のサービスでも利用していたことから ◦ 開発チームとの親和性が高いこと ◦ Serializerごとにテストを書くことができるtestability • 「JSON APIとサービス高速化」という大変興味深いテーマの話が自分の発表 の後すぐに聞けるのでお楽しみに！
63. サーバーサイド • Ruby: snake_case 言語間の命名規則の壁を乗り越える 03 いい感じのRails実装 言語間の命名規則の壁を 乗り越える 不用意なバグが起こりがち はしわたしをいい感じにしたい！！ • レスポンスのプロパティ名を snake_case→camelCaseに変換 • リクエストのプロパティ名を camelCase→snake_caseに変換 クライアントサイド • JavaScript: camelCase • kotlin: camelCase • swift: camelCase
64. レスポンスのプロパティ名を snake_case→camelCaseに変換 03 いい感じのRails実装 言語間の命名規則の壁を 乗り越える • Jsonapi-serializerのkey-transforms機能 を使えば一瞬
65. リクエストのプロパティ名を camelCase→snake_caseに変換 03 いい感じのRails実装 言語間の命名規則の壁を 乗り越える • 変換しないと `params.permit(:someKey)` みたいに書くことになる • rubyの世界にcamelCaseが混じるのは避けたい • 各controllerで `params.transform_keys(&:underscore)` としてもいいけど冗長
66. リクエストのプロパティ名を camelCase→snake_caseに変換 03 いい感じのRails実装 言語間の命名規則の壁を 乗り越える 1. ActionController#Parameters にパッチをあててメソッドを追加する 2. before_actionで`params.deep_snakeize!` を呼ぶようにする
67. リクエストのプロパティ名を camelCase→snake_caseに変換 03 いい感じのRails実装 言語間の命名規則の壁を 乗り越える • ActionController::Parameters#deep_transform_keys!がRails 6.1でリリース 予定 • 6.1リリース後はパッチを当てずとも params.deep_transform_keys!(&:underscore)のように対応可能になる予定 https://github.com/rails/rails/issues/39081
68. 01 02 03 いい感じのAPI設計 いい感じの開発フロー いい感じのRails実装 -スタンダードを知る -巨人の肩に乗る 新規事業における WebAPI開発を よしなにリードする方法 -スキーマ駆動開発とは -明日からはじめるスキーマ駆動開発 -実践編：具体的な開発フロー -json serializer 選定 -言語の命名規則の壁を乗り越える
69. まとめ 「よしな」は1日にしてならず 設計論 便利なツールの導入とチームへの浸透 開発フローの策定と改善 技術選定と実装上の工夫
70. CREDITS: This presentation template was created by Slidesgo, including icons by Flaticon, and infographics & images by Freepik. Thanks! Please keep this slide for attribution.