Ktor 1.6.8 から 2.2.4 へ安全に移⾏した話

■ 発表者
Bill One Engineering Unit
⼩式澤 篤

■ Bill One 開発エンジニア 採用情報
https://media.sansan-engineering.com/billone-engineer

Transcript

1. Sansan株式会社 部署 名前 Ktor 1.6.8 から 2.2.4 へ 安全に移⾏した話 Sansan技術本部 Bill One Engineering Unit ⼩式澤 篤
2. 写真が入ります ⼩式澤 篤 (Atsushi Koshikizawa) Sansan株式会社 技術本部 Bill One Engineering Unit 2022年に BtoC 業界から Sansan へ中途⼊社。⼊社以来 Web アプリケー ション開発エンジニアとして Bill One の開発に従事。現在は Bill One にお ける請求書受領領域の開発に加えて、 Bill One 全体の品質向上に向き合っ ている。 @lastarrow21 @lasta
3. - Ktor 1.6.8 から 2.2.4 へバージョンアップした話 - 作戦と実際の流れ - 安全に移⾏するために必要なもの - 他の開発を⽌めずスムーズに進めるたの⼯夫 今⽇お話したいこと
4. マイクロサービスやウェブアプリケーションなどを作成するための JetBrains 公式のフレームワーク Ktor Copyright © 2023 JetBrains s.r.o. Ktor and the Ktor logo are registered trademarks of JetBrains s.r.o.
5. アーキテクチャ概要 Email Authentication Frontend / BFF App Engine Cloud Load Balancing Backend Cloud Run Database Cloud SQL Static Files Cloud Storage Cloud Tasks API Gateway Cloud Load Balancing API Client User Logging Error Reporting Cloud Build Bill One Entry Management / Developer Tools Cloud Functions Monitoring
6. アーキテクチャ概要 Email Authentication Frontend / BFF App Engine Cloud Load Balancing Backend Cloud Run Database Cloud SQL Static Files Cloud Storage Cloud Tasks API Gateway Cloud Load Balancing API Client User Logging Error Reporting Cloud Build Bill One Entry Management / Developer Tools Cloud Functions Monitoring ここのマイクロサービスの1つの話
7. 背景
8. 背景とゴール - Ktor 1.6.8 から 2.x 系へバージョンアップしたい - 1.x 系から 2.x 系で破壊的な仕様変更が数多くなされている - feature から plugin への変更や、 API テストの書き⽅の変更など - 主な変更は 公式のドキュメント にあるがそれだけでも結構多い - 1.6.8 から 2.0.3 への移⾏の知⾒はあった - 別のマイクロサービスで移⾏済みのため - 今回は 1.6.8 から実施当時最新の 2.2.4 へ移⾏する - 2023/06/22 現在の最新は 2.3.1
9. - 移⾏⽅針 (後述) - 検証⼿段 - 必須 : サーバサイドの結合的な⾃動テスト - Ktor のテストフレームワークを利⽤ - 任意 : システム全体のリグレッションテスト - ⼤まかなスケジュールの確保 - 移⾏作業, リグレッションテスト 事前準備
10. - 基本的には公式のマイグレーションガイドに従う - 変更は最⼩限に留める - 他の開発を可能な限り⽌めない - 安全に移⾏する ⽅針
11. 移⾏準備
12. マイグレーションガイドとリリースノートの確認 まずは何がどう変わるかについて把握する 移⾏作業中や作業後に問題が発覚した際に原因の⾒当がつきやすくなる - 公式のマイグレーションガイド - 1.6.x → 2.0.x - 2.0.x → 2.2.x - リリースノート⼀覧 - 2.0.1 以降は YouTrack のリンクもあるので、必要に応じて確認する - DeepL や ChatGPT などを頼ると便利
13. IntelliJ IDEA の機能である程度移⾏できるため、最初にこれを実施する - “Migrate Project to Latest Ktor Version…” を実⾏ - ソースコード量に依るがそれなりに時間がかかる - 他の作業と混ざるとロールバックしづらくなるため、マイグレーションツール が実⾏完了した段階で⼀度コミットしておく - 以降コンパイル可能 (= 動作確認が可能) になるまで必要な作業が多いため、1 作業ごとにコミットしておくと後で確認しやすくなる マイグレーションツールの実⾏
14. - 右図を始め構⽂が壊れたところを修正 - バージョンを定数化したい場合は それも対応する コンパイルエラーの修正 - build.gradle.kts マイグレーションツール実⾏ ⼿動で修正
15. Feature から Plugin に名前が変わり、パッケージやインタフェースも変更さ れている - StatusPage - DataConversion - Authentication - etc …… コンパイルエラーの修正 - Plugin
16. プラグインの作成⽅法が変わったため再実装する - 1.x : Base API をもとに Ktor の内部構造を意識して Feature を作成 - 2.x : 新 API をもとに Plugin を作成 - createApplicationPlugin や createRouteScopedPlugin など これも⼤まかなマイグレーションガイドがあるためそれに従う コンパイルエラーの修正 - Custom Plugin
17. マイグレーションツールでまかなえなかったところや Deprecated となって いる API に対応する - nullable な body - MultiPart のパッケージ変更 - etc …… コンパイルエラーの修正 - ApplicationCall
18. ContentNegotiation プラグインが例外翻訳するようになった - 例外を Controller や StatusPage プラグイン等で⾃前でハンドリングしている場 合は確認が必要 - 2.x 系から何度か改修が⼊っているため要注意 (KTOR-5410 など) 失敗したテストへの対応 - 例外翻訳 JacksonConverter.deserialize で例外をスローしている箇所 RequestConverter で body を convert した際に例外翻訳している箇所 (画像のコードの出典)
19. テスト⽤アプリケーションの挙動が変わり例外をキャッチできなくなった 本来結合テストではアプリケーションの外から⾒た挙動をテストすべきであ るため、テストコードを修正 失敗したテストへの対応 - 例外送出を期待する結合テスト
20. クエリ⽂字列の扱いがバージョンや プラグインによって少しずつ異なる - 必須パラメータが⽋落した場合 (KTOR-447) - Ktor 1.6.8 : 404 NotFound - Ktor 2.2.4 : 400 BadRequest - パラメータ名のみの場合 (例: /foo?param) - Ktor 1.6.8 w/ Location Feature : 400 BadRequest - Ktor 2.2.4 w/ Location Plugin : IllegalArgumentException - Ktor 2.2.4 w/ Resource Plugin : 400 BadRequest クエリ⽂字列のパース時の挙動の変化
21. (参考) クエリ⽂字列の扱いの変遷まとめ (指定なし) param (名前のみ) param= (右辺なし) param=42 (指定あ り) Ktor 1.6.8 (@Location) 必須パラメータ 404 NotFound 400 BadRequest 400 BadRequest 200 OK Ktor 1.6.8 (@Location) 任意パラメータ 200 OK 400 BadRequest 400 BadRequest 200 OK Ktor 2.2.4 (@Location) 必須パラメータ 400 BadRequest IllegalArgumentException 400 BadRequest 200 OK Ktor 2.2.4 (@Location) 任意パラメータ 200 OK IllegalArgumentException 400 BadRequest 200 OK Ktor 2.2.4 (@Resource) 必須パラメータ 400 BadRequest 400 BadRequest 400 BadRequest 200 OK Ktor 2.2.4 (@Resource) 任意パラメータ 200 OK 400 BadRequest 400 BadRequest 200 OK 検証時の実装 - Ktor 1.6.8 - Ktor 2.2.4 (Location Plugin) - Ktor 2.2.4 (Resource Plugin)
22. - Location プラグインから Resource プラグインへの移⾏ - 間に合わなかったため後⽇対応 - Testing API の移⾏ - テスト⾃体の挙動が変わらないこと担保するため - 共通化した処理を含む withTestApplication のラッパーを作っているため スキップした対応
23. - 重点的にレビューすべきことの整理 - コードのレビュー時に本質的な内容をレビューしてもらうため - 重点的に検証すべきことの整理 - ロギングなどライブラリに頼っている部分など - 移⾏の本番にむけて - リグレッションテスト⼯数の確保 - コードフリーズ期間の確保 - 修正範囲が広く確実にコンフリクトするため - 移⾏作業者がコンフリクトの解消をするより各機能の実装者が解消したほうが 安全なため その他の準備
24. 1. ひたすら cherry-pick - 移⾏準備とそのレビューで時間が経過しているため、レビュー内容を維持し つつコンフリクトを最⼩限にすべく、新たなブランチで実施 - できれば rebase のほうが良い 2. API テスト 3. リグレッションテスト 4. リリース 3⽇確保していたが、1⽇強で完了 🎉 移⾏本番
25. まとめ
26. まとめ - ⼗分な検証内容および検証⼿段があれば安全に移⾏できる - 公式のマイグレーションガイドや先⼈の知恵によりスムーズに進められる - メモを残しておくと必ず誰かの役に⽴つので⼤事 - 予めコードフリーズ等の調整をすることで混乱なく進められる