LaravelリポジトリのREADME.mdを改善しました!
オンライン家庭教師マナリンク CTOの名人です。
今週新しくWebエンジニアの方に参画していただくことになりましたので、LaravelリポジトリのREADME.mdファイルを改善しました。
この記事では改善した内容と、改善した結果足りなかった情報に対する反省点をまとめようと思います。
README.mdとは?
GitHub上に作成したリポジトリのルートディレクトリにREADME.mdという名前のマークダウンファイルを置くと、暗黙のルールとして開発者に対して読むべきドキュメントであると示すことができます。
したがって、環境構築手順であったり、開発にあたっての全体感を書く場所に適しています。
私個人のやり方としてはルートディレクトリだけではなく、開発に使っている各ディレクトリに意識的にREADME.mdを置くようにしています。それによってディレクトリを使った意思を後世に残すようにしています。この辺については機会があれば別の記事でお話します。
README.mdの構成
環境構築手順(Makefile)
環境構築手順は、今回からmakeコマンドを使って8割方の環境構築を済ませることができるように工夫しました。これまでdocker-composeコマンドを地道に叩いていました。
$ make init
makeコマンドの仕様について私は詳しく知りませんが、以下のリポジトリを参考に進めることができました。
https://github.com/ucan-lab/docker-laravel/blob/main/Makefile
ルートディレクトリにMakefileというファイルを作成し、コマンドをグルーピングしてラベルを付けます。するとmake ラベル名というコマンドでそのコマンド群を実行することができます。
無機質なコマンド群に意味のあるラベルをつけることでドキュメンテーションの効果があります。
init:
docker-compose up -d --build
docker-compose exec php-fpm cp .env.local .env
docker-compose exec php-fpm php artisan key:generate
docker-compose exec php-fpm chmod -R 777 storage bootstrap/cache
@make fresh
src-update:
@make install
@make migrate
migrate:
docker-compose exec app php artisan migrate
install:
docker-compose exec php-fpm composer install
fresh:
docker-compose exec php-fpm php artisan migrate:fresh
rollback-test:
docker-compose exec app php artisan migrate:fresh
docker-compose exec app php artisan migrate:refresh
seed:
docker-compose exec php-fpm php artisan db:seed
fresh-seed:
docker-compose exec php-fpm php artisan migrate:fresh --seed
test-data-seed:
docker-compose exec php-fpm php artisan db:seed --class=RawDataSeeder
以下略
このように書けば、以下のようなコマンドで色々と実行できます。
$ make init // 初期環境構築
$ make ide-helper // ide-helperファイル作成
$ make cache-clear // 困ったときのキャッシュクリア
自分オリジナルのコマンドとして、make test-data-seedというものを用意しました。これはローカル開発用にだけ使う便利なテストデータを入れるコマンドです。Seederを作り込めば良いのですが、本番環境にあるようなリアルな先生のプロフィールや指導コースを使うほうが開発の捗るので、定期的に本番のそういった公開情報をローカルに持ってくるためにこのようなコマンドを作っておきました。
テスト用アカウント
ローカル環境でUserSeederを実行して設定された各種アカウントへのログイン情報を記載しています。
ローカル環境へのアクセス
https://localhost へのアクセスを行います。
■反省点
ここで、Chromeがlocalhostに対するオレオレ証明書に対して警告を出してアクセスできない問題が頻発するので、Chromeの設定を変更しなければなりません。その点の追記が漏れていたため環境構築に手間が掛かりました。
また、今回加わっていただいたエンジニアの方から、localhostからmanalink.localhost.comといった名前のドメインに変更し、/etc/hostsを書き換える運用にして、mkcertというツールで証明書を発行すれば良いのでは、という提案がありました。こちらは今後試してみたいと思います。
アーキテクチャ
アーキテクチャについても説明をしています。今回は自分の思考整理も兼ねて、日頃実装しているController、UseCase、Repositoryなどのクラスの依存関係を図にまとめてみました。
原則UseCase(単一メソッドのクラスで、Controllerから依存される)まで実装必須です。そしてドメインが複雑になってくる決済周りではEntityやValueObjectも実装しているため、そのへんまで含めた図になっています。
■反省点
routes周りの各ファイルについて解説するのが漏れていました。弊社のLaravelサーバーは主にNuxtのフロントエンドからアクセスされるAPIを提供していますが、管理画面向けのAPIや、一部ネイティブアプリ経由のAPIを提供しています。このあたりはrouteファイルごと分けているのですが、ここに関する解説がREADMEまたは各ファイルにあったほうが親切でした。
その他
以下のような内容について記載していますが、サクッと書いてあとは実際のファイルを読めばいいという感じにしてあります。
- GitHub Actionsを用いたデプロイフロー
- mailhogコンテナによるローカル環境でのメールテスト
- フレームワークや言語等の各種バージョン
- https://localhost/debug を見るとdebugbarが見れる旨
以上になります。
引き続きエンジニアを募集しています。オンライン家庭教師事業に興味を持っていただけましたらぜひご連絡ください。