Share
Embed
Transcript
18 slides
-
自己紹介 • @kyappamu (Yoshiki Takamatsu) • 株式会社Voicy • フルスタックエンジニアーAndroid・iOS アプリ
開発をメイン • ちょっと前からサウナに行ってます -
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で取得で きますよ。 -
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で取得で きますよ。 用語変換という小さなコストが頻繁に発生 -
例:レスポンスの使用方法が不明 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と いった他のフラグがどのような値になるか、レスポンス の具体例を教えていただけますか? -
例:レスポンスの使用方法が不明 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と いった他のフラグがどのような値になるか、レスポンス の具体例を教えていただけますか? レスポンスのどの項目を使ったら正しい判定ができ るのかわかりづらい -
例:同じ情報が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によって異なる名称で使われる 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ごとに同じ内容が異なる形式で返され、 変換実装コストがかかる -
想定される問題 - 🔄 無駄な実装コスト - 同じ情報を異なるAPIで異なる形で処 理 - クライアント側での変換ロジック実装
- ⚠ バグの温床 - 用語の取り違えによる実装ミス - レスポンス構造の誤解による不具合 - 📈 保守性の悪化 - 機能追加時の影響範囲が不 明確 - 新メンバーの学習コスト増大 - 技術的負債の蓄積 -
2-3人チーム 「プレミアム無料体験」 「Plus Trial」 → 口頭で確認できる範囲 👥 5-6人チーム Backend:「Plus
Trial」 iOS:「プレミアム体験」 Android:「無料キャンペーン」 → 用語変換が頻繁に発生 チーム規模と意思疎通コスト 10人以上チーム 複数の用語が混在 各自が異なる用語でドキュメント化 新メンバーが混乱 → 意思疎通コストが指数関数的に増加 -
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 フィールドに補足を記載 -
得られたこと&今後の展望 • 共通言語で会話しスムーズなやりとりができた ◦ 設計段階で用語を統一したことで、開発中のコミュニケーションに認識のズレがなく、手戻 りや無駄な確認コストを削減できた ◦ →
FrontEndやQA, デザイナー, PdMと、プロジェクト全体で用語を統一していきたい • デイリーミーティングでお互いの進捗が把握しやすい • 型の統一も図れ、実装で複雑性を吸収することを防げた ◦ モバイルとバックエンドでデータ構造を統一 ◦ クライアント側で複雑な変換ロジックを持つ必要がなくなった ◦ Swift OpenAPI Generator, OpenAPI Generator ◦ https://github.com/apple/swift-openapi-generator ◦ https://github.com/OpenAPITools/openapi-generator ◦ → 型安全性の向上に繋げたい -
結論 ✅ OpenAPI → 型安全性・仕様統一 + ✅ 用語統一 → スムーズなコミュニケーション
+ ✅ 使用方法明確化 → 実装判断の迷い解消