$30 off During Our Annual Pro Sale. View Details »

[2023/09/15]ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

tosite
September 21, 2023

[2023/09/15]ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

tosite

September 21, 2023
Tweet

More Decks by tosite

Other Decks in Programming

Transcript

  1. ER図クエスト 

    過ぎ去りしドキュメントを求めて

    〜複雑性に眠る秘宝〜

    株式会社マネーフォワード

    クラウド経費本部 プロダクト開発部

    手島 尚人 / tosite

    2023-09-15

    7th長崎QDG

    DEJIMAメッセ長崎


    View Slide

  2. 初めまして

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  3. View Slide

  4. 株式会社マネーフォワード 

    クラウド経費本部 プロダクト開発部

    バックエンドエンジニア

    手島 尚人 / tosite


    趣味:

    キャンプ・登山・料理・ドライブ・温泉

    三線 ← New!


    View Slide

  5. 福岡から来ました!

    前々職の関係で5年ほど長崎に住んでいました

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  6. JaSST'23 Kyushu

    の実行委員長やってます!

    https://www.jasst.jp/symposium/jasst23kyushu.html

    View Slide

  7. 2023-11-02に

    福岡で開催

    予定なので興味ある方はぜひ!

    https://www.jasst.jp/symposium/jasst23kyushu.html

    View Slide

  8. 本題: 起

    ここまで0:45


    View Slide

  9. 今年の8月

    からマネーフォワードでの

    キャリアをスタートしました

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  10. 皆さんは入社して

    まず何をしますか?

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  11. ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  12. times芸人業ですね

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜
    チームリーダーからの評価


    View Slide

  13. …ですが

    今日話したいのはその話ではなく…

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  14. まずやることは

    ドメイン知識を身につける

    ところからだと思います

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  15. では皆さんはどうやって

    ドメインを理解しますか?

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  16. 仕様書やドキュメントを読む!


    View Slide

  17. ドキュメントが充実している

    プロダクトならいざしらず、必要十分な

    ドキュメントがない場合もあります

    理想と現実

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  18. コードから全てを理解する


    View Slide

  19. 配属当初から全てのコードを網羅的に

    読み込むのはなかなかに厳しいと思います

    木は見えるけど森は見えない

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  20. じゃあどうするの?


    View Slide

  21. データベースから

    仕様を理解する

    ことが早いと思っています

    私の経験に基づいた一例ですが…

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  22. そんな私がマネーフォワードに入社して1ヶ月

    どのような取り組みをしてきたかを

    お話ししようと思います

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  23. 本題: 承

    ここまで2:00


    View Slide

  24. データベースの仕様書と言えば

    真っ先に思い浮かぶものがありますね

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  25. そう、ER図ですね

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  26. でも作るの大変だし

    何よりメンテが大変…

    大変じゃない?

    https://github.com/k1LoW/tbls

    View Slide

  27. 私は

    tblsというOSS

    をこの上なく愛しています

    https://github.com/k1LoW/tbls

    View Slide

  28. 端的に言えば

    データベースドキュメント

    自動生成ツール

    開発者の方は「Document as Code」というキーワードを使われています

    https://speakerdeck.com/k1low/phpconfuk-2023

    View Slide

  29. https://github.com/k1LoW/tbls
    参考: 出力イメージ


    View Slide

  30. 仕様理解・開発スピードの向上

    を目的としてこのツールの導入を進めました

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  31. 実装イメージ

    https://github.com/k1LoW/tbls

    View Slide

  32. Phase 1. ローカルに

    ドキュメント生成環境を準備

    https://github.com/k1LoW/tbls

    View Slide

  33. Phase 1. ローカルにドキュメント生成環境を準備 

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜
    tblsのインストールと

    ymlファイルを準備しただけ!


    あとはMakefileに便利コマンドを

    追加した程度の開発

    1.ローカルのDBをマイグレーション

     ファイルから構築

    2.tbls.ymlを作成

    3.コマンドを実行してデータベース

     ドキュメントを生成

    View Slide

  34. Phase 2. CIでドキュメントの

    ビハインドを検知する

    https://github.com/k1LoW/tbls

    View Slide

  35. Phase 2. CIでドキュメントのビハインドを検知する 

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜
    CIで利用されるテーブルは常に

    最新になることを利用

    コミットされているドキュメントと

    最新のドキュメントに差分がある

    場合はCIを落とすようにした

    1.CIのDBをマイグレーション

     ファイルから構築

    2.CIのデータベースドキュメントを生成

    3.CIとコミットしたデータベース

     ドキュメントの差分を検知

    View Slide

  36. ER図が作られただけではなく

    データベースドキュメントが

    最新の状態に保たれる

    仕組みが構築できました

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  37. ドキュメントを最新の状態に

    維持し続けていくのが一番難しい…

    ここを仕組みで解決しました

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  38. 更にビハインド発生時の

    マニュアルを整備する

    ことで他の開発者向けに情報を残しました

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  39. これでデータベース

    ドキュメントについては完璧!

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  40. 本題: 転

    ここまで4:00


    View Slide

  41. …というわけではなく、

    まだまだ課題は残っています

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  42. テーブルごとの意味を持つまとまりを

    どう表現するかが課題です

    例えばユーザーの基本情報が格納されているテーブル群だったり

    契約情報がまとまっているテーブル群だったり…

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  43. tblsには「ラベル」

    という概念があります

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  44. テーブルにラベルを付与して

    ラベル単位でもドキュメントを出力する

    仕組みを検討しています

    更に開発者フレンドリーなドキュメントが生成できますね

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  45. 他にも「Viewpoints」という

    概念を用いてドキュメントを追加する

    こともできるでしょう

    https://speakerdeck.com/k1low/phpconfuk-2023?slide=34

    View Slide

  46. また、他のアプローチとして

    モデルに定義されている

    定義を機械的に収集した上で

    反映させることもできそうです

    https://speakerdeck.com/k1low/phpconfuk-2023?slide=34

    View Slide

  47. ツールを入れて終わり

    ではなく

    ドキュメントを整備し続ける

    ことが大事ですね

    https://speakerdeck.com/k1low/phpconfuk-2023?slide=34

    View Slide

  48. 本題: 結

    ここまで4:30


    View Slide

  49. 以上の取り組みによって

    アプリケーションの仕様を

    データベースから理解する

    ことができるようになりました

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  50. ドキュメントは宝の山

    だと思っています

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  51. 今回取り入れた仕組みを通して

    オンボーディングの高速化などに

    役立てばいいなと思っています

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  52. みなさんもドキュメント化

    やっていきましょう💪

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  53. 終わりに

    ここまで4:50


    View Slide

  54. マネーフォワード福岡拠点では

    一緒に働ける仲間を募集しています!

    https://hrmos.co/pages/moneyforward/jobs?category=1666323298559537153 

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  55. 福岡開発拠点のサイトもあるので

    ぜひご覧ください!

    https://fukuoka.moneyforward.com 

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  56. 一緒にドキュメント化を

    進めていきたいという方は

    ぜひお声がけください

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide

  57. ご清聴ありがとう

    ございました!

    ER図クエスト 過ぎ去りしドキュメントを求めて 〜複雑性に眠る秘宝〜

    View Slide