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

by shibadog1121

Slide 1

Slide 1 text

新規事業におけるWebAPI開発をよしなにリードする方法 2020/07/30 リードエンジニアから学ぶ MedPeerのプロダクト開発 Takahisa Sakurai

Slide 2

Slide 2 text

Rails Engineer ● [2019/01~] MedPeer ● [2020/05~] kakari for Clinicのリードエンジニア ● ミーハーです。梨泰院クラスにハマっています。 Takahisa Sakurai @shibadog39 shibadog39

Slide 3

Slide 3 text

オンラインでの医師と患者の繋がりを支援するかかりつけクリニック支援サービス 2020年9月末リリース予定患者が利用するモバイルアプリとクリニックが利用するWebアプリ大手ジェネリック医薬品メーカーの日医工株式会社との共同事業 kakari for Clinic

Slide 4

Slide 4 text

kakari for clinicの機能と提供価値クリニックPR 待ち時間負担二次感染リスクの削減診療予約双方向の繋がり（かかりつけ）の提供双方向チャット集患支援アプリ・HP双方から時間帯予約が出来る機能の提供予約の変更や予約前日通知もアプリ経由で可能にクリニック受付と患者さんを双方向で繋ぐチャット機能の提供これまで電話で行っていた各種問い合わせをチャットで効率化これまでＨＰから行っていた情報発信をより機動的に実施 PUSH通知を伴ったお知らせ配信等で、確実に患者さんに情報を届ける

Slide 5

Slide 5 text

kakari for Clinicの構想クリニック薬局向けかかりつけ薬局化支援サービス「kakari」と連携し、診療から服薬フォローまで一気通貫で支援する kakariを通じて医療体験を変える！ ● 診療予約 ● 双方向チャット ● クリニックPR ● オンライン診療 ● 処方せん送信 ● 双方向チャット ● 服薬フォロー ● オンライン服薬指導薬局

Slide 6

Slide 6 text

利用技術とチーム構成クリニック用Webフロント患者用モバイルアプリ Android/iOS 2人ずつ計4名 2名 3名 APIサーバー

Slide 7

Slide 7 text

(様式美) We’re hiring!!

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

よしな＝「いい感じ」

Slide 11

Slide 11 text

リードエンジニアとして何がいい感じになると嬉しいか ● 開発スピード ● 開発品質 ● 開発継続性

Slide 12

Slide 12 text

新規事業 ● 不確定事項が多く仕様の流動性が高い ● 開発スケジュールがタイトになりがち ● 自分にとっては初のリードエンジニアポジション ● はじめましてのメンバーもいる WebAPI開発 ● 協働が前提 ● 開発スピードが上がりにくい ● 仕様変更コストが大きいフルリモート ● コミュニケーションコスト増 ● 心理的安全性の醸成難易度高「よしな」の実現がハードモードな状況この状況にいかに立ち向かったかの話

Slide 13

Slide 13 text

発表のターゲット ● これからAPI開発に携わることになりそうな人 ● 現状のAPI開発フローを改善したいと思っている人 ● スキーマ駆動開発興味あるけどどうデビューしたらいいかわからない人

Slide 14

Slide 14 text

個人的に設定している裏Goal この発表を聞いてスキーマ駆動開発はじめてみたというtweetを1ヶ月以内に観測すること @shibadog39

Slide 15

Slide 15 text

01 02 03 いい感じのAPI設計いい感じの開発フローいい感じのRails実装 -スタンダードを知る -巨人の肩に乗る新規事業における WebAPI開発をよしなにリードする方法 -スキーマ駆動開発とは -明日からはじめるスキーマ駆動開発 -実践編：具体的な開発フロー -json serializer 選定 -言語の命名規則の壁を乗り越える

Slide 16

Slide 16 text

01 02 03 いい感じのAPI設計いい感じのAPI開発フローいい感じのRails実装 -スタンダードを知る -巨人の肩に乗る新規事業における WebAPI開発をよしなにリードする方法 -スキーマ駆動開発とは -明日からはじめるスキーマ駆動開発 -実践編：具体的な開発フロー -json serializer 選定 -言語の命名規則の壁を乗り越える

Slide 17

Slide 17 text

01 いい感じのAPI設計 ● これまでの自分：先輩エンジニアの見よう見まねのAPI設計 ● 「かくあるべき」というAPI設計の基礎知識が粗いと設計意図の言語化がうまくできず、リードとしてイケていない ● 「戦略の失敗は戦術で補うことはできない」よろしく、設計の失敗を実装で補うことは難しいのでまずは設計をいい感じにする

Slide 18

Slide 18 text

01 いい感じのAPI設計 1. スタンダードを知る 2. 巨人の肩に乗る

Slide 19

Slide 19 text

スタンダードを知る 01 いい感じのAPI設計スタンダードを知るレスポンス設計変更への柔軟性エンドポイント設計 RESTful リソースの命名リクエスト設計 API設計 XSRF JSONハイジャックセキュリティ関係のHTTPヘッダセキュリティ検索とクエリパラメータページングとクエリパラメータクエリ/パスパラメータの違いフラットにするべきか配列の返し方日付のフォーマットエラーの表現モバイル/SPAでの考え方の違い APIのバージョン管理

Slide 20

Slide 20 text

スタンダードを知る 01 いい感じのAPI設計スタンダードを知るこれを読むのがよいエッセンスをサクッと読める Web API: The Good Parts: https://www.oreilly.co.jp/books/9784873116860/

Slide 21

Slide 21 text

巨人の肩に乗る 01 いい感じのAPI設計巨人の肩に乗る ● 困ったら偉大な先人の設計をパクるのがよい ● 広く認められているサービスなら、大きくハズレた設計はしていない

Slide 22

Slide 22 text

巨人の肩に乗る 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定義

Slide 23

Slide 23 text

巨人の肩に乗った例 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すべての順番を更新する

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Slide 26

Slide 26 text

02 いい感じの開発フロー ● API開発＝協働が前提 ● スムーズに協働できるフローを目指すと良い ○ 認識の齟齬が少ない ○ 並行して稼働できる

Slide 27

Slide 27 text

1. スキーマ駆動開発とは 2. 明日からはじめるスキーマ駆動開発 3. 実践編：具体的な開発フロー 02 いい感じの開発フロー

Slide 28

Slide 28 text

スキーマ駆動開発とは 02 いい感じの開発フロースキーマ駆動開発とは ● API開発手法のひとつ ● API記述言語※を用いてスキーマ(＝API定義)を表現 ○ ※OpenAPI / API Blue Print / RAML 等が有名どころ ● スキーマを開発の中心に据えて進める

Slide 29

Slide 29 text

02 いい感じの開発フロースキーマ駆動開発とはスキーマを中心に据えて。。？

Slide 30

Slide 30 text

02 いい感じの開発フロースキーマ駆動開発とは WebAPI開発なんだから API定義が中心なのは当たり前では？

Slide 31

Slide 31 text

思い当たることありませんか 02 いい感じの開発フロースキーマ駆動開発とは ● API定義のドキュメント準備していたがメンテナンスがいつからかストップ ● 仕様変更が一部の人にしか伝達されておらず、定義にも反映されず結合テストでバグとなり発見される ● ？「実装見ればわかるっしょ」

Slide 32

Slide 32 text

02 いい感じの開発フロースキーマ駆動開発とは API定義は置いてけぼりにされがち

Slide 33

Slide 33 text

スキーマを書くこと＝開発行為の一環いつだってスキーマを書くことから開発がはじまる一環というよりは要となる 02 いい感じの開発フロースキーマ駆動開発とはスキーマを中心に据えた開発

Slide 34

Slide 34 text

02 いい感じの開発フロースキーマ駆動開発とはスキーマを中心に据えた開発スキーマから ● ドキュメントの自動生成 ● コードを自動生成する ● モックサーバーを立ち上げる ● 単体テストのバリデーションを行う

Slide 35

Slide 35 text

スキーマ駆動のAPI開発 02 いい感じの開発フロースキーマ駆動開発とはクライアントサイドサーバーサイド API定義を一緒に決めるリリースエンジニアによる結合テスト QAテスト実装実装モックの提供コードの自動生成スキーマによる単体テスト補強

Slide 36

Slide 36 text

これを読むのがよいエッセンスをサクッと読める WEB+DB PRESS Vol.108 https://gihyo.jp/magazine/wdpress/archive/2019/vol108 スキーマ駆動のAPI開発 02 いい感じの開発フロースキーマ駆動開発とは

Slide 37

Slide 37 text

明日から始めるスキーマ駆動開発 02 いい感じの開発フロー明日から始めるスキーマ駆動開発 OpenAPIを知るみんながスキーマにアクセスできる状態にするスキーマを頑張って書く 01 02 03 まずはこれだけやれば大丈夫簡単3ステップ

Slide 38

Slide 38 text

明日から始めるスキーマ駆動開発 01 OpenAPIを知る ● 何なのか：スキーマを記述するフォーマット ○ 公式 ○ ぐぐると出てくる各社のテックブログ ○ (再掲) WEB+DB PRESS Vol.108 ● 周辺ツール ○ ドキュメント生成、コード生成、モックサーバー等 ○ ここにまとまっている 02 いい感じの開発フロー明日から始めるスキーマ駆動開発

Slide 39

Slide 39 text

明日から始めるスキーマ駆動開発スキーマを頑張って書く ● エンドポイント/リクエスト/レスポンスの定義をひたすら書く ● OpenAPI Speciﬁcation ここを見ながらひたすらに ● json/yamlが辛ければ周辺ツールを利用するのもあり ○ e.g. Stoplight 02 02 いい感じの開発フロー明日から始めるスキーマ駆動開発

Slide 40

Slide 40 text

明日から始めるスキーマ駆動開発みんながスキーマにアクセスできるようにする ● Chrome拡張の swagger-viewer を入れてもらう ● github上でSwaggerUIを開くことができる ● e.g. 公式のexample 03 02 いい感じの開発フロー明日から始めるスキーマ駆動開発

Slide 41

Slide 41 text

明日から始めるスキーマ駆動開発 OpenAPIを知るみんながスキーマにアクセスできる状態にするスキーマを頑張って書く 01 02 03 ぜひはじめてみては！ 02 いい感じの開発フロー明日から始めるスキーマ駆動開発

Slide 42

Slide 42 text

実践編：具体的な開発フロー 02 いい感じの開発フロー実践編：具体的な開発フロー実務ではどのようにスキーマ駆動開発を進めているのか定義設計フェーズ 200 1 実装フェーズテストフェーズ

Slide 43

Slide 43 text

クライアントサイドサーバーサイド API定義を一緒に決めるリリースエンジニアによる結合テスト QAテスト実装実装モックの提供コードの自動生成スキーマによる単体テスト補強 02 いい感じの開発フロー実践編：具体的な開発フロー定義設計フェーズ実装フェーズテストフェーズ実践編：具体的な開発フロー

Slide 44

Slide 44 text

実践編：具体的な開発フロー 02 いい感じの開発フロー実践編：具体的な開発フロー定義設計フェーズ 200 1 実装フェーズテストフェーズ

Slide 45

Slide 45 text

定義設計フェーズ 02 いい感じの開発フロー実践編：具体的な開発フロー ● 1人がたたき台を作成の上、全関係者を集めその場で修正 ● クライアントサイドの事情・サーバーサイドの事情を顧みた設計にできる ● もともとはスキーマファイルを書くところから、モブプロ的にやっていたが yamlを書く作業時間の待ちがもったいないのでこの形に

Slide 46

Slide 46 text

定義設計フェーズ誰がたたき台をつくるべきか？ ● dbのカラム名とAPIのプロパティ名はなるべくあわせたい → サーバーサイド？ ● 画面表示・制御と密なのだから →フロントサイド？基本的にサーバーサイドが作成、複雑な画面に関しては相談しながら作っていく事が多い 02 いい感じの開発フロー実践編：具体的な開発フロー

Slide 47

Slide 47 text

実践編：具体的な開発フロー 02 いい感じの開発フロー実践編：具体的な開発フロー定義設計フェーズ 200 1 実装フェーズテストフェーズ

Slide 48

Slide 48 text

実装フェーズ 02 いい感じの開発フロー実践編：具体的な開発フロー 1.スキーマへのアクセス容易さ 2.コスパの高い形でモックを提供重要なことは4つ 3.スキーマ通りの実装になっていることを技術で担保 4.機能群の優先順位の認識を揃えること ● API定義を簡単に参照できること ● リクエスト ● レスポンス ● 並行して稼働するためにまずはモックを提供 ● 機能群ごとに結合テスト実施のマイルストーンを決める

Slide 49

Slide 49 text

1.スキーマへのアクセス容易さ 02 いい感じの開発フロー実践編：具体的な開発フロー ● Chrome拡張の swagger-viewer で実現 ● なにか確認したいことがあるときにAPI定義をお互いに見ながら議論

Slide 50

Slide 50 text

2.コスパの高い形でモックを提供 02 いい感じの開発フロー実践編：具体的な開発フロー ● 開発スピードを上げるためにはモックの提供は必須 ● とはいえ本実装に置き換わるまでの一時的なものなので少ない労力で実現することが重要

Slide 51

Slide 51 text

2.コスパの高い形でモックを提供 02 いい感じの開発フロー実践編：具体的な開発フロー mockの実現方法3選 A. mockサーバー立ち上げる B. controllerにjsonべた書き C. クライアントサイドで準備

Slide 52

Slide 52 text

2.コスパの高い形でモックを提供 02 いい感じの開発フロー実践編：具体的な開発フロー A . mockサーバー立ち上げる ● Toolがいくつかある ○ 本家 openapi-generator ○ Sprout ○ Prism ● スキーマ駆動開発ぽくてかっこいい ● スキーマファイルに値を書いていくことになるので柔軟なことはそこまでできない＆スキーマファイルが冗長になっていく

Slide 53

Slide 53 text

2.コスパの高い形でモックを提供 02 いい感じの開発フロー実践編：具体的な開発フロー B . controllerにjsonべた書き ● Swagger UIに表示されるexampleをもとにrailsのcontrollerにベタ書き ● 楽 ● やろうとすれば分岐も柔軟に対応できる ● スキーマ駆動の自動生成感は薄れる

Slide 54

Slide 54 text

2.コスパの高い形でモックを提供 02 いい感じの開発フロー実践編：具体的な開発フロー C . クライアントサイドで準備 ● クライアント側がスキーマをもとに勝手に準備する ● 欲しいデータをクライアント側が作成するので柔軟性はとても高い ● スキーマ駆動の自動生成感はとても薄い ● クライアントサイドのsnapshotテスト等でも使い回すとしたらクライアント側で作成するのがコスパがよくなる

Slide 55

Slide 55 text

2.コスパの高い形でモックを提供 02 いい感じの開発フロー実践編：具体的な開発フロー ● もともとは「A . mockサーバー立ち上げる」方法をとっていたが、今は「B . controllerにjsonべた書き」、「C . クライアントサイドで準備」をメインで進めている ○ ちょっとした調整がしたい場合が多いため ○ クライアントサイドのsnapshotテストを考慮 ● どの方法が適しているかは、チームで話し合って決めるのが良い ● 個人的なおすすめは「B . controllerにjsonべた書き」

Slide 56

Slide 56 text

3.スキーマ通りの実装になっていることを技術で担保 02 いい感じの開発フロー実践編：具体的な開発フロー ● リクエスト：スキーマからクライアントライブラリを自動生成 ○ Web側の実装ではopenapi-generatorを利用してtypescriptのコードを自動生成して利用している ● レスポンス：スキーマ通りかのバリデーションをrspecで実施 ○ Committee / committee-rails を利用している ● 詳細はぐぐるとたくさん出てくると思うので割愛

Slide 57

Slide 57 text

4.機能群の優先順位の認識を揃えること 02 いい感じの開発フロー実践編：具体的な開発フロー ● サーバー・クライアントの両者の実装が完了した機能群から順次結合テストを実施していく ● 両者の着手する順番がバラバラだといつまでも結合テストに進めないことが起きうる ● 機能群ごとに、結合テスト実施日のマイルストーンを決めておいて日々の開発では次のマイルストーンに向けて実装を進める

Slide 58

Slide 58 text

実践編：具体的な開発フロー 02 いい感じの開発フロー実践編：具体的な開発フロー定義設計フェーズ 200 1 実装フェーズテストフェーズ

Slide 59

Slide 59 text

テストフェーズ 02 いい感じの開発フロー実践編：具体的な開発フロー ● 結合テストに先んじてデザイン・UIレビューを実施する ○ どうしてもサーバー側の実装が遅れてしまう事が多い。 ○ mockによるクライアントサイドの実装が先に完了した場合は、デザイン・UI だけのテストと称して画面をディレクターにテストしてもらう ○ デザイン系の指摘事項を先に上げてもらうことが可能 ● 結合テストはサーバー・クライアントで一緒に行う ○ 考慮もれを防ぐ

Slide 60

Slide 60 text

Slide 61

Slide 61 text

03 いい感じのRails実装サーバーサイドの実装にしぼってtipsを紹介

Slide 62

Slide 62 text

json serializer選定 03 いい感じのRails実装 json serializer選定 ● 絶対的正解はない印象 ● kakari for clinicではjsonapi-serializer (fork of fast_jsonapi)を使用 ● Kakariという前任のサービスでも利用していたことから ○ 開発チームとの親和性が高いこと ○ Serializerごとにテストを書くことができるtestability ● 「JSON APIとサービス高速化」という大変興味深いテーマの話が自分の発表の後すぐに聞けるのでお楽しみに！

Slide 63

Slide 63 text

サーバーサイド ● Ruby: snake_case 言語間の命名規則の壁を乗り越える 03 いい感じのRails実装言語間の命名規則の壁を乗り越える不用意なバグが起こりがちはしわたしをいい感じにしたい！！ ● レスポンスのプロパティ名を snake_case→camelCaseに変換 ● リクエストのプロパティ名を camelCase→snake_caseに変換クライアントサイド ● JavaScript: camelCase ● kotlin: camelCase ● swift: camelCase

Slide 64

Slide 64 text

レスポンスのプロパティ名を snake_case→camelCaseに変換 03 いい感じのRails実装言語間の命名規則の壁を乗り越える ● Jsonapi-serializerのkey-transforms機能を使えば一瞬

Slide 65

Slide 65 text

リクエストのプロパティ名を camelCase→snake_caseに変換 03 いい感じのRails実装言語間の命名規則の壁を乗り越える ● 変換しないと `params.permit(:someKey)` みたいに書くことになる ● rubyの世界にcamelCaseが混じるのは避けたい ● 各controllerで `params.transform_keys(&:underscore)` としてもいいけど冗長

Slide 66

Slide 66 text

リクエストのプロパティ名を camelCase→snake_caseに変換 03 いい感じのRails実装言語間の命名規則の壁を乗り越える 1. ActionController#Parameters にパッチをあててメソッドを追加する 2. before_actionで`params.deep_snakeize!` を呼ぶようにする

Slide 67

Slide 67 text

リクエストのプロパティ名を 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

Slide 68

Slide 68 text

Slide 69

Slide 69 text

まとめ「よしな」は1日にしてならず設計論便利なツールの導入とチームへの浸透開発フローの策定と改善技術選定と実装上の工夫

Slide 70

Slide 70 text

CREDITS: This presentation template was created by Slidesgo, including icons by Flaticon, and infographics & images by Freepik. Thanks! Please keep this slide for attribution.