このリポジトリは、Pythonを使用したAPIサーバー開発の効率化を目的としたテンプレートリポジトリです。以下の特徴を持っています：
- FastAPIによる高速なAPIサーバー実装
- OpenAPI Generatorによるコード生成
- DevContainerによる開発環境のDockerコンテナ化
- 依存パッケージの厳密なバージョン管理
- Python標準ライブラリの
unittestですぐにテストを始められる環境 flake8、black、isortによるコード品質の自動チェックと整形- CSpellによるスペルチェック
- GitHub Actionsによる継続的インテグレーション（CI）の整備
- Cloud Runへのデプロイ対応
このテンプレートを使用することで、各案件に向けたAPIサーバー開発を迅速に開始し、一貫した開発スタイルを維持することができます。
Note
Cursor使用時の追加支援機能
Cursorを使用している場合、.cursor/rulesに定義されたプロジェクト固有のルールによって、開発プロセスに関する質問や作業において適切なガイダンスを受けることができます。これにより、プロジェクト固有の開発フローや品質基準に沿った作業を効率的に進めることができます。
- VSCode または Cursor の拡張機能Dev Containersをインストールします。
- コマンドパレットを開き、
Dev Containers: Reopen in Containerを選択します。
# exampleを実行する場合
python -m src.example.entrypoint
# another_exampleを実行する場合
python -m src.another_example.entrypoint
# save_resultを実行する場合
python -m src.save_result.entrypointhttp://localhost:8080 に対してリクエストを送ることができるようになります。
python -m unittestJSONリクエスト
curl -X POST -H "Content-Type: application/json" localhost:8080/ -d '{"api_name": "Solver", "name": "Taro"}'JSON Linesリクエスト
DATA='
{"api_name": "Solver", "name": "Taro"}
{"api_name": "Solver", "name": "Jiro"}
{"api_name": "Solver", "name": "Siro"}
'
curl -X POST -H "Content-Type: application/jsonl" localhost:8080/ -d "$DATA"OpenAPI仕様でAPIを定義し、OpenAPI Generatorを使用してPythonコードを自動生成します。schema.yamlにOpenAPIの定義を記述し、以下のコマンドでPythonのデータモデルに変換します：
./scripts/convert_open_api_to_dataclass.sh生成されたコードは src/models/ に配置されます。自動生成されたコードは直接編集せず、schema.yamlを更新して再生成してください。
- 必ず手動で更新すること
- 直接依存しているパッケージのみを書くこと
- PyPIで利用可能なパッケージのみを書くこと
例) flake8 の バージョンを 1.2.X にしたい場合: flake8~=1.2.3
参考： https://www.python.org/dev/peps/pep-0440/#version-specifiers
以下のコマンドによる更新は禁止します。
pip freeze > requirements.in
pip freeze >> requirements.in以下のコマンドを実行します。
./scripts/generate_lockfile.shこのプロジェクトでは、Dependabot が月次で依存パッケージの更新を自動的に行います。Dependabot が作成したPRのマージとリリースについては、一貫性のあるガイドラインに従って実施してください。
詳細は CONTRIBUTING.md の「Dependabot による自動更新」セクションを参照してください。
-
コンテナが起動しない
- Dockerが正しくインストールされているか確認します。
- VSCodeまたはCursorのDev Containers拡張機能が最新版か確認します。
-
依存パッケージのインストールに失敗
requirements.inのバージョン指定が正しいか確認します。- インターネット接続を確認します。
-
APIの自動生成が失敗
schema.yamlの構文が正しいか確認します。- Dockerコンテナ内で実行しているか確認します。
-
起動時にPythonに関するエラーが毎回出る（Cursor使用時）
- Cursor起動時に「In order to use Anysphere Python,
ms-python.vscode-pylancemust be uninstalled.」というエラーが毎回表示される場合があります。 - これは
ms-python.vscode-pylanceとanysphere.cursorpyrightの拡張機能が両方インストールされていることが原因です。 - 解決方法：拡張機能
anysphere.cursorpyrightをアンインストールしてください。（anysphere.cursorpyrightは推奨する拡張機能には含まれていません）
- Cursor起動時に「In order to use Anysphere Python,
このプロジェクトでは、標準的なPythonのloggingモジュールを拡張した独自のロギング機能を提供しています。src.loggerモジュールを使用することで、統一されたフォーマットでログを出力できます。
from src.logger import logger
# 基本的なログ出力
logger.debug("デバッグ情報")
logger.info("通常の情報")
logger.warning("警告メッセージ")
logger.error("エラーメッセージ")
logger.critical("致命的なエラー")
# 追加情報を含むログ
logger.info("ユーザー情報", extra={"user_id": 123, "username": "test_user"})
# 例外情報を含むログ
try:
1 / 0
except ZeroDivisionError:
logger.error("計算エラーが発生しました", exc_info=True)開発環境では視認性を高めるため、色付きログメッセージを使用できます。以下のユーティリティ関数を使用して、ログメッセージに色や強調を追加できます。
from src.logger import logger, red, green, yellow, blue, bold, success, warning, error, highlight
# 色付きメッセージの例
logger.info("ステータス: %s", success("成功"))
logger.warning("注意: %s", warning("ディスク容量が少なくなっています"))
logger.error("エラー: %s", error("データベース接続に失敗しました"))
# 強調表示の例
logger.info("ユーザー %s が管理画面にログインしました", highlight("admin"))
logger.info("重要な設定: %s", bold("DEBUG_MODE=True"))
# 複合的な使用例
logger.info("実行時間: %s (前回: %s)", bold(green("152ms")), yellow("165ms"))Note
本番環境（ENV=production）では、色付けは自動的に無効になり、代わりにGoogle Cloud互換のJSON形式でログが出力されます。これにより、ログ解析システムとの互換性が確保されます。
環境変数 ENV によってログの出力形式が変わります：
-
開発環境（デフォルト）: カラー付きの人間が読みやすい形式
[2025-05-26T07:04:17] INFO [logger.py:304] app_started -
本番環境（
ENV=production）: Google Cloud互換のJSON形式{"timestamp": "2025-05-26T07:03:43.566Z", "severity": "INFO", "message": "app_started", "logging.googleapis.com/sourceLocation": {"file": "logger.py", "line": 304, "function": "<module>"}, "env": "production"}
FastAPIアプリケーションでHTTPリクエストを自動的にログに記録するには、LoggingMiddlewareを使用します：
from fastapi import FastAPI
from src.logger import LoggingMiddleware
app = FastAPI()
app.add_middleware(LoggingMiddleware)これにより、各HTTPリクエストの情報（メソッド、パス、レスポンスコードなど）が自動的にログに記録されます。ヘルスチェックリクエスト（/healthエンドポイント）はログから除外されます。
ログメッセージの作成には、生成AIを活用することも推奨されます。特に以下のような場合にAIの支援が有効です：
- 一貫性のあるログメッセージフォーマットの作成
- 適切なログレベル（INFO/WARNING/ERROR）の選択
- 色付きログの効果的な使用例の生成
- エラーメッセージの明確で詳細な記述
生成AIを使用する際は、以下のポイントに注意してください：
- 機密情報や個人情報をAIに送信しないこと
- 生成されたコードを必ず確認し、プロジェクトの規約に合致していることを確認すること
- 自動生成されたログメッセージの文言が適切かどうかをレビューすること
例えば、以下のようなプロンプトでAIにログメッセージの作成を依頼できます：
「src.logger モジュールを使って、ユーザー認証に失敗した場合のエラーログを作成してください。logger.error と error() 関数を使用し、ユーザーID、IPアドレス、失敗理由を含めること。extra パラメータを使用して構造化ログも実装し、適切な色付けも提案してください。」
これにより開発者は、効率的かつ一貫性のあるログ実装が可能になります。
このプロジェクトでは、CSpellを使用してコード内のスペルミスをチェックしています。これにより、コードベース全体で一貫した命名規則を保ちやすくなります。
全ファイルのスペルチェックを実行するには、以下のコマンドを使用します：
npx cspell --config cspell.json "**" --dotこのコマンドは、プロジェクト内のすべてのファイル（ドット始まりのファイルも含む）に対してスペルチェックを実行します。
プロジェクト固有の用語や技術用語は、.cspell/project-words.txtに追加することができます。このファイルに追加された単語は、スペルチェックで「正しい」と認識されます。
例えば、myapiという用語を追加する場合：
.cspell/project-words.txtファイルを開きます。- 適切なセクションに
myapiを追加します。 - 変更を保存します。
次回のスペルチェック実行時に、その単語はエラーとして報告されなくなります。
このプロジェクトではGitHub Actionsを使用して、すべてのブランチへのプッシュ時に自動的にスペルチェックが実行されます。ワークフローは.github/workflows/spellcheck.ymlで定義されています。
このプロジェクトでは、Hadolintを使用してDockerfileの構文チェックを行っています。Hadolintは、Dockerfileのベストプラクティスに基づいたリンターで、潜在的な問題や改善点を自動的に検出します。
以下のDockerfileが自動チェックの対象となっています：
- ルートのDockerfile - アプリケーションのコンテナ化用
- DevContainer用Dockerfile - 開発環境用（
.devcontainer/Dockerfile） - GPU対応DevContainer用Dockerfile - GPU開発環境用（
.devcontainer/nvidia-gpu.Dockerfile）
Dockerfileが変更された場合、GitHub Actionsによって自動的にHadolintが実行されます。ワークフローの設定は.github/workflows/check-dockerfile.ymlで定義されています。
このワークフローには以下の特徴があります：
- Dockerfileが存在しない場合は自動的にチェックをスキップ
- 各Dockerfileに対して専用のジョブが実行される
- プッシュおよびプルリクエスト時に自動実行
このテンプレートリポジトリの保守運用に関する詳細はCONTRIBUTING.mdを参照してください。リリース手順についても同ファイルに記載されています。