どのスターターを選ぶべき?
FastAPI-fastkit には、プロジェクトを始めるための方法がいくつか用意されています。このページは初めての方のための 選び方ガイド です。ここで方向性を決めたうえで、実際のプロジェクト生成は クイックスタート に進んでください。
迷っている場合の答えは次のとおりです:
fastkit init --interactiveで始め、domain-starterプリセットを選んでください。 これは現代的な API プロジェクトに対する推奨デフォルトです。
このページの残りの部分では、その理由と、別の選択を取るべき場面を説明します。
TL;DR — ユーザータイプ別の選び方
| あなたが... | 出発点 |
|---|---|
| FastAPI が初めてで、ガイド付きで進めたい | fastkit init --interactive (preset: domain-starter) |
| 動作する CRUD デモを読み・書き換えながら学びたい | fastkit startdemo fastapi-default |
| 可能な限り小さいスキャフォールドが欲しい | fastkit init --interactive (preset: minimal) |
| 簡単なプロトタイプ / 単一ファイルのスクリプトを書く | fastkit init --interactive (preset: single-module) |
| 実際のデータベースが必要 (PostgreSQL + SQLAlchemy + Alembic) | fastkit startdemo fastapi-psql-orm |
| マイグレーションと汎用 CRUD を備えた非同期の永続化が欲しい | fastkit startdemo fastapi-sqlmodel |
| 初日からユーザーアカウント、ログイン、保護されたルートが必要 | fastkit startdemo fastapi-auth-jwt |
| ストリーミングとツールを備えた LLM チャットバックエンドを作る | fastkit startdemo fastapi-llm-agent |
| 中規模 API のための本番志向のドメインレイアウトが欲しい | fastkit init --interactive (preset: domain-starter) |
startdemo と init --interactive の違いは?
これらが 2 つの主なエントリポイントで、それぞれ異なる用途を持ちます。
fastkit startdemo <template>
同梱テンプレート (fastapi-default、fastapi-async-crud、fastapi-psql-orm、fastapi-domain-starter、...) のいずれかをもとに、完成済みで動作する例題プロジェクト をディスクに展開します。テンプレートのソースコードはほぼそのままコピーされ、メタデータのプレースホルダ (<project_name> など) のみが埋め込まれます。
- ✅ 動作するデモまでの最短ルート。
- ✅ コードはすべて実際に動き、読みやすい — 例題による学習に最適。
- ❌ テンプレートのスタックと構造は固定されており、生成時に「CORS だけ入れて認証は外す」といった組み合わせはできません。
$ fastkit list-templates # 利用可能なテンプレート一覧を表示
$ fastkit startdemo fastapi-default # その中の 1 つでプロジェクトを生成
fastkit init --interactive
対話型ウィザード に沿って進めます: プロジェクトメタデータ → アーキテクチャプリセット → 機能選択 (データベース、認証、テスト、デプロイ、...) → パッケージマネージャー → 確認、という流れです。ジェネレーターはプリセットごとに適切なベーステンプレートを選び、その上に選択した機能を重ねていきます。
- ✅ 自分が本当に欲しいスタックを組み立てられる。
- ✅ アーキテクチャプリセットがプロジェクトレイアウト (単一ファイル、レイヤー型、ドメイン指向、...) を決定。
- ❌
main.pyをそのまま使う構成の充実したプリセット (classic-layered、domain-starter) では、設定モジュールは生成されますが、それを同梱のルーターに組み込む配線はユーザー自身が行う前提です。プリセット / 機能ごとの仕様は アーキテクチャプリセットマトリクス を参照してください。
4 種類のアーキテクチャプリセット
これらは fastkit init --interactive のプロジェクト情報入力後に表示されます。どのプリセットを選ぶか決める際にこのセクションを使ってください。
minimal — 最小から始め、後で育てる
最小構成の動作可能な FastAPI アプリ。空のスキャフォールド + 機能フラグから再生成された単一の src/main.py です。CORS、レート制限、Prometheus 計装は、選択時に自動で main.py に配線されます。
- 👤 対象: プロジェクトが成長するにつれて自分で構造を組み立てたい人や、特定のレイアウトに縛られず FastAPI を試したい人。
- 📦 ベーステンプレート:
fastapi-empty。 - 🧠 メンタルモデル: 「FastAPI を import した 1 ファイルだけ用意してくれれば、残りは自分でやる」。
single-module — スクリプト型プロトタイプ
すべてのコードが 1 モジュールの中にあります。minimal と同じ main.py 再生成オーバーレイを使います。
- 👤 対象: グルースクリプト、小さな webhook、あるいはパッケージ境界が不要な 1 日でできるプロトタイプ。
- 📦 ベーステンプレート:
fastapi-single-module。 - 🧠 メンタルモデル: 「実行も通読もひと息でできる Python ファイル 1 つあれば十分」。
classic-layered — レイヤー型分割 (api / crud / schemas / core)
「Django 風」レイアウト — コードを関心事ごとに水平分割します: ルーターはすべて api/ に、CRUD ロジックはすべて crud/ に、pydantic スキーマはすべて schemas/ に、設定はすべて core/ にまとめます。同梱の main.py は 保存 されており (CORS の配線済み)、生成されたデータベース / 認証設定は src/core/ 配下に配置されます。
- 👤 対象: Django / Rails 風レイアウトに慣れたチーム、共通の CRUD 配管を共有する小さなエンドポイントが多いプロジェクト。
- 📦 ベーステンプレート:
fastapi-default。 - 🧠 メンタルモデル: 「コードを 何であるか で分ける」。
domain-starter — ドメイン指向 (推奨デフォルト)
コードを ビジネス概念ごと に垂直分割します: 各ドメインが自身のルーター、サービス、リポジトリ、スキーマを src/app/domains/<concept>/ 配下に持ちます。/health エンドポイントと、新しい概念ごとにコピーしてリネームする雛形となる items ドメインの例が同梱されています。同梱の main.py (src/app/ 配下) は保存され、生成された設定は src/app/core/ 配下に配置されます。
- 👤 対象: 複数の異なるビジネス概念 (users、orders、billing、...) に成長していく中規模 API。推奨される現代的なデフォルトです。
- 📦 ベーステンプレート:
fastapi-domain-starter。 - 🧠 メンタルモデル: 「コードを ビジネスにとって何をするか で分ける」。
比較マトリクス
横並びで一目で比べられるようにしたものです。
minimal |
single-module |
classic-layered |
domain-starter |
|
|---|---|---|---|---|
| ベーステンプレート | fastapi-empty |
fastapi-single-module |
fastapi-default |
fastapi-domain-starter |
| プロジェクト入口 | src/main.py |
src/main.py |
src/main.py |
src/app/main.py |
| ルーター配置 | (自分で追加) | (main.py の中) |
src/api/routes/ |
src/app/domains/<concept>/router.py |
| ドメイン別フォルダ | ❌ | ❌ | ❌ | ✅ |
/health エンドポイント標準搭載 |
✅ | ✅ | ❌ | ✅ |
main.py を機能から再生成 |
✅ | ✅ | ❌ | ❌ |
main.py に CORS 事前配線 |
選択時に追加 | 選択時に追加 | あり (環境変数駆動) | あり (環境変数駆動) |
| pyproject ファースト | 任意 | 任意 | 任意 | ✅ |
| 適した用途 | 「自分で構造を育てたい」 | 「1 ファイルのプロトタイプ」 | 「関心事で分ける」 | 「ビジネス概念で分ける」 |
機能ごとの完全な契約 (データベース / 認証の設定が配置されるパス、自動配線されない選択、警告が出る条件) は アーキテクチャプリセットマトリクス を参照してください。
startdemo テンプレートの選び方
fastkit startdemo <template> は、ガイド付きで組み立てるよりも 完成済みで実行可能な例題 が欲しいときに最適です。ほとんどのテンプレートは前述の 4 つのプリセットのいずれかにおおむね対応していますが、追加のサンプルコード (モックストア上の CRUD エンドポイント、カスタムレスポンス処理、Docker ツールなど) を同梱しています。
| テンプレート | 最も近いプリセット | 選ぶ場面 |
|---|---|---|
fastapi-default |
classic-layered |
レイヤー型レイアウトで動く CRUD デモ。最初の出発点として手堅い。 |
fastapi-empty |
minimal |
素のスキャフォールド。minimal と同じ形になります。 |
fastapi-single-module |
single-module |
単一ファイルのデモ。 |
fastapi-domain-starter |
domain-starter |
推奨される現代的デフォルト。items ドメインの例を同梱。 |
fastapi-auth-jwt |
domain-starter |
API にアカウントが必要な場合。アクセス/リフレッシュトークン、argon2id ハッシュ化、ロールとスコープ、Alembic マイグレーション。 |
fastapi-sqlmodel |
domain-starter |
非同期の永続化を第一に: SQLModel + 非同期 SQLAlchemy、マイグレーション、汎用 CRUD ベース、ページネーションされたリスト。 |
fastapi-llm-agent |
domain-starter |
本物のツール呼び出しループとオフラインのテストを備えた、ストリーミング Claude チャットバックエンド。 |
fastapi-custom-response |
classic-layered |
カスタムレスポンスエンベロープ / フォーマットのデモ。 |
fastapi-psql-orm |
(直接対応するプリセットなし) | PostgreSQL + SQLAlchemy + Alembic、同期型。実際のデータベースを中心にした Compose スタックが欲しいときに選択。 |
fastapi-mcp |
(直接対応するプリセットなし) | Model Context Protocol 連携。 |
fastapi-async-crud |
classic-layered |
⚠️ 非推奨。 fastapi-default の非同期版。fastapi-sqlmodel を推奨。 |
fastapi-dockerized |
classic-layered |
⚠️ 非推奨。 デフォルトレイアウトに Dockerfile を追加。現在のテンプレートにはすべて Dockerfile が含まれています。 |
3 つの新しいスターター
v1.4.0 で追加された 3 つのスターターはいずれも domain-starter の形 (概念ごとのフォルダを持つ src/app/)
に従っているため、そのプリセットですでに知っている内容とそのまま組み合わせられます。
fastapi-auth-jwt — 本番環境に出しても通用する認証。
アクセストークンは短命です。リフレッシュトークンは使うたびにローテーションされ、データベース上で jti によって
追跡されるため、再送されたトークンは黙って受け入れられるのではなく拒否されます。パスワードは pwdlib を介して
argon2id でハッシュ化されます。ログアウトも実際に機能し、1 つのセッション、またはユーザーのすべてのセッションを
失効させられます。ガードは依存性として付属します — get_current_user、get_current_active_superuser、そして
require_scopes(...) ファクトリです。外部サービスなしで SQLite 上で動作し、DATABASE_URL を設定すれば
PostgreSQL に移行できます。ウォークスルー: JWT 認証。
fastapi-sqlmodel — 概念ごとに 1 つのモデル定義。
SQLModel のクラスは SQLAlchemy のテーブルであると同時に pydantic のスキーマでもあるため、新しいカラムは一度
宣言するだけで、すべてのリクエスト/レスポンススキーマがそれを継承します。端から端まで非同期で、非同期 Alembic
マイグレーション、create / read / list / count / update / delete を提供して各ドメインが固有の部分だけを書けば
済むようにする CRUDBase、そしてページ用のエンベロープで包まれたリスト系エンドポイントを備えています。
ウォークスルー: SQLModel による永続化。
fastapi-llm-agent — POST /completion のラッパーではなく、チャットバックエンド。
トークンは SSE でクライアントにストリーミングされ、ツール呼び出しループはモデルの処理が終わるか反復上限に
達するまで実行されます。会話履歴は ConversationStore インターフェースの背後にあるため、同梱の dict から
Redis への移行は実装を 1 つ用意するだけで済みます。テストスイートは Anthropic クライアントをスクリプト化された
偽物に置き換えます — 決定的で、オフラインで動作し、API キーも不要です。
ウォークスルー: LLM エージェント。
非推奨テンプレートについて
fastapi-async-crud と fastapi-dockerized は引き続き同梱されており、動作するプロジェクトを生成します —
使っても何も壊れません。非推奨とされているのは、それらを選ぶ理由がなくなったからです:
fastapi-dockerizedは Dockerfile を追加するために存在していました。現在のテンプレートにはすべて Dockerfile が含まれており、対話型のデプロイ選択はどのプリセットに対しても Docker ファイルを生成します。fastapi-async-crudはモックストアに対する非同期エンドポイントのデモでした。fastapi-sqlmodelは同じことを 本物の非同期データベースに対して、マイグレーション付きで行います。
どちらかのテンプレートから生成された既存のプロジェクトについて、対応は必要ありません。
fastkit list-templates で 1 行説明付きの最新リストを確認できます。
よくある質問
Q. プリセット / テンプレートは最初に決めないといけない? いいえ — 後から手動で生成済みコードを再構成することはいつでもできます。プリセットはあくまで出発点であり契約ではありません。選択を考え過ぎないでください。
Q. 「現代的」な選択肢はどれ?
domain-starter です。pyproject ファーストで、/health エンドポイントが付属し、よく運営されている中規模 FastAPI プロジェクトが収束していくレイアウトを採用しています。
Q. 後から classic-layered から domain-starter に切り替えできる?
できますが手動のリファクタリングです — マイグレーションコマンドはありません。プロジェクトがドメインフォルダを必要とするほど成長すると思うなら、最初からそこを選んでください。
Q. とにかく FastAPI を学びたいだけ。
まず fastkit startdemo fastapi-default から始めてください — コードを読み、テストを実行し、いくつかのエンドポイントを書き換えてみましょう。慣れてきたら、fastkit init --interactive で domain-starter プリセットを選ぶのが自然な次の一歩です。
Q. 各プリセットが生成する正確なファイル一覧はどこで見られる? アーキテクチャプリセットマトリクス がそのリファレンスページです。
次のステップ
- クイックスタート — 実際に最初のプロジェクトを作成。
- プロジェクトの作成 — CLI フラグのより踏み込んだウォークスルー。
- JWT 認証チュートリアル、SQLModel による永続化チュートリアル、 LLM エージェントチュートリアル — v1.4.0 で追加された 3 つのスターターの エンドツーエンドのウォークスルー。
- ドメイン指向プロジェクトのチュートリアル —
domain-starterを選んだ場合の、生成ツリー、同梱のitems例、次のドメインの追加方法までを通したエンドツーエンドの解説。 - アーキテクチャプリセットマトリクス — プリセット / 機能ごとの完全な契約。