让我们创建一个在整个项目中受到重视的精简明了的README文件吧！

2 年 ago

韵, 科

7 minutes

README是指阅读我文档，即阅读我这个文件的说明。

使用方法や仕様に関する情報を提供するためのドキュメントです。このドキュメントにはアプリケーションの基本的な機能の説明や使い方、トラブルシューティングの情報などが含まれています。アプリケーションを使用する前に、必ずこのREADMEを参照してください。

環境構築手順

这是一个文件，它包含了项目所需的所有信息。本次我们将解释如何在GitHub等平台上编写简洁明了的README文件。

写README的目的是什么？

当在项目中有新成员加入时，通过编写README文档，包含项目概述和所需文档的链接，可以方便新成员理解项目，同时也可以减少不必要的沟通成本。此外，如果还包括环境配置的步骤，那么无论个人技术水平如何，任何人都能够进行开发构建。希望大家能够务必写进去。

我希望在README中添加以下内容。

あくまで一例ですが私が普段READMEに記載しているのは以下の通りです

トラブルシューティング

那么，我们逐个来看吧。

主要的技术使用

どんな技術を使っているかはディレクトリ構成やファイルなどでなんとなくわかりますが
プロジェクトで使用している技術に疎い人が見ると見づらいのでは？と感じたので私はSheildを冒頭につけています

Sheid是什么

Shield是一种类似于徽章的东西，可以贴在README等MarkDown文件上。

请您参考以下网站获得详细信息。

使用img标签创建。具体结构如下：

<img src="https://img.shields.io/badge/-{言語、フレームワーク名など}-{シールドのカラーコード}.svg?logo=next.js&style={バッチのスタイル}&logoColor={ロゴのカラーコード}">

由于不同的项目使用不同的技术，请从以下选择中选择并贴上。

前端框架

前端编程语言

后台框架

后端语言

中间件

基础设施

其他

您可以在以下网站创建未在此处列出的批处理。

项目简介

请把注意力放在这里

プロジェクトの詳細が記載された資料のリンク

为了了解项目的详细信息，我们将在README文档中提供项目概述和开发环境构建方法。然而，请参考Backlog等项目管理工具以获取详细的项目信息。

必需的环境变量和命令列表

由於環境變數和命令列表只有部分人知道，且容易變成黑盒，因此會列出一份完整的清單。

环境变量

以下是我在我常用的Django项目中使用的环境变量示例。
请根据您使用的框架自由进行记录。

変数名役割デフォルト値DEV 環境での値MYSQL_ROOT_PASSWORDMySQL のルートパスワード（Docker で使用）root
MYSQL_DATABASEMySQL のデータベース名（Docker で使用）django-db
MYSQL_USERMySQL のユーザ名（Docker で使用）django
MYSQL_PASSWORDMySQL のパスワード（Docker で使用）django
MYSQL_HOSTMySQL のホスト名（Docker で使用）db
MYSQL_PORTMySQL のポート番号（Docker で使用）3306
SECRET_KEYDjango のシークレットキーsecretkey他者に推測されないランダムな値にすることALLOWED_HOSTSリクエストを許可するホスト名localhost 127.0.0.1 [::1] back webフロントのホスト名DEBUGデバッグモードの切り替えTrueFalseTRUSTED_ORIGINSCORS で許可するオリジンhttp://localhost
DJANGO_SETTINGS_MODULEDjango アプリケーションの設定モジュールproject.settings.localproject.settings.dev

指令列表

由于我使用Makefile来执行命令

コマンドを実行する際に起こる処理

我认为使用「写上」这个词可能会更容易理解。

Dockerを使い慣れてない新人

将其记录下来，以便可以随时参考，非常方便。

Make実行する処理元のコマンドmake preparenode_modules のインストール、イメージのビルド、コンテナの起動を順に行うdocker-compose run –rm front npm install
docker-compose up -d –buildmake upコンテナの起動docker-compose up -dmake buildイメージのビルドdocker-compose buildmake downコンテナの停止docker-compose downmake loaddataテストデータの投入docker-compose exec app poetry run python manage.py loaddata crm.jsonmake makemigrationsマイグレーションファイルの作成docker-compose exec app poetry run python manage.py makemigrationsmake migrateマイグレーションを行うdocker-compose exec app poetry run python manage.py migratemake show_urlsエンドポイントをターミナル上で一覧表示docker-compose exec app poetry run python manage.py show_urlsmake shellテストデータの投入docker-compose exec app poetry run python manage.py debugsqlshellmake superuserスーパーユーザの作成docker-compose exec app poetry run python manage.py createsuperusermake testテストを実行docker-compose exec app poetry run pytestmake test-covカバレッジを表示させた上でテストを実行docker-compose exec app poetry run pytest –covmake formatblack と isort を使ってコードを整形docker-compose exec app poetry run black .
docker-compose exec app poetry run isort .make updatePoetry 内のパッケージの更新docker-compose exec app poetry updatemake appアプリケーションのコンテナへ入るdocker exec -it app bashmake dbデータベースのコンテナへ入るdocker exec -it db bashmake pdocpdoc ドキュメントの作成docker-compose exec app env CI_MAKING_DOCS=1 poetry run pdoc -o docs applicationmake initTerraform の初期化docker-compose -f infra/docker-compose.yml run –rm terraform initmake fmtTerraform の設定ファイルをフォーマットdocker-compose -f infra/docker-compose.yml run –rm terraform fmtmake validateTerraform の構成ファイルが正常であることを確認docker-compose -f infra/docker-compose.yml run –rm terraform validatemake show現在のリソースの状態を参照docker-compose -f infra/docker-compose.yml run –rm terraform showmake applyTerraform の内容を適用docker-compose -f infra/docker-compose.yml run –rm terraform applymake destroyTerraform で構成されたリソースを削除docker-compose -f infra/docker-compose.yml run –rm terraform destroy

故障排除

如果按照步骤进行环境配置，但仍无法完成，我们设有故障排除指南。主要整理了与Docker相关的错误。

### .env: no such file or directory

.env ファイルがないので環境変数の一覧を参考に作成しましょう

### docker daemon is not running

Docker Desktop が起動できていないので起動させましょう

### Ports are not available: address already in use

別のコンテナもしくはローカル上ですでに使っているポートがある可能性があります
<br>
下記記事を参考にしてください
<br>
[コンテナ起動時に Ports are not available: address already in use が出た時の対処法について](https://qiita.com/shun198/items/ab6eca4bbe4d065abb8f)

### Module not found

make build

を実行して Docker image を更新してください

模板示例

以下是我使用的README模板。除了上面提到的内容，例如

ディレクトリ構成

如果您有任何想要的信息，我认为可以适当添加，并包括相关内容。

<div id="top"></div>

## 使用技術一覧

<!-- シールド一覧 -->
<!-- 該当するプロジェクトの中から任意のものを選ぶ-->
<p style="display: inline">
  <!-- フロントエンドのフレームワーク一覧 -->
  <img src="https://img.shields.io/badge/-Node.js-000000.svg?logo=node.js&style=for-the-badge">
  <img src="https://img.shields.io/badge/-Next.js-000000.svg?logo=next.js&style=for-the-badge">
  <img src="https://img.shields.io/badge/-TailwindCSS-000000.svg?logo=tailwindcss&style=for-the-badge">
  <img src="https://img.shields.io/badge/-React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB">
  <!-- バックエンドのフレームワーク一覧 -->
  <img src="https://img.shields.io/badge/-Django-092E20.svg?logo=django&style=for-the-badge">
  <!-- バックエンドの言語一覧 -->
  <img src="https://img.shields.io/badge/-Python-F2C63C.svg?logo=python&style=for-the-badge">
  <!-- ミドルウェア一覧 -->
  <img src="https://img.shields.io/badge/-Nginx-269539.svg?logo=nginx&style=for-the-badge">
  <img src="https://img.shields.io/badge/-MySQL-4479A1.svg?logo=mysql&style=for-the-badge&logoColor=white">
  <img src="https://img.shields.io/badge/-Gunicorn-199848.svg?logo=gunicorn&style=for-the-badge&logoColor=white">
  <!-- インフラ一覧 -->
  <img src="https://img.shields.io/badge/-Docker-1488C6.svg?logo=docker&style=for-the-badge">
  <img src="https://img.shields.io/badge/-githubactions-FFFFFF.svg?logo=github-actions&style=for-the-badge">
  <img src="https://img.shields.io/badge/-Amazon%20aws-232F3E.svg?logo=amazon-aws&style=for-the-badge">
  <img src="https://img.shields.io/badge/-terraform-20232A?style=for-the-badge&logo=terraform&logoColor=844EBA">
</p>

## 目次

1. [プロジェクトについて](#プロジェクトについて)
2. [環境](#環境)
3. [ディレクトリ構成](#ディレクトリ構成)
4. [開発環境構築](#開発環境構築)
5. [トラブルシューティング](#トラブルシューティング)

<!-- READMEの作成方法のドキュメントのリンク -->
<br />
<div align="right">
    <a href="READMEの作成方法のリンク"><strong>READMEの作成方法 »</strong></a>
</div>
<br />
<!-- Dockerfileのドキュメントのリンク -->
<div align="right">
    <a href="Dockerfileの詳細リンク"><strong>Dockerfileの詳細 »</strong></a>
</div>
<br />
<!-- プロジェクト名を記載 -->

## プロジェクト名

React、DRF、Terraform のテンプレートリポジトリ

<!-- プロジェクトについて -->

## プロジェクトについて

React、DRF、Terraform を勉強する際に使用できるテンプレート

<!-- プロジェクトの概要を記載 -->

  <p align="left">
    <br />
    <!-- プロジェクト詳細にBacklogのWikiのリンク -->
    <a href="Backlogのwikiリンク"><strong>プロジェクト詳細 »</strong></a>
    <br />
    <br />

<p align="right">(<a href="#top">トップへ</a>)</p>

## 環境

<!-- 言語、フレームワーク、ミドルウェア、インフラの一覧とバージョンを記載 -->

| 言語・フレームワーク  | バージョン |
| --------------------- | ---------- |
| Python                | 3.11.4     |
| Django                | 4.2.1      |
| Django Rest Framework | 3.14.0     |
| MySQL                 | 8.0        |
| Node.js               | 16.17.0    |
| React                 | 18.2.0     |
| Next.js               | 13.4.6     |
| Terraform             | 1.3.6      |

その他のパッケージのバージョンは pyproject.toml と package.json を参照してください

<p align="right">(<a href="#top">トップへ</a>)</p>

## ディレクトリ構成

<!-- Treeコマンドを使ってディレクトリ構成を記載 -->

❯ tree -a -I "node_modules|.next|.git|.pytest_cache|static" -L 2
.
├── .devcontainer
│   └── devcontainer.json
├── .env
├── .github
│   ├── action
│   ├── release-drafter.yml
│   └── workflows
├── .gitignore
├── Makefile
├── README.md
├── backend
│   ├── .vscode
│   ├── application
│   ├── docs
│   ├── manage.py
│   ├── output
│   ├── poetry.lock
│   ├── project
│   └── pyproject.toml
├── containers
│   ├── django
│   ├── front
│   ├── mysql
│   └── nginx
├── docker-compose.yml
├── frontend
│   ├── .gitignore
│   ├── README.md
│   ├── __test__
│   ├── components
│   ├── features
│   ├── next-env.d.ts
│   ├── package-lock.json
│   ├── package.json
│   ├── pages
│   ├── postcss.config.js
│   ├── public
│   ├── styles
│   ├── tailwind.config.js
│   └── tsconfig.json
└── infra
    ├── .gitignore
    ├── docker-compose.yml
    ├── main.tf
    ├── network.tf
    └── variables.tf

<p align="right">(<a href="#top">トップへ</a>)</p>

## 開発環境構築

<!-- コンテナの作成方法、パッケージのインストール方法など、開発環境構築に必要な情報を記載 -->

### コンテナの作成と起動

.env ファイルを以下の環境変数例と[環境変数の一覧](#環境変数の一覧)を元に作成

.env
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=django-db
MYSQL_USER=django
MYSQL_PASSWORD=django
MYSQL_HOST=db
MYSQL_PORT=3306
SECRET_KEY=django
DJANGO_SETTINGS_MODULE=project.settings.local


.env ファイルを作成後、以下のコマンドで開発環境を構築

make prepare

### 動作確認

http://127.0.0.1:8000 にアクセスできるか確認
アクセスできたら成功

### コンテナの停止

以下のコマンドでコンテナを停止することができます

make down

### 環境変数の一覧

| 変数名                 | 役割                                      | デフォルト値                       | DEV 環境での値                           |
| ---------------------- | ----------------------------------------- | ---------------------------------- | ---------------------------------------- |
| MYSQL_ROOT_PASSWORD    | MySQL のルートパスワード（Docker で使用） | root                               |                                          |
| MYSQL_DATABASE         | MySQL のデータベース名（Docker で使用）   | django-db                          |                                          |
| MYSQL_USER             | MySQL のユーザ名（Docker で使用）         | django                             |                                          |
| MYSQL_PASSWORD         | MySQL のパスワード（Docker で使用）       | django                             |                                          |
| MYSQL_HOST             | MySQL のホスト名（Docker で使用）         | db                                 |                                          |
| MYSQL_PORT             | MySQL のポート番号（Docker で使用）       | 3306                               |                                          |
| SECRET_KEY             | Django のシークレットキー                 | secretkey                          | 他者に推測されないランダムな値にすること |
| ALLOWED_HOSTS          | リクエストを許可するホスト名              | localhost 127.0.0.1 [::1] back web | フロントのホスト名                       |
| DEBUG                  | デバッグモードの切り替え                  | True                               | False                                    |
| TRUSTED_ORIGINS        | CORS で許可するオリジン                   | http://localhost                   |                                          |
| DJANGO_SETTINGS_MODULE | Django アプリケーションの設定モジュール   | project.settings.local             | project.settings.dev                     |

### コマンド一覧

| Make                | 実行する処理                                                            | 元のコマンド                                                                               |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| make prepare        | node_modules のインストール、イメージのビルド、コンテナの起動を順に行う | docker-compose run --rm front npm install<br>docker-compose up -d --build                  |
| make up             | コンテナの起動                                                          | docker-compose up -d                                                                       |
| make build          | イメージのビルド                                                        | docker-compose build                                                                       |
| make down           | コンテナの停止                                                          | docker-compose down                                                                        |
| make loaddata       | テストデータの投入                                                      | docker-compose exec app poetry run python manage.py loaddata crm.json                      |
| make makemigrations | マイグレーションファイルの作成                                          | docker-compose exec app poetry run python manage.py makemigrations                         |
| make migrate        | マイグレーションを行う                                                  | docker-compose exec app poetry run python manage.py migrate                                |
| make show_urls      | エンドポイントをターミナル上で一覧表示                                  | docker-compose exec app poetry run python manage.py show_urls                              |
| make shell          | テストデータの投入                                                      | docker-compose exec app poetry run python manage.py debugsqlshell                          |
| make superuser      | スーパーユーザの作成                                                    | docker-compose exec app poetry run python manage.py createsuperuser                        |
| make test           | テストを実行                                                            | docker-compose exec app poetry run pytest                                                  |
| make test-cov       | カバレッジを表示させた上でテストを実行                                  | docker-compose exec app poetry run pytest --cov                                            |
| make format         | black と isort を使ってコードを整形                                     | docker-compose exec app poetry run black . <br> docker-compose exec app poetry run isort . |
| make update         | Poetry 内のパッケージの更新                                             | docker-compose exec app poetry update                                                      |
| make app            | アプリケーション のコンテナへ入る                                       | docker exec -it app bash                                                                   |
| make db             | データベースのコンテナへ入る                                            | docker exec -it db bash                                                                    |
| make pdoc           | pdoc ドキュメントの作成                                                 | docker-compose exec app env CI_MAKING_DOCS=1 poetry run pdoc -o docs application           |
| make init           | Terraform の初期化                                                      | docker-compose -f infra/docker-compose.yml run --rm terraform init                         |
| make fmt            | Terraform の設定ファイルをフォーマット                                  | docker-compose -f infra/docker-compose.yml run --rm terraform fmt                          |
| make validate       | Terraform の構成ファイルが正常であることを確認                          | docker-compose -f infra/docker-compose.yml run --rm terraform validate                     |
| make show           | 現在のリソースの状態を参照                                              | docker-compose -f infra/docker-compose.yml run --rm terraform show                         |
| make apply          | Terraform の内容を適用                                                  | docker-compose -f infra/docker-compose.yml run --rm terraform apply                        |
| make destroy        | Terraform で構成されたリソースを削除                                    | docker-compose -f infra/docker-compose.yml run --rm terraform destroy                      |

### リモートデバッグの方法

リモートデバッグ を使用する際は以下の url を参考に設定してください<br>
[Django のコンテナへリモートデバッグしよう！](https://qiita.com/shun198/items/9e4fcb4479385217c323)

## トラブルシューティング

### .env: no such file or directory

.env ファイルがないので環境変数の一覧を参考に作成しましょう

### docker daemon is not running

Docker Desktop が起動できていないので起動させましょう

### Ports are not available: address already in use

別のコンテナもしくはローカル上ですでに使っているポートがある可能性があります
<br>
下記記事を参考にしてください
<br>
[コンテナ起動時に Ports are not available: address already in use が出た時の対処法について](https://qiita.com/shun198/items/ab6eca4bbe4d065abb8f)

### Module not found

make build

を実行して Docker image を更新してください

<p align="right">(<a href="#top">トップへ</a>)</p>

模板设置方法

如果有一份您想在其他项目中使用的README作为模板，您可以在”设置”中勾选”模板存储库”，然后以后创建新仓库时可以基于该模板创建。

总结

有没有README对于加入新项目的障碍和负担是完全不同的，而且README也是项目的一个形象，所以虽然麻烦但认真制作是非常好的一件事。希望我发布的模板能对某人有所帮助。