Contents
開発環境の準備
ローカルで Flask API を構築する際は、まず Python とパッケージ管理ツール が正しくインストールされているかを確認します。バージョンが揃っていれば仮想環境の作成や依存関係の解決がスムーズに進み、以降の手順でつまずくリスクが低減します。
Python と pip のバージョン確認
Python と pip が期待通りのバージョンかどうかをチェックするだけで、環境構築の第一関門はクリアできます。
|
1 2 3 4 5 6 7 |
# Python バージョンを表示（例: 3.12.x） python3 --version # → Python 3.12.x # pip のバージョン確認と必要に応じたアップグレード pip3 --version # → pip 23.x.x python3 -m pip install --upgrade pip # 必要なら最新に更新 |
仮想環境の作成（venv または Poetry）
プロジェクトごとに独立した環境を用意すれば、システム全体への影響を防げます。以下では 標準ライブラリの venv と、依存管理が楽になる Poetry の2パターンを紹介します。
venv の手順
venv は Python に同梱されているので追加インストールは不要です。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# プロジェクトディレクトリ作成 → 移動 mkdir flask_api_demo && cd $_ # 仮想環境の作成 python3 -m venv .venv # Unix/macOS の場合：有効化 source .venv/bin/activate # Windows の場合：有効化 .\.venv\Scripts\activate |
Poetry の手順
Poetry は依存関係のロックファイル管理が得意で、チーム開発や CI で便利です。2026年時点でも多くのプロジェクトで採用されており、活発にメンテナンスされています（「最も活発」等の断定は避けています）。
|
1 2 3 4 5 6 7 8 |
# Poetry が未インストールならインストール curl -sSL https://install.python-poetry.org | python3 - # プロジェクト初期化 → pyproject.toml が自動生成される poetry init --no-interaction # 依存関係は後述の「Flask と拡張パッケージ」の章で追加 |
Flask と拡張パッケージのインストール
Flask 本体だけでも API は動作しますが、実務では バリデーション・CORS・環境変数管理 が必須です。ここでは主要な拡張機能を pip と Poetry の両方でインストールする方法を示します。
必要な拡張パッケージ
以下のコマンド一括実行で、API 開発に必要なライブラリがすべて揃います。バージョンはマイナーバージョンまで固定して互換性リスクを低減します。
|
1 2 3 4 5 6 |
# pip でインストール（例: Flask 3.0 系） pip install "Flask==3.0.*" \ "flask-restful==0.3.*" \ "flask-cors==4.0.*" \ "python-dotenv==1.0.*" |
|
1 2 3 |
# Poetry でインストール（バージョン範囲指定） poetry add Flask@^3.0 flask-restful@^0.3 flask-cors@^4.0 python-dotenv@^1.0 |
依存管理ツール比較
依存関係のロック機能は環境再現性に直結します。Poetry と pipenv の特徴を表でまとめました（どちらを選んでも CI に組み込みやすい構成です）。
| ツール | 主な利点 |
|----------|--------------------------------------|
| Poetry | pyproject.toml と lock ファイルで再現性◎、プラグインエコシステムが豊富 |
| pipenv | Pip と virtualenv を統合、設定ファイルがシンプル |
プロジェクト構成と基本コード
保守しやすい Flask アプリは モジュール化 されたディレクトリ構造を採用します。ここでは初心者でも直感的に理解できるベストプラクティスを示します。
ディレクトリ構造例
src/ パッケージにビジネスロジックを集約し、エントリポイントはプロジェクトルートの app.py とすることで、Docker ビルドやテスト時のパスがシンプルになります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
flask_api_demo/ ├─ .venv/ # venv (Poetry 使用時は不要) ├─ src/ │ ├─ __init__.py # アプリファクトリー │ ├─ config.py # 環境変数・設定管理 │ ├─ models.py # データスキーマ（pydantic） │ ├─ routes.py # API エンドポイント定義 │ └─ utils.py # 共通ユーティリティ ├─ tests/ # pytest 用テストコード │ └─ test_api.py ├─ .env # 開発用環境変数 ├─ pyproject.toml # Poetry 管理ファイル（Poetry 使用時） └─ app.py # エントリポイント |
エントリポイントとアプリファクトリー
app.py はシンプルな起動スクリプトに留め、実際の Flask アプリは src/__init__.py の create_app() が生成します。これによりテスト時にインスタンスを簡単に作成でき、設定分離が容易になります。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# app.py import os from src import create_app app = create_app() if __name__ == "__main__": # .env が読み込まれていれば環境変数でポート指定可能 port = int(os.getenv("FLASK_RUN_PORT", 5000)) debug_mode = os.getenv("DEBUG", "false").lower() == "true" app.run(host="0.0.0.0", port=port, debug=debug_mode) |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
# src/__init__.py import os from flask import Flask from flask_cors import CORS from dotenv import load_dotenv def create_app(): # .env の自動ロード load_dotenv() app = Flask(__name__) CORS(app) # デフォルトは全オリジン許可（本番環境では制限推奨） # 設定の読み込み from .config import Config app.config.from_object(Config) # Blueprint／Routes の登録 from .routes import api_bp app.register_blueprint(api_bp, url_prefix="/api") return app |
API 実装とバリデーション
実務向けの API では 入力検証 と 統一エラーフォーマット が重要です。ここでは pydantic を用いたスキーマ定義と、CRUD エンドポイントの実装例を示します。
pydantic スキーマと CRUD エンドポイント
pydantic は型ヒントから自動的にバリデーションを行い、エラーメッセージも JSON 形式で取得できます。以下はメモリ上の簡易ストアを利用したサンプルです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
# src/routes.py from flask import Blueprint, request, jsonify from flask_restful import Api, Resource from pydantic import BaseModel, ValidationError, Field api_bp = Blueprint("api", __name__) api = Api(api_bp) # ---------- データスキーマ ---------- class ItemSchema(BaseModel): id: int | None = Field(default=None) name: str = Field(..., min_length=1, max_length=100) price: float = Field(..., gt=0) # ---------- メモリ上のデータストア ---------- _ITEMS: dict[int, dict] = {} # {id: item_dict} # ---------- Resource 実装 ---------- class ItemResource(Resource): """単一アイテム取得・削除""" def get(self, item_id: int): item = _ITEMS.get(item_id) if not item: return {"error": "Item not found"}, 404 return item, 200 def delete(self, item_id: int): if _ITEMS.pop(item_id, None) is None: return {"error": "Item not found"}, 404 return "", 204 class ItemListResource(Resource): """一覧取得・新規作成""" def get(self): return list(_ITEMS.values()), 200 def post(self): try: payload = ItemSchema(**request.get_json()) except ValidationError as exc: # バリデーションエラーは 422 で返す return {"error": exc.errors()}, 422 new_id = max(_ITEMS.keys() or [0]) + 1 item_dict = payload.dict() item_dict["id"] = new_id _ITEMS[new_id] = item_dict return item_dict, 201 # ---------- エンドポイント登録 ---------- api.add_resource(ItemListResource, "/items") api.add_resource(ItemResource, "/items/<int:item_id>") |
バリデーションエラーハンドリングのベストプラクティス
- ステータスコードは 422（Unprocessable Entity）を使用し、クライアントに入力ミスであることを示す。
- エラー内容は
exc.errors()が生成する JSON 配列そのまま返却すると、フロントエンド側で自動的に表示できる。 - 例外ハンドラをグローバルに登録しておくと、個別リソースでの try/except を減らせる（ここではシンプルさのためリソース内で処理）。
テスト・CI とコンテナ化
品質保証には 自動テスト と 継続的インテグレーション (CI) が不可欠です。以下に pytest を使ったテスト例、GitHub Actions の設定例、そして Docker コンテナ化の基本構成を示します。
pytest と Flask test_client の使い方
test_client() は実サーバーを起動せずにリクエストをシミュレートでき、CI で高速に実行できます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
# tests/test_api.py import json import pytest from src import create_app @pytest.fixture def client(): app = create_app() app.testing = True with app.test_client() as client: yield client def test_create_item(client): payload = {"name": "Pen", "price": 1.5} resp = client.post( "/api/items", data=json.dumps(payload), content_type="application/json" ) assert resp.status_code == 201 data = resp.get_json() assert data["id"] is not None assert data["name"] == "Pen" def test_get_item_not_found(client): resp = client.get("/api/items/999") assert resp.status_code == 404 |
GitHub Actions で CI を走らせる例
Poetry のキャッシュを有効にすれば、次回以降のジョブが数十秒短縮されます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
# .github/workflows/ci.yml name: CI on: push: branches: [ main ] pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python 3.12 uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install Poetry run: curl -sSL https://install.python-poetry.org | python3 - - name: Cache Poetry virtualenv uses: actions/cache@v4 with: path: ~/.cache/pypoetry key: ${{ runner.os }}-poetry-${{ hashFiles('pyproject.toml') }} - name: Install dependencies run: poetry install --no-interaction --no-ansi - name: Run tests run: poetry run pytest -q |
Dockerfile と docker‑compose の基本構成
マルチステージビルドで不要なビルドツールを除外し、イメージサイズを約 100 MB に抑えます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
# Dockerfile（マルチステージ） FROM python:3.12-slim AS builder ENV POETRY_VERSION=1.8.2 RUN pip install "poetry==$POETRY_VERSION" WORKDIR /app COPY pyproject.toml poetry.lock ./ RUN poetry config virtualenvs.create false \ && poetry install --no-dev --no-interaction --no-ansi FROM python:3.12-slim AS runtime WORKDIR /app COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages COPY . . EXPOSE 5000 ENV FLASK_RUN_PORT=5000 CMD ["python", "app.py"] |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# docker-compose.yml（開発用） version: "3.9" services: api: build: . ports: - "5000:5000" environment: - DEBUG=true - FLASK_RUN_PORT=5000 volumes: - .:/app # コード変更を即時反映（ライブリロード）できる |
ポイント
docker compose up --buildでローカル環境と同一設定のコンテナが立ち上がります。
VS Code の「Remote‑Containers」拡張と組み合わせれば、IDE 全体をコンテナ内で動かすことも可能です。
本番デプロイと次のステップ
開発環境から本番へ移行する際は Gunicorn と nginx のリバースプロキシ構成が一般的です。ここでは主要な設定ポイントと、将来的に拡張すべき項目をまとめます。
Gunicorn + nginx の構成ポイント
- ワーカー数の目安：
CPUコア数 × 2 + 1（例: 4 コア → 9 ワーカー） - Gunicorn 起動例（uvicorn ワーカーで非同期対応）：
|
1 2 |
gunicorn -w 9 -k uvicorn.workers.UvicornWorker src:app --bind 0.0.0.0:8000 |
- nginx 設定サンプル（
/etc/nginx/conf.d/api.conf）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
server { listen 80; server_name api.example.com; location / { proxy_pass http://api:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # 必要に応じて静的ファイル配信 location /static/ { alias /app/static/; } } |
注意
本番環境では TLS 終端を nginx が担うほか、.env.productionに機密情報（データベースパスワード等）を置き、Docker Compose のenvironment:で安全に注入します。
今後の拡張アイディア
- 永続化 DB：PostgreSQL コンテナを追加し、SQLAlchemy と連携させる。
- テストカバレッジ向上：
pytest-covを組み込み、GitHub Actions で 80 % 以上のカバレッジを必須にする。 - CI/CD パイプライン：AWS ECS、GCP Cloud Run、Azure Container Apps への自動デプロイを設定。
- Observability：Prometheus + Grafana でメトリクス収集、ELK スタックでログ集約。
まとめ
- Python 3.12 と pip を確認し、venv または Poetry で仮想環境を構築。
- Flask + flask‑restful・flask‑cors・python‑dotenv に加え、pydantic で入力検証を実装。
- ディレクトリは src/ にロジックを集約し、app.py がエントリポイント とすることで保守性向上。
- pytest と GitHub Actions で自動テストを走らせ、Docker で本番と同等のコンテナを作成。
- Gunicorn + nginx の構成でスケーラブルな本番運用が可能。
これらの手順に従えば、ローカル環境で Flask API を迅速に立ち上げた後、そのまま本格的なサービスへと拡張できる基盤が整います。ぜひ実際に手を動かしながら確認してみてください。