PHPのAPI連携「とりあえず動く」実装が本番で壊れる理由

開発環境では問題なく動いたPHPのAPI連携コードが、本番環境で突然エラーを起こす。その根本原因と、実運用に耐える実装パターンを解説します。

「開発環境では動いていたのに」——その一言が引き金になる

こんな経験はありませんか？

• 外部APIとの連携機能を実装して、テスト環境では問題なく動作した
• リリース直後は快調だったのに、数週間後に突然エラーが頻発し始めた
• ログを見ても原因がよくわからず、とりあえず再起動で誤魔化した

実は、これはPHP開発において非常によくあるパターンです。Fivenineでも過去に、決済代行サービスとの連携を担当したプロジェクトで同様の事象を経験したことがあります。あるECサイトのクライアントから「本番移行後に注文確定メールが届かないケースが出ている」という連絡が入り、原因を追跡してみると、外部メール送信APIへのリクエストがタイムアウトしていたにもかかわらず、コード上でそれを検知できていなかったというものでした。

本記事では、「とりあえず動く」実装が本番環境で壊れやすい構造的な理由を掘り下げ、実運用に耐えるAPI連携の実装パターンを具体的に解説します。エラーハンドリングの設計、タイムアウト設定、リトライ処理など、開発段階で意識すべき観点を中心に整理しました。

なぜ「開発環境では動く」のか——本番との構造的な差異

開発環境と本番環境の最大の違いは、「予測不能な外部要因の存在」 です。開発中は自分のマシンや安定したネットワーク上でAPIを叩くため、レイテンシのばらつきやサービス側の一時障害を体験することがほとんどありません。

本番環境では以下のような事象が日常的に発生します。

• 外部APIサーバーの一時的な過負荷によるレスポンス遅延（通常200msが3秒を超えることも）
• ネットワーク経路の不安定さによる接続タイムアウト
• APIプロバイダーのバージョンアップによるレスポンス構造の変更
• レート制限（Rate Limit） への到達によるリクエスト拒否（HTTP 429）
• 認証トークンの期限切れによる401エラーの突発的発生

「とりあえず動く」コードはこれらを一切考慮していないため、予期しない事態が起きた瞬間に無言で失敗します。エラーがユーザーに丸見えになるか、あるいはサイレントに処理が抜け落ちるかのどちらかです。

「とりあえず実装」の典型例と、本番対応コードの比較

よくある「動くだけ」の実装

// ❌ よくあるNG実装
function fetchUserFromApi(string $userId): array
{
    $response = file_get_contents(
        "https://api.example.com/users/{$userId}"
    );

    return json_decode($response, true);
}

このコードの問題点は一目瞭然です。タイムアウト設定がなく、HTTPエラーへの対応もなく、$responseがfalseだった場合にjson_decodeはnullを返し、呼び出し元は何が起きたか把握できません。

Guzzleを使った本番対応の実装

Laravelプロジェクトであれば、GuzzleかHttpファサードを使うのがベストプラクティスです。以下は実プロジェクトで採用したパターンをベースにした実装です。

<?php

use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class UserApiService
{
    private const TIMEOUT_SECONDS = 10;
    private const RETRY_TIMES = 3;
    private const RETRY_SLEEP_MS = 500;

    public function fetchUser(string $userId): ?array
    {
        try {
            $response = Http::timeout(self::TIMEOUT_SECONDS)
                ->withToken(config('services.example_api.token'))
                ->retry(self::RETRY_TIMES, self::RETRY_SLEEP_MS, function ($exception) {
                    // 429（レート制限）と503（一時障害）のみリトライ対象
                    return $exception instanceof RequestException
                        && in_array($exception->response->status(), [429, 503]);
                })
                ->get("https://api.example.com/users/{$userId}");

            if ($response->failed()) {
                Log::warning('User API responded with error', [
                    'status'  => $response->status(),
                    'user_id' => $userId,
                    'body'    => $response->body(),
                ]);
                return null;
            }

            return $response->json();

        } catch (\Exception $e) {
            Log::error('User API request failed', [
                'user_id' => $userId,
                'message' => $e->getMessage(),
            ]);
            return null;
        }
    }
}

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use Psr\Log\LoggerInterface;

class UserApiService
{
    private Client $client;
    private LoggerInterface $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;

        $stack = HandlerStack::create();
        // リトライミドルウェアを追加
        $stack->push(Middleware::retry(
            function ($retries, $request, $response, $exception) {
                if ($retries >= 3) return false;
                if ($exception instanceof RequestException) return true;
                if ($response && in_array($response->getStatusCode(), [429, 503])) return true;
                return false;
            },
            fn($retries) => $retries * 500 // バックオフ（500ms, 1000ms, 1500ms）
        ));

        $this->client = new Client([
            'base_uri' => 'https://api.example.com/',
            'timeout'  => 10.0,
            'headers'  => [
                'Authorization' => 'Bearer ' . getenv('API_TOKEN'),
                'Accept'        => 'application/json',
            ],
            'handler'  => $stack,
        ]);
    }

    public function fetchUser(string $userId): ?array
    {
        try {
            $response = $this->client->get("users/{$userId}");
            return json_decode($response->getBody()->getContents(), true);
        } catch (RequestException $e) {
            $this->logger->error('User API request failed', [
                'user_id' => $userId,
                'message' => $e->getMessage(),
                'status'  => $e->hasResponse() ? $e->getResponse()->getStatusCode() : null,
            ]);
            return null;
        }
    }
}

本番対応コードで押さえているポイントは以下の3点です。

• タイムアウトを明示的に設定（timeout(10)）：外部サービスの応答待ちで PHP プロセスが詰まるのを防ぐ
• リトライ対象を絞る：全エラーをリトライすると副作用（二重登録など）が起きるため、冪等性が保証できるケースのみを対象にする
• エラーを必ずログに残す：「なんかたまに失敗してる」状態から「いつ・どのリクエストが・なぜ落ちたか」が追跡できる状態へ

よくある失敗パターンと、その対処法

❌ 失敗パターン1：APIキーをコードに直書きする

// これをやると git push した瞬間にキーが漏洩する
$apiKey = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx';

対処： .envファイルとconfig()を介して管理する。Laravelならconfig/services.phpに定義し、本番環境では環境変数として注入するのが鉄則です。

❌ 失敗パターン2：レスポンス構造を信頼しすぎる

外部APIはメジャーバージョンアップで突然レスポンス構造を変えることがあります。$data['user']['email']のようにネストしたキーに直アクセスするコードは、構造が変わった瞬間にUndefined indexエラーを吐きます。

// ❌ 危険
$email = $response['data']['user']['email'];

// ✅ 安全
$email = $response['data']['user']['email'] ?? null;
if ($email === null) {
    Log::warning('APIレスポンスにemailフィールドが存在しない', $response);
}

❌ 失敗パターン3：全処理を同期的に行う

ユーザーのリクエスト処理中にAPIを叩くと、そのAPI呼び出しが遅延した分だけユーザーへのレスポンスが遅くなります。通知送信・外部への書き込みなど、即時性が不要な処理はLaravelの**キュー（Queue）**に委譲することで、ユーザー体験を損なわずに安全に処理できます。

// ✅ 通知送信はキューに投げて即レスポンスを返す
SendExternalNotificationJob::dispatch($userId, $payload)
    ->onQueue('notifications');

❌ 失敗パターン4：エラーをキャッチして握りつぶす

try {
    $result = $apiService->fetchUser($id);
} catch (\Exception $e) {
    // 何もしない ← これが一番危険
}

沈黙するコードは最も発見が遅れます。たとえ処理を継続させる場合でも、必ずログを残してください。

まとめ：「動く」と「壊れない」は全く別の話

API連携の実装において、開発環境での動作確認は「スタート地点」に過ぎません。本番環境で本当に信頼できるコードにするためには、タイムアウト・エラーハンドリング・リトライ・ロギング・非同期化という5つの観点が不可欠です。

Fivenineでは、API連携を含む機能開発の際には必ずコードレビューで上記の観点をチェックし、リリース前に意図的にAPIをダウンさせた状態でのテストも実施しています。「本番で壊れてから直す」のではなく、「壊れることを前提に設計する」——この思想の転換が、安定したシステムを作る上での核心です。

自社のシステムにAPI連携が含まれており、現状の実装に不安を感じている方は、ぜひFivenineへご相談ください。コードレビューや既存実装の診断から対応しています。