URL 設計はリソースで考える

URL はアクションではなくリソース（名詞）を表します。

# 悪い例: 動詞を使っている
GET  /getUsers
POST /createUser
POST /deleteUser?id=123

# 良い例: リソース + HTTP メソッドで表現
GET    /users          # 一覧取得
POST   /users          # 作成
GET    /users/123      # 1件取得
PUT    /users/123      # 全体更新
PATCH  /users/123      # 部分更新
DELETE /users/123      # 削除

階層関係は URL で表現します。

GET /users/123/orders        # ユーザー123の注文一覧
GET /users/123/orders/456    # 特定の注文

HTTP ステータスコードを正しく使う

200 をすべてに使ってエラーをボディで返すのはやめましょう。

エラーレスポンスを統一する

エラー時のレスポンス形式を統一しておくと、クライアント側の実装が楽になります。

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "入力値が不正です",
    "details": [
      { "field": "email", "message": "有効なメールアドレスを入力してください" },
      { "field": "age", "message": "18歳以上である必要があります" }
    ]
  }
}

code にはマシンリーダブルな文字列を入れると、クライアントがプログラムで判定できます。

バージョニング

API を公開した後に破壊的変更をする場合はバージョンを切ります。

# URL パスにバージョンを含める（最も一般的）
/v1/users
/v2/users

# ヘッダーでバージョン指定（URL をきれいに保ちたい場合）
Accept: application/vnd.myapp.v2+json

ページネーション

大量データの取得にはページネーションを必ず実装します。

# カーソルベース（SNS のような無限スクロールに向く）
GET /posts?cursor=eyJpZCI6MTAwfQ&limit=20

# オフセットベース（ページ番号指定に向く）
GET /products?page=3&per_page=20

レスポンスには次のページの情報を含めます。

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIwfQ",
    "has_more": true
  }
}

まとめ

• URL はリソース（名詞）で設計する
• HTTP メソッドとステータスコードのセマンティクスに従う
• エラーレスポンスの形式を統一する
• 公開後の変更にはバージョニングで対応
• 一覧取得には必ずページネーションを

設計に迷ったときは「クライアントを実装する人が直感的に使えるか」を基準にすると判断しやすいです。

まず EXPLAIN で実行計画を確認する

チューニングの前に、データベースがどのようにクエリを実行しているか確認します。

EXPLAIN ANALYZE
SELECT * FROM orders
WHERE user_id = 123 AND status = 'pending';

注目するポイント:

• Seq Scan → テーブル全体を走査（遅い）
• Index Scan → インデックスを使用（速い）
• rows の見積もりと実際の差が大きい → 統計情報が古い

インデックスを正しく使う

複合インデックスのカラム順序

複合インデックスは左端のカラムから順に効きます。

-- このインデックスは (user_id, status) の順
CREATE INDEX idx_orders_user_status ON orders(user_id, status);

-- 有効: user_id が先頭にある
SELECT * FROM orders WHERE user_id = 123 AND status = 'pending';
SELECT * FROM orders WHERE user_id = 123;

-- 無効: user_id を含まない
SELECT * FROM orders WHERE status = 'pending';

カーディナリティ（値の種類数）が高いカラムを先頭に置くのが基本です。

インデックスが使われなくなるパターン

-- 関数をかけるとインデックスが効かない
WHERE UPPER(email) = 'USER@EXAMPLE.COM'  -- NG
WHERE email = 'user@example.com'          -- OK

-- 型が違うと暗黙変換でインデックスが効かないことがある
WHERE user_id = '123'  -- user_id が INTEGER の場合は注意

-- LIKE の前方一致はOK、後方一致はNG
WHERE name LIKE 'John%'   -- OK
WHERE name LIKE '%John'   -- NG（インデックス非効率）

N+1 問題を避ける

ループの中でクエリを発行するのは最も頻繁に見るパフォーマンス問題です。

-- N+1: ユーザーごとに注文数を取得 (1 + N 回のクエリ)
SELECT * FROM users;
-- ↓ ループ内で N 回実行
SELECT COUNT(*) FROM orders WHERE user_id = ?;

-- 改善: JOIN で1回にまとめる
SELECT u.id, u.name, COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.id, u.name;

不要なデータを取得しない

-- SELECT * は避ける
SELECT * FROM products;  -- NG

-- 必要なカラムだけ取得
SELECT id, name, price FROM products;  -- OK

-- LIMIT を忘れない
SELECT id, name FROM products
ORDER BY created_at DESC
LIMIT 20;

サブクエリより JOIN を使う

相関サブクエリは行ごとに実行されるため遅くなりがちです。

-- 遅い: 相関サブクエリ
SELECT name,
  (SELECT COUNT(*) FROM orders WHERE user_id = u.id) AS cnt
FROM users u;

-- 速い: JOIN で書き換え
SELECT u.name, COUNT(o.id) AS cnt
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.id, u.name;

まとめ

1. EXPLAIN ANALYZE で問題のあるクエリを特定する
2. 適切なインデックスを貼る（複合インデックスのカラム順に注意）
3. N+1 は JOIN でまとめる
4. SELECT * をやめ、必要なカラムだけ取得する

まずスロークエリログを有効にして、実際に遅いクエリを特定するところから始めましょう。

unknown を any の代わりに使う

any は型チェックを完全に無効にしますが、unknown は「何か分からない値」として扱い、使う前に型チェックを強制します。

// 危険: any はどこでも使えてしまう
function parseData(input: any) {
  return input.name.toUpperCase(); // 実行時エラーの可能性
}

// 安全: unknown は型ガードが必要
function parseData(input: unknown) {
  if (typeof input === "object" && input !== null && "name" in input) {
    return (input as { name: string }).name.toUpperCase();
  }
  throw new Error("Invalid input");
}

外部 API のレスポンスや JSON パースの結果には unknown を使いましょう。

Discriminated Union で状態を表現する

フラグのような boolean の組み合わせより、Union 型で状態を明示するほうが安全です。

// 問題: isLoading と error が同時に true になれる
type State = {
  isLoading: boolean;
  data: User | null;
  error: string | null;
};

// 改善: 状態が排他的になる
type State =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: User }
  | { status: "error"; error: string };

function render(state: State) {
  switch (state.status) {
    case "success":
      return state.data.name; // data が確実に存在する
    case "error":
      return state.error;     // error が確実に存在する
  }
}

satisfies 演算子で型チェックしながら型推論を保つ

TypeScript 4.9 で追加された satisfies は、型の整合性を確認しつつ推論された型を保持します。

type Config = {
  port: number;
  host: string;
};

// as を使うと推論が失われる
const config = { port: 3000, host: "localhost" } as Config;
config.port; // number

// satisfies なら具体的な型が残る
const config = { port: 3000, host: "localhost" } satisfies Config;
config.port; // 3000 (リテラル型)

設定オブジェクトの定義によく使います。

型ガード関数でナローイングを再利用する

同じ型チェックを複数箇所に書くなら、型ガード関数にまとめます。

type ApiResponse<T> =
  | { success: true; data: T }
  | { success: false; error: string };

function isSuccess<T>(res: ApiResponse<T>): res is { success: true; data: T } {
  return res.success === true;
}

const response = await fetchUser();
if (isSuccess(response)) {
  console.log(response.data); // T 型として使える
}

Readonly と as const でミュータブルなバグを防ぐ

意図せず変更されては困るオブジェクトは読み取り専用にします。

// 定数オブジェクト
const ROLES = ["admin", "editor", "viewer"] as const;
type Role = typeof ROLES[number]; // "admin" | "editor" | "viewer"

// 関数の引数を変更不可にする
function process(config: Readonly<Config>) {
  // config.port = 8080; // エラー
}

まとめ

• any より unknown — 型安全を保ちつつ柔軟に
• Discriminated Union — 状態管理を型で正確に表現
• satisfies — 型チェックと型推論を両立
• 型ガード関数 — ナローイングの再利用
• as const / Readonly — 不変性をコンパイル時に保証

型を「注釈」ではなく「設計ツール」として使うと、TypeScript の本領が発揮されます。

GitHub Flow — シンプルで速い

最もシンプルな戦略です。ブランチは main と feature/* の2種類だけ。

main
  └── feature/add-login
  └── feature/fix-typo

手順:

1. main から feature/xxx を切る
2. 実装して PR を出す
3. レビュー後に main へマージ
4. すぐデプロイ

向いている場面: 継続的デプロイができるプロダクト、スタートアップ、小〜中規模チーム。

git switch main
git pull origin main
git switch -c feature/add-login

# 実装...

git push origin feature/add-login
# → GitHub で PR を作成

Git Flow — リリース管理が必要なとき

バージョン管理が必要なアプリ（モバイルアプリ、パッケージなど）向けです。

main          ← 本番リリース済みコード
develop       ← 開発統合ブランチ
  └── feature/xxx
  └── release/1.2.0
  └── hotfix/crash-fix

ブランチの役割:

複雑な分、厳密なリリース管理が可能です。

コミットメッセージを統一する

どの戦略を採用しても、コミットメッセージのルールを決めておくと git log が読みやすくなります。

feat: ログイン機能を追加
fix: パスワードリセット時のエラーを修正
docs: README にセットアップ手順を追記
refactor: 認証ロジックをサービス層へ移動
chore: 依存ライブラリを更新

Conventional Commits に従うと、CHANGELOGの自動生成もできます。

PR のサイズは小さく保つ

ブランチ戦略と同じくらい重要なのが PR のサイズです。

• 1 PR = 1 つの目的
• 変更行数は 400 行以内を目安に
• レビュアーが 15 分で読み切れるくらいが理想

大きな機能はフラグで隠しながら小さく分割してマージするのが現実的です。

まとめ

• 小〜中規模で CI/CD が整っているなら GitHub Flow
• バージョン管理が必要なら Git Flow
• いずれにせよコミットメッセージとPRサイズのルールは最初に決める

ツールよりもチームの合意が大切です。

イメージとコンテナの違い

イメージはコンテナを起動するための設計図（テンプレート）です。読み取り専用で、Dockerfile から作られます。

コンテナはイメージを実際に起動したものです。書き込み可能な実行環境で、何度でも起動・停止できます。

Dockerfile → (build) → イメージ → (run) → コンテナ

クラスとインスタンスの関係に近いイメージです。

よく使うコマンド

# イメージを取得
docker pull node:22

# コンテナを起動（起動後すぐ削除）
docker run --rm node:22 node --version

# バックグラウンドで起動
docker run -d -p 3000:3000 --name my-app my-image

# 起動中のコンテナ一覧
docker ps

# コンテナの中に入る
docker exec -it my-app bash

# コンテナを停止・削除
docker stop my-app && docker rm my-app

Dockerfile の基本構造

FROM node:22-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

EXPOSE 3000
CMD ["node", "server.js"]

COPY と RUN はキャッシュが効くので、変更頻度の低いものを上に書くのがポイントです。package.json を先にコピーして npm ci することで、ソースコードを変えても依存関係の再インストールが走りません。

docker compose を使う

複数コンテナを管理するときは docker compose が便利です。

services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: password

docker compose up -d    # 起動
docker compose down     # 停止
docker compose logs -f  # ログ確認

まとめ

Docker の基本は「イメージを作って、コンテナとして動かす」この一点です。最初は docker run と docker compose up だけ覚えておけば十分です。慣れてきたら Dockerfile の最適化（マルチステージビルドなど）に進みましょう。