用語統一のその先へ〜フロントとバックエンドの円滑なコミュニケーション

Transcript

1. 用語統一のその先へ〜フロントとバックエンドの円滑なコミュニ ケーション
 @kyappamu

2. 自己紹介
 • @kyappamu (Yoshiki Takamatsu)
 • 株式会社Voicy
 • フルスタックエンジニアーAndroid・iOS アプリ 開発をメイン
 • ちょっと前からサウナに行ってます

3. OpenAPIがあれば情報連携は十分...本当に？

4. 技術的な統一だけでは解決しない
 コミュニケーションの課題があるんです

5. 例えばこんな場面、ありませんか？

6. is_plus: type: boolean plus: type: object properties: amount: type: integer time_of_next_payment: type: string format: date-time required: - amount - time_of_next_payment is_plus_trial: type: boolean plus_trial: type: object properties: ends_at: 例：用語の不一致
 （Mobile開発者）今度の "無料キャンペーン" の件なん ですが、ユーザーが対象かどうかと、終了日を知りたい です。
 （BE開発者）"無料キャンペーン"...？ああ、内部的には "Plus Trial"と呼んでいる機能です。はい、APIで取得で きますよ。

7. is_plus: type: boolean plus: type: object properties: amount: type: integer time_of_next_payment: type: string format: date-time required: - amount - time_of_next_payment is_plus_trial: type: boolean plus_trial: type: object properties: ends_at: 例：用語の不一致
 （Mobile開発者）今度の "無料キャンペーン" の件なん ですが、ユーザーが対象かどうかと、終了日を知りたい です。
 （BE開発者）"無料キャンペーン"...？ああ、内部的には "Plus Trial"と呼んでいる機能です。はい、APIで取得で きますよ。
 用語変換という小さなコストが頻繁に発生 

8. 例：レスポンスの使用方法が不明
 properties: is_basic: type: boolean basic: type: object properties: plus_trial_enabled: type: boolean can_join_plus_trial_plan: type: boolean is_plus: type: boolean is_plus_trial: type: boolean plus_trial: type: object properties: ends_at: type: string （Mobile開発者）ユーザーが"無料体験中"である場合の 判定について質問です。
 is_plus_trial というフラグがありますが、これを正として 見れば良いでしょうか？
 また、is_plus_trial が true の時、is_basic や is_plusと いった他のフラグがどのような値になるか、レスポンス の具体例を教えていただけますか？ 

9. 例：レスポンスの使用方法が不明
 properties: is_basic: type: boolean basic: type: object properties: plus_trial_enabled: type: boolean can_join_plus_trial_plan: type: boolean is_plus: type: boolean is_plus_trial: type: boolean plus_trial: type: object properties: ends_at: type: string （Mobile開発者）ユーザーが"無料体験中"である場合の 判定について質問です。
 is_plus_trial というフラグがありますが、これを正として 見れば良いでしょうか？
 また、is_plus_trial が true の時、is_basic や is_plusと いった他のフラグがどのような値になるか、レスポンス の具体例を教えていただけますか？ 
 レスポンスのどの項目を使ったら正しい判定ができ るのかわかりづらい

10. 例：同じ情報がAPIによって異なる名称で使われる
 properties: is_plus_trial: type: boolean plus_trial: type: object properties: ends_at: type: string （Mobile開発者）APIについて質問させてください。無料 体験機能について調べているのですが、関連しそうな APIが2つ見つかりました。
 名前も構造も全く違うのですが、もしかしてこの2つの APIが返している情報は、表現している内容は全く同じ もの、という認識で合っていますでしょうか？ 
 properties: plan_name: type: string trial_info: type: object properties: trial_end_date: type: string /contract /subscription
11. 例：同じ情報がAPIによって異なる名称で使われる
 properties: is_plus_trial: type: boolean plus_trial: type: object properties: ends_at: type: string （Mobile開発者）APIについて質問させてください。無料 体験機能について調べているのですが、関連しそうな APIが2つ見つかりました。
 名前も構造も全く違うのですが、もしかしてこの2つの APIが返している情報は、表現している内容は全く同じ もの、という認識で合っていますでしょうか？ 
 properties: plan_name: type: string trial_info: type: object properties: trial_end_date: type: string /contract /subscription APIごとに同じ内容が異なる形式で返され、 
 変換実装コストがかかる 

12. 想定される問題
 - 🔄 無駄な実装コスト
 - 同じ情報を異なるAPIで異なる形で処 理
 - クライアント側での変換ロジック実装 
 - ⚠ バグの温床
 - 用語の取り違えによる実装ミス 
 - レスポンス構造の誤解による不具合 
 - 📈 保守性の悪化
 - 機能追加時の影響範囲が不 明確
 - 新メンバーの学習コスト増大 
 - 技術的負債の蓄積
 

13. 󰳕 2-3人チーム
 「プレミアム無料体験」
 「Plus Trial」
 → 口頭で確認できる範囲
 👥 5-6人チーム
 Backend：「Plus Trial」
 iOS：「プレミアム体験」
 Android：「無料キャンペーン」
 → 用語変換が頻繁に発生
 チーム規模と意思疎通コスト
 󰔢 10人以上チーム
 複数の用語が混在
 各自が異なる用語でドキュメント化 
 新メンバーが混乱
 → 意思疎通コストが指数関数的に増加 

14. 実践したことー用語の統一、概念の共通認識
 • 概念設計段階から入り、同じ用語を使って会話する
 • 状態遷移図

15. description: | ユーザーが現在契約している利用プランを表す。 - 契約を表すプロパティ: is_classic, is_basic, is_plus - 必ずこれらのプロパティのうちのひとつを持つ (いずれも存在しなかっ たり、2つ以上存在することはない) - 存在するプロパティの値は必ずtrueである - 今後種類が増える可能性がある - 契約の追加情報を表すプロパティ: basic, plus_trial - 契約を表すプロパティ (is_*) に対応するものが含まれる - これらのプロパティは存在しないこともある properties: is_classic: type: boolean description: このキーが存在し、かつtrueなら従来プランを契約してい る is_basic: type: boolean description: このキーが存在し、かつtrueなら基本プランを契約してい る 実践したことーレスポンスの使用方法
 • OpenAPI の description フィールドに補足を記載

16. 得られたこと＆今後の展望
 • 共通言語で会話しスムーズなやりとりができた 
 ◦ 設計段階で用語を統一したことで、開発中のコミュニケーションに認識のズレがなく、手戻 りや無駄な確認コストを削減できた 
 ◦ → FrontEndやQA, デザイナー, PdMと、プロジェクト全体で用語を統一していきたい 
 • デイリーミーティングでお互いの進捗が把握しやすい 
 • 型の統一も図れ、実装で複雑性を吸収することを防げた 
 ◦ モバイルとバックエンドでデータ構造を統一 
 ◦ クライアント側で複雑な変換ロジックを持つ必要がなくなった 
 ◦ Swift OpenAPI Generator, OpenAPI Generator 
 ◦ https://github.com/apple/swift-openapi-generator 
 ◦ https://github.com/OpenAPITools/openapi-generator 
 ◦ → 型安全性の向上に繋げたい 

17. 結論 ✅ OpenAPI → 型安全性・仕様統一 + ✅ 用語統一 → スムーズなコミュニケーション + ✅ 使用方法明確化 → 実装判断の迷い解消
18. ご清聴ありがとうございました