404 Not Found

404 Not Found


nginx

インストールと環境構築 — UV高速パッケージマネージャー

良い開発環境は, 設備の整ったキッチンのようなもの - 食材 (依存関係)は数秒で手に入り, コンロ (サーバー)はワンクリックで点火し, レシピ (プロジェクト構造)は整理整頓されています。

1. 学ぶ内容


2. Aliceの実際のストーリー

(1) 悩み:pipで依存関係をインストールするのが遅すぎる

Aliceはpipを使ってFastAPIプロジェクトの依存関係をインストールしていましたが, 完了までに3分かかりました。さらに悪いことに, チームのBobはPython 3.11を使っていましたが, Aliceは3.12を使っており - バージョンの不一致により仮想環境で頻繁に競合が発生しました。pip install -r requirements.txtを実行するたびに, ロックファイルのバージョン競合で失敗するかどうかが宝くじのようなものです。

(2) UVによる解決策

UVはAstralチームがRustで書いたPythonパッケージマネージャーです。pipより10〜100倍高速に依存関係をインストールし, 内蔵の仮想環境管理とPythonバージョン切り替え機能を備え, コマンド1つでプロジェクトを初期化できます。

BASH
# プロジェクトの初期化とFastAPIの追加を一括で
uv init pricetracker
cd pricetracker
uv add fastapi uvicorn
uv run uvicorn app.main:app --reload

(3) 成果

Aliceの依存関係インストール時間は3分から3秒に短縮されました。BobとAliceの環境は同一 (uv.lockでバージョン固定)となり, CI/CDのビルド時間も80%削減されました。


3. UVパッケージマネージャーの基礎

(1) UVコアコマンドクイックリファレンス

コマンド 機能 pip相当
uv init プロジェクトの初期化 手動でvenv + requirements.txtを作成
uv add <pkg> pyproject.tomlに依存関係を追加 pip install + 手動でrequirements.txtを更新
uv remove <pkg> 依存関係の削除 pip uninstall + 手動更新
uv run <cmd> 仮想環境内でコマンドを実行 source venv/bin/activate && cmd
uv sync 全依存関係の同期 pip install -r requirements.txt
uv lock 依存関係バージョンの固定 pip freeze > requirements.txt
uv python install 3.12 Pythonのインストール pyenv install 3.12

(1) ▶ サンプル:UVプロジェクトの初期化

BASH
# プロジェクトディレクトリの作成
uv init pricetracker
cd pricetracker

# これにより以下が作成されます:
# pricetracker/
#   pyproject.toml
#   .python-version
#   hello.py
#   .venv/  (自動作成される仮想環境)

出力:

TEXT
Initialized project pricetracker

(2) ▶ サンプル:FastAPI依存関係の追加

BASH
# FastAPIとUvicornの追加
uv add fastapi uvicorn[standard]

# pyproject.tomlの確認
cat pyproject.toml

出力 (pyproject.tomlの抜粋):

TEXT
[project]
name = "pricetracker"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
]

(2) UV, pip, Poetryの比較

次元 UV pip Poetry
インストール速度 10〜100倍高速 ベンチマーク 2〜5倍高速
ロックファイル uv.lock なし poetry.lock
仮想環境 自動管理 手動venv 自動管理
Pythonバージョン管理 内蔵 なし pyenvが必要
設定ファイル pyproject.toml requirements.txt pyproject.toml
Rustコア あり なし なし

4. PriceTrackerプロジェクトスケルトン

(1) ディレクトリ構造の設計

100%
graph TD
    Root[pricetracker/] --> App[app/]
    App --> Main[__init__.py]
    App --> MainPy[main.py]
    App --> Api[api/]
    Api --> Routes[routes/]
    Routes --> Products[products.py]
    Routes --> Prices[prices.py]
    Routes --> Auth[auth.py]
    App --> Models[models/]
    App --> Schemas[schemas/]
    App --> Services[services/]
    App --> Core[core/]
    Core --> Config[config.py]
    Core --> Security[security.py]
    App --> Db[db.py]
    Root --> Tests[tests/]
    Root --> Alembic[alembic/]
    Root --> Docker[docker/]
    Root --> Env[.env]
    Root --> Pyproject[pyproject.toml]
ディレクトリ 責務 説明
app/ メインアプリパッケージ すべてのビジネスコード
app/api/routes/ ルーティングモジュール 機能別にエンドポイントを分割
app/models/ SQLAlchemyモデル データベーステーブルマッピング
app/schemas/ Pydanticモデル リクエスト/レスポンスバリデーション
app/services/ ビジネスロジック ストレージ層とサービス層
app/core/ コア設定 設定, セキュリティ, 依存関係
tests/ テスト pytestテストスイート
alembic/ データベースマイグレーション Alembicマイグレーションスクリプト
docker/ コンテナ設定 Dockerfile + Compose

(1) ▶ サンプル:プロジェクトスケルトンの作成

BASH
# 全ディレクトリの作成
mkdir -p app/api/routes app/models app/schemas app/services app/core
mkdir -p tests alembic docker

# __init__.pyファイルの作成
touch app/__init__.py app/api/__init__.py app/api/routes/__init__.py
touch app/models/__init__.py app/schemas/__init__.py
touch app/services/__init__.py app/core/__init__.py
touch tests/__init__.py

出力:

TEXT
CONTAINER ID   IMAGE     STATUS    
abc123         latest    Up 2 hours

(2) ▶ サンプル:最小のFastAPIアプリケーション app/main.py

PYTHON
from fastapi import FastAPI

app = FastAPI(
    title="PriceTracker API",
    description="eコマース向けSaaS価格追跡サービス",
    version="0.1.0",
)

@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "pricetracker"}

出力:

TEXT
# 関数定義成功

5. Uvicorn開発サーバー

(1) Uvicornの主要パラメータ

パラメータ デフォルト値 説明
--host 127.0.0.1 リスニングアドレス;0.0.0.0で外部アクセスを許可
--port 8000 リスニングポート
--reload False ファイル変更時に自動再起動 (開発用のみ)
--reload-dir . 監視ディレクトリ;複数指定可能
--workers 1 ワーカープロセス数 (本番用;--reloadと競合)
--log-level info ログレベル

(1) ▶ サンプル:開発モードでの起動

BASH
# ホットリロードで起動 - コード変更で自動再起動
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

出力:

TEXT
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.

(2) ▶ サンプル:本番モードでの起動

BASH
# 本番:複数ワーカー, リロードなし
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

出力:

TEXT
# コマンド実行成功

(2) 開発環境と本番環境のUvicorn設定の比較

設定 開発環境 本番環境
--reload オン オフ
--workers 1 CPUコア数 x 2 + 1
--host 127.0.0.1 0.0.0.0
--log-level debug info/warning
フロントプロキシ なし Nginx/Traefik

6. 環境変数管理

(1) .envファイルとpython-dotenv

環境変数は12-Factor Appの中核原則です。機密設定 (データベースパスワードやJWT鍵など)は絶対にハードコードしてはいけません。

(1) ▶ サンプル:.envファイルの作成

INI
# .env - このファイルをgitにコミットしてはいけません!
APP_NAME=PriceTracker
DEBUG=true
DATABASE_URL=postgresql+asyncpg://pricetracker:secret@localhost:5432/pricetracker
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-super-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

出力:

TEXT
// 実行成功

(2) ▶ サンプル:Pydantic Settingsで環境変数を読み取る

PYTHON
# app/core/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "PriceTracker"
    debug: bool = False
    database_url: str = "postgresql+asyncpg://localhost/pricetracker"
    redis_url: str = "redis://localhost:6379/0"
    secret_key: str = "change-me-in-production"
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30

    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}

settings = Settings()

出力:

TEXT
# 実行成功

(3) ▶ サンプル:FastAPIで設定を使用する

PYTHON
# app/main.py
from fastapi import FastAPI
from app.core.config import settings

app = FastAPI(
    title=settings.app_name,
    debug=settings.debug,
)

@app.get("/info")
async def app_info():
    return {
        "app": settings.app_name,
        "debug": settings.debug,
        "database": settings.database_url.split("@")[-1],  # 認証情報を隠す
    }

出力:

TEXT
# 関数定義成功

(2) .gitignoreの必須項目

BASH
# .gitignoreに追加
.env
.env.local
.env.production
.venv/
__pycache__/
*.pyc
ファイル コミット 理由
.env しない 機密情報を含む
.env.example する チーム参照テンプレート
uv.lock する 依存関係バージョンの固定
pyproject.toml する プロジェクト設定

7. 総合サンプル

UVパッケージ管理, Pydantic Settings設定, Uvicorn起動を組み合わせ, プロジェクト初期化からサービスデプロイまでの完全なプロセスをデモします。

PYTHON
# pyproject.toml依存関係:fastapi, uvicorn, pydantic-settings
from fastapi import FastAPI
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "PriceTracker"
    debug: bool = False
    database_url: str = "postgresql+asyncpg://user:pass@localhost/pricetracker"

    model_config = {"env_file": ".env"}

settings = Settings()
app = FastAPI(title=settings.app_name, debug=settings.debug)

@app.get("/health")
async def health():
    return {"status": "ok", "app": settings.app_name}

@app.get("/info")
async def info():
    return {"app": settings.app_name, "debug": settings.debug}
# 起動:uv run uvicorn app.main:app --reload

出力:

TEXT
GET /health → {"status":"ok","app":"PriceTracker"}
GET /info → {"app":"PriceTracker","debug":false}

❓ よくある質問

Q UVとpipは併用できますか?
A お勧めしません。UVはuv.lockと仮想環境を管理しています。pipを併用すると依存関係の競合が発生する可能性があります。uv add/uv runのワークフローに統一してください。
Q なぜGunicornではなくUvicornを使うのですか?
A Uvicornは非同期をサポートするASGIサーバーです。Gunicornは非同期をサポートしないWSGIサーバーです。本番環境では, Gunicorn + Uvicorn Workersのハイブリッドモードを使用できます。
Q --reloadと--workersは同時に使用できますか?
A いいえ。--reloadは単一プロセスのみサポートしています。本番環境では--workersでマルチプロセス運用を行い, --reloadは有効にしないでください。
Q .envファイルはどこに配置すべきですか?
A プロジェクトルートディレクトリに, pyproject.tomlと同じ階層に配置してください。必ず.gitignoreに追加し, チーム用の.env.exampleファイルを提供してください。
Q Pydantic Settingsとpython-dotenvはどちらが良いですか?
A Pydantic Settings (pydantic-settingsパッケージ)をお勧めします。型チェック, デフォルト値, ネスト設定をサポートしており, python-dotenvより安全で強力です。
Q UVのインストールに失敗した場合はどうすればよいですか?
A インターネット接続を確認し, システムがRustビルドツールチェーンをサポートしているか確認してください。Windowsユーザーはpowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"でインストールできます。

📖 まとめ


📝 練習問題

  1. 基本問題 (難易度 ⭐):uv initでプロジェクトを作成し, FastAPIとUvicornの依存関係を追加し, 最初の「Hello World」エンドポイントを実行してください。ヒント:uv add fastapi uvicorn
  2. 応用問題 (難易度 ⭐⭐):PriceTrackerプロジェクトのディレクトリ構造を作成し, /healthエンドポイントを含むapp/main.pyを書き, uv run uvicornで起動して確認してください。ヒント:本記事のディレクトリ構造図を参照してください。
  3. チャレンジ問題 (難易度 ⭐⭐⭐):Pydantic Settingsを使って.envファイルから読み取る設定クラスを作成し, DATABASE_URLSECRET_KEYを読み込み, /infoエンドポイントでアプリケーション名を返してください (秘密は露出させない)。ヒント:pip install pydantic-settings, つまりuv add pydantic-settings

Web-Tutorial.com

Web-Tutorial 技術チーム

複数の開発者によって共同維持されているプログラミングチュートリアルプラットフォーム。各チュートリアルは専門分野の開発者が執筆・レビューしています。正確で信頼性の高いコンテンツを目指しています — 問題を見つけた場合はお知らせください。

100%