Tweet
Tweet

Slide 1

Slide 1 text

実装と乖離させないスキーマ駆 動開発フロー / OpenAPI Laravel 編 Press Space for next page （非公式）PHP Conference Fukuoka After Hack!! June 25, 2023. v0.0.21

Slide 2

Slide 2 text

自己紹介 以下のアカウントで活動しています katzumiと申します katzchum k2tzumi katzumi

Slide 3

Slide 3 text

スキーマ駆動開発のフローってどうやっていますか？ 本LTではクライアント（フロントエンド）の実装はさておいて、主にAPI（バックエンド）の実装についてお 話します。

Slide 4

Slide 4 text

スキーマ駆動開発のフローってどうやっていますか？ ドキュメント（スキーマ定義の仕様書）が先？ 本LTではクライアント（フロントエンド）の実装はさておいて、主にAPI（バックエンド）の実装についてお 話します。

Slide 5

Slide 5 text

スキーマ駆動開発のフローってどうやっていますか？ ドキュメント（スキーマ定義の仕様書）が先？ APIの実装（コード）が先？ 本LTではクライアント（フロントエンド）の実装はさておいて、主にAPI（バックエンド）の実装についてお 話します。

Slide 6

Slide 6 text

問題点 スキーマ定義（ドキュメント）と実際の実装（コード）が乖離してしまう

Slide 7

Slide 7 text

なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）

Slide 8

Slide 8 text

なぜ乖離が発生するのか？ コード生成 実装 Open API Spec Stub コード 実際のコード ドキュメントが先の場合（コードが先であっても。。）

Slide 9

Slide 9 text

なぜ乖離が発生するのか？ コード生成 実装 変更 ❌ 変更済みのStub を反映することはできない Open API Spec Stub コード 実際のコード * ドキュメントが先の場合（コードが先であっても。。）

Slide 10

Slide 10 text

なぜ乖離が発生するのか？ コード生成 実装 変更 ❌ 変更済みのStub を反映することはできない 変更 ❌ 定義が間違っていても自動反映はされない Open API Spec Stub コード 実際のコード * * ドキュメントが先の場合（コードが先であっても。。）

Slide 11

Slide 11 text

なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）

Slide 12

Slide 12 text

なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）

Slide 13

Slide 13 text

なぜ乖離が発生するのか？ ドキュメントが先の場合（コードが先であっても。。）

Slide 14

Slide 14 text

つらい、、

Slide 15

Slide 15 text

なぜ？

Slide 16

Slide 16 text

スキーマとコードとの距離が離れてしまっている コード生成 実装 ココ!! Open API Spec Stub コード 実際のコード 独立したものになっていて、乖離が発生したことを見落としがち

Slide 17

Slide 17 text

どうすれば距離が縮まるか？

Slide 18

Slide 18 text

スキーマ定義をコードに埋め込むという方法 swagger-php のAttributeを使ってスキーマを定義する Controller

Slide 19

Slide 19 text

レビューしやすい 視点移動が少なくて済む

Slide 20

Slide 20 text

絶対スキーマから乖離させないマン Attributeや実際に出力されたスキーマファイルを活用してスキーマとコードを乖離させない仕組み

Slide 21

Slide 21 text

Attributeの力を引き出してみる!

Slide 22

Slide 22 text

Arttibuteはコードの一部！ ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする

Slide 23

Slide 23 text

Arttibuteはコードの一部！ 生成 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 Controller クラス Request クラス Response クラス スキーマファイル ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする

Slide 24

Slide 24 text

Arttibuteはコードの一部！ 生成 ズレが発生しない 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 実行時評価 自動生成 Controller クラス Request クラス Response クラス Validation ルール Route ファイル スキーマファイル ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする

Slide 25

Slide 25 text

Arttibuteはコードの一部！ 生成 ズレが発生しない 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 実行時評価 自動生成 Controller クラス Request クラス Response クラス Validation ルール Route ファイル スキーマファイル ReflectionClassを使ってArttibuteを読み出してゴニョゴニョする

Slide 26

Slide 26 text

スキーマ自体も静的解析すべし！ OpenAPI Spec 表示 生成 静的解析 整形 require スキーマファイル spectral Redoc 実際のコード Attribute 定義 Attribute 定義 Attribute 定義 実行時評価 自動生成 Controller クラス Request クラス Response クラス Validation ルール Route ファイル swagger-php(L5-Swagger) swagge-ui

Slide 27

Slide 27 text

リクエスト・レスポンスの正確性を保証させる 生成 参照（リクエスト・レスポンスValidation ） テスト実行 Test コード Use laravel-openapi-validator Controller テスト(PHPUnit) 実際のコード 自動生成 実行時評価 Route ファイル Controller クラス Request クラス Validation ルール Response クラス スキーマファイル Controllerテストで laravel-openapi-validator を利用してリクエストとレスポンスを検証

Slide 28

Slide 28 text

より確実にE2Eで検証 生成 参照（リクエスト・レスポンスValidation ） テスト実行 Test コード API シナリオテスト(runn) 実際のコード 自動生成 実行時評価 Route ファイル Controller クラス Request クラス Validation ルール Response クラス スキーマファイル APIシナリオテスト（ runn ）でユースケースを網羅的に検証

Slide 29

Slide 29 text

まとめ

Slide 30

Slide 30 text

スキーマ≠ドキュメント スキーマはコードの一部。ドキュメンテーションツールからSpecを自動生成

Slide 31

Slide 31 text

スキーマをいつ書くか？ コードを書いたら勝手にスキーマ定義がいい感じに出力されている状態

Slide 32

Slide 32 text

スキーマ自体もテストが必要 静的解析して最低限の品質を確保 テストでの検証にも利用してスキーマを含んだAPI自体の品質も向上させる

Slide 33

Slide 33 text

参考URL 実装と乖離させないスキーマ駆動開発フロー / OpenAPI Laravel編 https://zenn.dev/katzumi/articles/schema-driven-development-flow swagger-php https://github.com/zircote/swagger-php spectral https://github.com/stoplightio/spectral laravel-openapi-validator https://github.com/kirschbaum-development/laravel-openapi-validator runn https://github.com/k1LoW/runn

Slide 34

Slide 34 text

ご清聴ありがとうございます