よくある質問
FastAPI-fastkit に関するよくある質問とその回答です。
インストールとセットアップ
Q: 対応している Python バージョンは?
A: FastAPI-fastkit は Python 3.12 以上 が必要です。最良の体験のため、最新の安定 Python バージョンの利用を推奨します。
Q: FastAPI-fastkit はどうインストールしますか?
A: pip でインストールできます:
Q: パーミッションエラーでインストールに失敗します
A: 仮想環境内、またはユーザー権限でインストールしてください:
Q: インストール後に fastkit コマンドが見つかりません
A: たいていは、インストール先が PATH に含まれていないことが原因です:
プロジェクトの作成
Q: 利用できる依存関係スタックは?
A: FastAPI-fastkit は 3 つの依存関係スタックを提供します:
- MINIMAL: FastAPI、Uvicorn、Pydantic、Pydantic-Settings (基本的な Web API)
- STANDARD: SQLAlchemy、Alembic、pytest を追加 (データベース対応)
- FULL: Redis、Celery を追加 (バックグラウンドタスク)
デフォルトのパッケージマネージャー
デフォルトのパッケージマネージャーは依存関係インストールが速い uv です。pip、pdm、poetry も選択できます。
Q: プロジェクトテンプレートはカスタマイズできますか?
A: はい、次のいずれかの方法で:
- 既存テンプレートを使う —
fastkit startdemo - カスタムテンプレートを作る — 既存をコピーして変更
- 段階的にルートを追加 —
fastkit addroute
Q: プロジェクト名にはどんな形式が使えますか?
A: プロジェクト名は妥当な Python 識別子である必要があります:
- ✅
my-api、blog_system、UserService - ❌
my api、123project、project-name!
Q: 「ディレクトリは既に存在する」というエラーで作成に失敗します
A: プロジェクトディレクトリが既に存在しています。次のいずれかで対処してください:
- 別の名前を選ぶ
- 既存ディレクトリを削除 (安全な場合のみ)
- 別の場所に作成
Q: 対話型モードでプロジェクトをセットアップするには?
A: fastkit init --interactive を使うと、賢い機能選択を伴うガイド付きの段階的なセットアップが可能です:
対話型モードは次の順序で進みます:
- プロジェクト情報 — 名前、作者、メール、説明。
- アーキテクチャプリセット — プロジェクトレイアウトを選択。推奨デフォルトは
domain-starter。Enter で受け入れられます。各プリセットが生成する正確なレイアウトと、手動配線が必要な機能組み合わせは プリセット / 機能マトリクス を参照してください。 - 機能選択 — データベース、認証、バックグラウンドタスク、キャッシュ、モニタリング、テスト、ユーティリティ、デプロイ。
- パッケージマネージャーとカスタムパッケージ — pip / uv / pdm / poetry、および固定したい追加パッケージ。
- 確認 — プロジェクト作成前に、すべての選択 (アーキテクチャプリセット含む) を表で表示します。
対話型モードでは、次の包括的な機能カタログから選べます:
| カテゴリ | 利用可能な選択肢 |
|---|---|
| アーキテクチャ | minimal、single-module、classic-layered、domain-starter (推奨デフォルト) |
| データベース | PostgreSQL、MySQL、MongoDB、Redis、SQLite |
| 認証 | JWT、OAuth2、FastAPI-Users、セッションベース |
| バックグラウンドタスク | Celery、Dramatiq |
| テスト | Basic (pytest)、Coverage、Advanced (faker、factory-boy 付き) |
| キャッシュ | Redis with fastapi-cache2 |
| モニタリング | Loguru、OpenTelemetry、Prometheus |
| ユーティリティ | CORS、レート制限、ページネーション、WebSocket |
| デプロイ | Docker、docker-compose (自動生成設定付き) |
対話型モードは次を自動生成します:
- 選択した機能を統合した
main.py - データベースおよび認証の設定ファイル (コード生成に対応する選択肢の場合 — 例: データベースの PostgreSQL/MySQL/SQLite/MongoDB、認証の JWT/FastAPI-Users。それ以外の選択肢は必要パッケージのインストールのみ)
- 選択したデプロイオプションに対応するデプロイファイル (
Docker選択時はDockerfile、docker-compose選択時はdocker-compose.yml) - 選択したテストオプションに応じたテスト設定 (カバレッジ設定は
CoverageまたはAdvancedを選んだ場合のみ含まれます)
Q: 対話型モードで利用できる機能を確認するには?
A: list-features コマンドで、利用可能なすべての機能とパッケージを表示できます:
これで、各機能を選んだ場合にどのパッケージがインストールされるかを把握できます。
ルート開発
Q: ルートに認証を追加するには?
A: 認証用の依存性を作成します:
# src/api/deps.py
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer
security = HTTPBearer()
def get_current_user(token: str = Depends(security)):
# トークンを検証してユーザーを返す
if not verify_token(token):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid authentication credentials"
)
return get_user_from_token(token)
# src/api/routes/users.py
@router.get("/me")
def get_current_user_profile(user = Depends(get_current_user)):
return user
Q: プロジェクトにデータベースモデルを追加するには?
A: STANDARD または FULL スタックで、SQLAlchemy モデルを作成します:
# src/models/users.py
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True, index=True)
email = Column(String, unique=True, index=True)
username = Column(String, unique=True, index=True)
hashed_password = Column(String)
is_active = Column(Boolean, default=True)
Q: リクエストデータの検証を追加するには?
A: スキーマで Pydantic モデルを使います:
# src/schemas/users.py
from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
email: EmailStr
username: str = Field(..., min_length=3, max_length=50)
password: str = Field(..., min_length=8)
@validator('username')
def validate_username(cls, v):
if not v.isalnum():
raise ValueError('Username must be alphanumeric')
return v
Q: ファイルアップロードはどう扱いますか?
A: FastAPI の UploadFile を使います:
from fastapi import UploadFile, File
@router.post("/upload")
async def upload_file(file: UploadFile = File(...)):
contents = await file.read()
# ファイルを保存
with open(f"uploads/{file.filename}", "wb") as f:
f.write(contents)
return {"filename": file.filename, "size": len(contents)}
テンプレート
Q: 利用できるテンプレートは?
A: FastAPI-fastkit には、あらかじめ用意されたテンプレートが複数含まれています:
$ fastkit list-templates
Available Templates
┌─────────────────────────┬───────────────────────────────────┐
│ fastapi-default │ Simple FastAPI Project │
│ fastapi-async-crud │ Async Item Management API Server │
│ fastapi-custom-response │ Custom Response System │
│ fastapi-dockerized │ Dockerized FastAPI API │
│ fastapi-empty │ Minimal FastAPI Project │
│ fastapi-mcp │ MCP (Model Context Protocol) API │
│ fastapi-psql-orm │ PostgreSQL FastAPI API │
│ fastapi-single-module │ Single-file FastAPI Project │
└─────────────────────────┴───────────────────────────────────┘
Q: 特定のテンプレートを使うには?
A: startdemo コマンドを使います:
Q: 自分でテンプレートを作れますか?
A: 作れます。ディレクトリ構造を用意し、テンプレート変数を使います:
# main.py-tpl
from fastapi import FastAPI
app = FastAPI(title="{{PROJECT_NAME}}")
@app.get("/")
def read_root():
return {"message": "Hello from {{PROJECT_NAME}}!"}
Q: 既存のテンプレートを変更するには?
A: テンプレートは fastapi_project_template ディレクトリにあります:
- リポジトリをフォーク してテンプレートを変更
- 既存をベースに カスタムテンプレートを作成
- プロジェクト作成後に 特定のファイルを上書き
開発サーバー
Q: 開発サーバーを起動するには?
A: プロジェクトディレクトリで runserver コマンドを使います:
Q: サーバーが起動しない — "Address already in use"
A: ポート 8000 がビジー状態です。別のポートを使うか、既存プロセスを終了してください:
Q: 自動リロードが動きません
A: プロジェクトディレクトリにいて、仮想環境が有効化されているか確認してください:
Q: 本番運用向けにサーバーをどう設定すれば?
A: 本番では開発サーバーを使わないでください。次のようにします:
# gunicorn などの WSGI サーバーを使う
$ pip install gunicorn
$ gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker
# あるいは fastapi-dockerized テンプレートで Docker
$ fastkit startdemo # fastapi-dockerized を選択
$ docker build -t my-app .
$ docker run -p 8000:8000 my-app
パフォーマンスと最適化
Q: API のパフォーマンスを向上させるには?
A: いくつかの最適化戦略があります:
- I/O 操作には async/await を使用
- 重い処理には キャッシュを追加
- データベースクエリを最適化
- 重い処理には バックグラウンドタスクを使用
# 非同期エンドポイント
@router.get("/users/{user_id}")
async def get_user(user_id: int):
user = await users_service.get_user_async(user_id)
return user
# バックグラウンドタスク
from fastapi import BackgroundTasks
@router.post("/send-email")
def send_email(background_tasks: BackgroundTasks, email: str):
background_tasks.add_task(send_notification_email, email)
return {"message": "Email will be sent in background"}
Q: キャッシュを追加するには?
A: Redis でキャッシュします:
import redis
from functools import wraps
redis_client = redis.Redis(host='localhost', port=6379, db=0)
def cache_result(expiration: int = 300):
def decorator(func):
@wraps(func)
async def wrapper(*args, **kwargs):
cache_key = f"{func.__name__}:{hash(str(args) + str(kwargs))}"
# キャッシュから取得を試みる
cached = redis_client.get(cache_key)
if cached:
return json.loads(cached)
# 関数を実行して結果をキャッシュ
result = await func(*args, **kwargs)
redis_client.setex(cache_key, expiration, json.dumps(result))
return result
return wrapper
return decorator
@cache_result(expiration=600)
async def get_expensive_data():
# 重い処理
return complex_calculation()
Q: 大量の同時リクエストはどう扱えば?
A: 適切なサーバー設定を使います:
テスト
Q: テストを実行するには?
A: プロジェクトディレクトリで pytest を使います:
Q: API テストはどう書けば?
A: FastAPI のテストクライアントを使います:
from fastapi.testclient import TestClient
from src.main import app
client = TestClient(app)
def test_create_user():
response = client.post(
"/api/v1/users/",
json={"email": "test@example.com", "username": "testuser"}
)
assert response.status_code == 201
assert response.json()["email"] == "test@example.com"
def test_get_user():
response = client.get("/api/v1/users/1")
assert response.status_code == 200
Q: 外部依存をモックするには?
A: pytest フィクスチャとモックを使います:
import pytest
from unittest.mock import Mock, patch
@pytest.fixture
def mock_database():
with patch('src.database.get_db') as mock_db:
mock_db.return_value = Mock()
yield mock_db
def test_user_creation_with_mock_db(mock_database):
# モックされた DB でテスト
response = client.post("/api/v1/users/", json=user_data)
assert response.status_code == 201
コントリビュート
Q: FastAPI-fastkit にどう貢献すれば?
A: 次の手順で進めてください:
- GitHub で リポジトリをフォーク
- 開発環境をセットアップ
- 機能ブランチを作成
- テスト付きで 変更を実装
- プルリクエストを送信
Q: プルリクエストには何を含めるべき?
A: すべての PR に次を含めてください:
- [ ] 明確な変更内容の説明
- [ ] 新機能には テスト
- [ ] 必要に応じて ドキュメント更新
- [ ] コードガイドラインの遵守
- [ ] すべてのチェックを通過
Q: バグはどう報告すれば?
A: GitHub Issue を作成し、次を含めてください:
- バグの説明 と期待される挙動
- 再現手順
- 環境情報 (OS、Python バージョンなど)
- エラーメッセージ やログ
- 可能なら 最小再現例
Q: 新機能はどうリクエストすれば?
A: 機能リクエスト Issue を開き、次を含めてください:
- 機能の 明確な説明
- ユースケース と動機
- 実装案 (任意)
- 類似機能の 例
トラブルシューティング
Q: import エラーが出ます
A: Python パスと仮想環境を確認してください:
Q: データベース接続の問題
A: データベーステンプレートでは、データベースが起動しているか確認してください:
Q: テンプレートファイルが見つからない
A: テンプレートパスの問題が原因のことが多いです:
Q: pre-commit フックが失敗します
A: フックをインストールして実行します:
Q: CI ではテストが落ちるのにローカルでは通る
A: よくある原因と対処:
- 環境差: Python バージョンが一致しているか確認
- 依存関係不足: テスト要件が入っているか確認
- パスの問題: 絶対 import を使う
- タイミング問題: 非同期テストに適切な待機を入れる
ヘルプ
Q: どこでヘルプを得られますか?
A: いくつか方法があります:
- GitHub Issues: バグや機能リクエスト
- GitHub Discussions: 質問やコミュニティサポート
- ドキュメント: ユーザーガイドとチュートリアル
- コード例: 既存テンプレートとテスト
Q: 最新情報を追うには?
A: プロジェクトの更新を追ってください:
- GitHub で リポジトリを Watch
- 新機能は リリース で確認
- 破壊的変更は changelog を読む
- ドキュメントの ベストプラクティス に従う
プロのコツ
- Python プロジェクトでは常に仮想環境を使う
- FastAPI-fastkit を最新に保つ
- 利用可能なコマンドは
fastkit --helpで確認 - 困ったらドキュメントを見る
- 質問は GitHub Discussions で気軽にどうぞ