Python | テスト・設計・品質：フォルダ構成標準化

Python Python
スポンサーリンク

フォルダ構成標準化って何？一言でいうと「どのプロジェクトでも迷子にならないための地図づくり」

フォルダ構成標準化は、
「Pythonプロジェクトのフォルダやファイルの置き方に、共通ルールを決めること」です。

どのプロジェクトもバラバラな構成だと、

どこに本体コードがあるのか
どこにテストがあるのか
設定ファイルはどこか

毎回探すところから始まります。

逆に、構成が標準化されていると、

初めて触るプロジェクトでも「だいたいここだな」と当たりがつく
ツール（テスト、型チェック、CIなど）が自動で動かしやすい
リファクタリングや分割がしやすい

というメリットが出てきます。

まずは「よくあるPythonプロジェクト構成」を一つ覚える

シンプルな標準構成の例

典型的な構成を、まず一つ“型”として持っておくと楽です。

myapp/
  pyproject.toml
  README.md
  src/
    myapp/
      __init__.py
      domain.py
      services.py
      infra.py
  tests/
    test_domain.py
    test_services.py

ここで押さえたいポイントは3つです。

src/ の下にアプリ本体のパッケージを置く（src/myapp/）
テストは tests/ にまとめる
設定・メタ情報（pyproject.toml, README.md など）はルートに置く

この「src レイアウト」は、最近のPython界隈でよく使われるパターンです。

なぜ src/ 配下にコードを置くのかをちゃんと理解する

ルート直下に置く構成との違い

よくあるもう一つの構成はこれです。

myapp/
  myapp/
    __init__.py
    domain.py
    services.py
  tests/
    test_domain.py

これも動きます。
ただし、開発中に「カレントディレクトリがルート」であることに依存しがちです。

python -m myapp.domain
pytest（ルートで実行）

など、「たまたま動いている」状態になりやすい。

src/ レイアウトにすると、

myapp/
  src/
    myapp/
      ...
  tests/
      ...

インポートの解決が「インストールされたパッケージ」に依存する形になり、
本番環境と開発環境の差が減ります。

「テストでは動くのに、本番では動かない」を防ぐ

src/ レイアウトの一番大きなメリットは、

「テスト環境と本番環境で、インポートの前提が揃う」

ことです。

src/ を使わずにルート直下に置いていると、
テストでは PYTHONPATH にルートが入っているから動くけど、
本番でパッケージとしてインストールすると壊れる、という事故が起きがちです。

src/ レイアウトにしておけば、

開発中も「インストールされたパッケージ」として扱う前提で設計できる
インポートのバグが早めに見つかる

という品質面のメリットがあります。

フォルダ構成と「責務の分離」をリンクさせる

フォルダは「役割ごと」に分ける

フォルダ構成標準化は、単に見た目を揃えるだけではなく、
「責務の分離」とセットで考えると一気に強くなります。

例えば、src/myapp/ の中をこう分けるイメージです。

src/
  myapp/
    __init__.py
    domain/
      __init__.py
      models.py
      services.py
    infra/
      __init__.py
      db.py
      external_api.py
    presentation/
      __init__.py
      cli.py
      rest.py

ここでの考え方はシンプルです。

domain/ はビジネスロジック（ドメインモデル・ドメインサービス）
infra/ は外部との接続（DB・外部API・メッセージキューなど）
presentation/ は入口（CLI・REST API など）

フォルダ構成を「層」と対応させることで、

どこに何を書くべきか迷わなくなる
どこをテストすべきかが分かりやすくなる
依存関係（内側→外側）が見えやすくなる

という設計・品質のメリットが出てきます。

テストフォルダの構成も標準化しておく

テストは「対象と1対1で対応させる」と分かりやすい

テストのフォルダ構成も、ルールを決めておくと迷いません。

tests/
  domain/
    test_models.py
    test_services.py
  infra/
    test_db.py
  presentation/
    test_cli.py

もしくは、「モジュール名に対応させる」パターンもよく使われます。

src/
  myapp/
    domain.py
    services.py
tests/
  test_domain.py
  test_services.py

どちらでもいいですが、
「どのテストがどのコードを対象にしているか」が一目で分かる構成にするのがポイントです。

テストフォルダを標準化しておくと、

新しい機能を追加するときに「テストファイルをどこに置くか」で迷わない
CI（自動テスト）が tests/ を前提に動かしやすい

という実務的なメリットも大きいです。

設定ファイル・メタ情報の置き場所も決めておく

ルート直下に「プロジェクトの顔」を集める

Pythonプロジェクトでは、だいたいこんなファイルがルートに並びます。

pyproject.toml（ビルド・依存関係・ツール設定）
README.md（説明）
.gitignore
ruff.toml / .flake8 / mypy.ini などのツール設定

フォルダ構成標準化では、

「設定ファイルは基本ルートに置く」
「ツールごとの設定ファイル名を揃える」

というルールを決めておくと、
新しいプロジェクトを作るときに「テンプレート化」しやすくなります。

例えば、テスト・型チェック・Lint を全部 pyproject.toml に寄せる、という方針もよくあります。

フォルダ構成標準化が品質に効いてくる理由

「どこに何を書くか」で迷わない＝設計のブレが減る

フォルダ構成がバラバラだと、

この機能はどこに置くべきか
このクラスはどのモジュールに入れるべきか

毎回判断が必要になります。

標準構成があると、

ドメインロジックなら domain/
外部接続なら infra/
入口なら presentation/

と、迷わず置き場所を決められます。

これは、設計のブレを減らし、
結果として「似たようなコードがあちこちに散らばる」ことを防ぎます。

ツールとの連携がしやすくなる

例えば、

テストは tests/ を見る
ソースコードは src/ を見る
型チェックは src/ と tests/ を対象にする

という前提でツールを設定しておけば、
どのプロジェクトでも同じ設定をほぼ流用できます。

CI（GitHub Actions など）も、
「この構成ならこのジョブを回す」というテンプレートを作りやすくなります。

構成が標準化されていると、
「プロジェクトごとに毎回設定を考え直す」コストが減り、
その分、設計やテストに頭を使えるようになります。

初心者がフォルダ構成標準化を練習するときのステップ

まずは「自分なりのテンプレート」を一つ作る

例えば、こんな最小構成をテンプレートにしてしまうのがおすすめです。

myapp/
  pyproject.toml
  README.md
  src/
    myapp/
      __init__.py
      domain.py
      services.py
  tests/
    test_domain.py
    test_services.py

新しいプロジェクトを作るときは、
これをコピーして名前だけ変える。

そこから、

ドメインが増えたら domain/ フォルダを切る
インフラが増えたら infra/ を作る

というふうに、少しずつ育てていけばOKです。

「このファイルは何担当？」と自問して、場所を決める

ファイルを作るときに、必ず自分にこう聞いてください。

これはドメインロジックか？
これは外部接続か？
これは入口（CLI / REST）か？

その答えに応じて、
domain/ infra/ presentation/ のどこに置くかを決める。

この習慣がつくと、
フォルダ構成標準化と責務定義がセットで身についていきます。

まとめ（フォルダ構成標準化は「迷子にならないための共通ルールづくり」）

初心者目線でまとめると、フォルダ構成標準化はこういうものです。

src/ に本体コード、tests/ にテスト、ルートに設定・メタ情報を置く、といった「型」を決めておくことで、どのプロジェクトでも「どこに何があるか」がすぐ分かるようにする。
domain/ infra/ presentation/ など、フォルダと責務を対応させることで、設計のブレが減り、テストやツール連携もしやすくなり、結果として品質が安定する。
最初はシンプルなテンプレートを一つ決めて、「新しいプロジェクトは全部それから始める」「ファイルを作るときに“何担当か”を考えて置き場所を決める」という小さな習慣から始めると、自然と“迷子にならないプロジェクト”が作れるようになっていく。

スポンサーリンク
タイトルとURLをコピーしました