ドキュメント価格ブログ
お問い合わせ
ログイン無料で新規登録
Back to Tech Articles

Go APIのための堅牢なエラーハンドリングシステムの構築

10月 13, 2025
# Misc

Wenhao Wang

Dev Intern · Leapcell

この記事はEnglish、한국어、Deutschでも利用できます
Cover of "Go APIのための堅牢なエラーハンドリングシステムの構築"

はじめに

ネットワークアプリケーションの世界、特にマイクロサービスやAPIにおいて、適切なエラーハンドリングは単なるベストプラクティスではなく、信頼性が高くユーザーフレンドリーなシステムの重要な構成要素です。問題が発生した場合、不透明または不可解なエラーメッセージは、ユーザーをイライラさせ、下流のサービスを誤解させ、開発者のデバッグ作業を複雑にする可能性があります。逆に、明確に定義された構造化されたエラーシステムは、問題の明確な伝達、運用上の洞察のための整合性の取れたロギング、およびさまざまなAPIエンドポイント間での予測可能な動作を可能にします。この記事では、Goでそのようなシステムを設計すること、特にAPIレスポンスと内部ロギングの両方でエラーを効果的に管理する方法に焦点を当て、アプリケーションが機能的であるだけでなく、回復力があり、観測可能であることを保証します。

構造化エラーのコアコンセプト

実装に入る前に、構造化エラーハンドリングアプローチに不可欠ないくつかの重要な用語を定義しましょう。

  • エラーコード: システム内の特定のエラータイプを表す、通常は文字列または列挙型のユニークな識別子。これは、人間が読めるメッセージとは独立して、エラーを機械的に読み取り分類するための標準化された方法を提供します。
  • エラーカテゴリ/タイプ: エラーのより広範な分類（例: 検証エラー、認証エラー、内部サーバーエラー）。これは、類似のエラーコードをグループ化するのに役立ち、エラーの処理方法や提示方法に影響を与える可能性があります。
  • ユーザーメッセージ: ユーザーまたはクライアントアプリケーション向けに意図された、人間にとって読みやすいメッセージであり、何がうまくいかなかったかを理解しやすい非技術的な方法で説明します。このメッセージは、ロケールによって異なる場合があります。
  • 開発者メッセージ: デバッグ中に開発者向けに意図された、より詳細で技術的なメッセージ。これには、内部の詳細、コンテキスト、および潜在的な修復手順が含まれる場合があります。
  • エラーコンテキスト: エラーに関する特定のコンテキスト情報を提供する追加の動的なキーと値のペア。たとえば、検証エラーの場合、これは検証に失敗したフィールドと無効な値を含む可能性があります。データベースエラーの場合、試行されたクエリが含まれる場合があります。
  • HTTPステータスコード: HTTPリクエストの結果を示す標準の数値コード（例: 200 OK、400 Bad Request、500 Internal Server Error）。エラーに関連していますが、私たちの内部エラー構造は、それ自体がエラーであることではなく、HTTPステータスコードの選択を推進します。

Goで構造化エラーシステムを設計する

私たちの目標は、これらのすべての情報をカプセル化するカスタムエラータイプをGoで作成することです。これにより、アプリケーション全体にリッチなエラー詳細を伝達し、APIレスポンスやログエントリに適切に変換できるようになります。

カスタムエラータイプ

カスタムエラー構造体を定義しましょう。

package apperror

import (
	"fmt"
	"net/http"
)

// Category はエラーの広範なタイプを定義します。
type Category string

const (
	CategoryBadRequest       Category = "BAD_REQUEST"
	CategoryUnauthorized     Category = "UNAUTHORIZED"
	CategoryForbidden        Category = "FORBIDDEN"
	CategoryNotFound         Category = "NOT_FOUND"
	CategoryConflict         Category = "CONFLICT"
	CategoryInternal         Category = "INTERNAL_SERVER_ERROR"
	CategoryServiceUnavailable Category = "SERVICE_UNAVAILABLE"
	// 必要に応じてさらにカテゴリを追加
)

// Error は構造化されたアプリケーションエラー表します。
type Error struct {
	Code        string                 `json:"code"`                  // エラーの一意の識別子（例：「USER_NOT_FOUND」）
	Category    Category               `json:"category"`              // エラーの広範なカテゴリ（例：「NOT_FOUND」）
	UserMessage string                 `json:"user_message"`          // ユーザーフレンドリーなメッセージ
	DevMessage  string                 `json:"dev_message,omitempty"` // 開発者フレンドリーなメッセージ、オプション
	Context     map[string]interface{} `json:"context,omitempty"`     // コンテキストのための追加のキーと値のペア
	Cause       error                  `json:"-"`                     // 基になるエラー、シリアライズされない
}

// Error はエラーインターフェースを実装します。
func (e *Error) Error() string {
	if e.DevMessage != "" {
		return fmt.Sprintf("[%s:%s] %s (Dev: %s)", e.Category, e.Code, e.UserMessage, e.DevMessage)
	}
	return fmt.Sprintf("[%s:%s] %s", e.Category, e.Code, e.UserMessage)
}

// Unwrap は errors.Is と errors.As がカスタムエラータイプで機能できるようにします。
func (e *Error) Unwrap() error {
	return e.Cause
}

// New は新しい構造化エラーを作成します。
func New(category Category, code, userMsg string, opts ...ErrorOption) *Error {
	err := &Error{
		Category:    category,
		Code:        code,
		UserMessage: userMsg,
		Context:     make(map[string]interface{}), // nilマップパニックを避けるためにコンテキストを初期化
	}
	for _, opt := range opts {
		opt(err)
	}
	return err
}

// ErrorOption はエラーをカスタマイズするための機能オプションを定義します。
type ErrorOption func(*Error)

// WithDevMessage は開発者メッセージを設定します。
func WithDevMessage(msg string) ErrorOption {
	return func(e *Error) {
		e.DevMessage = msg
	}
}

// WithContext はエラーコンテキストにキーと値のペアを追加します。
func WithContext(key string, value interface{}) ErrorOption {
	return func(e *Error) {
		e.Context[key] = value
	}
}

// WithCause は基になる原因を設定します。
func WithCause(cause error) ErrorOption {
	return func(e *Error) {
		e.Cause = cause
	}
}

// MapCategoryToHTTPStatus はエラーカテゴリを標準のHTTPステータスコードにマッピングします。
func MapCategoryToHTTPStatus(cat Category) int {
	switch cat {
	case CategoryBadRequest:
		return http.StatusBadRequest
	case CategoryUnauthorized:
		return http.StatusUnauthorized
	case CategoryForbidden:
		return http.StatusForbidden
	case CategoryNotFound:
		return http.StatusNotFound
	case CategoryConflict:
		return http.StatusConflict
	case CategoryServiceUnavailable:
		return http.StatusServiceUnavailable
	case CategoryInternal:
		return http.StatusInternalServerError
	default:
		return http.StatusInternalServerError // 未処理のカテゴリには内部サーバーエラーとしてデフォルト
	}
}

このError構造体はerrorインターフェースを実装しており、標準のGoerrorが期待される場所であればどこでも使用できます。Unwrapメソッドは、Goのerrorsパッケージ関数（errors.Is、errors.As）との互換性のために重要です。また、エラーを簡潔に構築するための機能オプションも提供します。

アプリケーションロジックでの使用例

次に、サービスレイヤーでこれを使用する方法を見てみましょう。

package userservice

import (
	"errors"
	"fmt"
	"your_module/apperror" // apperrorパッケージは上記で定義されていると仮定
)

// User はユーザーエンティティを表します。
type User struct {
	ID    string
	Name  string
	Email string
}

// UserRepository はユーザーデータアクセス用のインターフェースを定義します。
type UserRepository interface {
	GetUserByID(id string) (*User, error)
	CreateUser(user *User) error
}

// Service にはユーザー関連のビジネスロジックが用意されています。
type Service struct {
	repo UserRepository
}

func NewService(repo UserRepository) *Service {
	return &Service{repo: repo}
}

// GetUser IDでユーザーを取得します。
func (s *Service) GetUser(id string) (*User, error) {
	user, err := s.repo.GetUserByID(id)
	if err != nil {
		if errors.Is(err, apperror.New(apperror.CategoryNotFound, "USER_NOT_FOUND", "User not found")) {
			// このチェックは単純化されています。理想的には、リポジトリが構造化されたエラーを返すべきです。
			// デモンストレーションのために、リポジトリが現在のところ汎用エラーを返すと仮定します。
		}

		// 例：リポジトリが「見つかりません」という汎用エラーを返すと仮定します
		if err.Error() == "sql: no rows in result set" { // または、基になるドライバからの他の特定のエラー
			return nil, apperror.New(
				apperror.CategoryNotFound,
				"USER_NOT_FOUND",
				"要求されたユーザーが見つかりませんでした。",
				apperror.WithDevMessage(fmt.Sprintf("ID %s のユーザーはデータベースに存在しません。", id)),
				apperror.WithContext("userID", id),
				apperror.WithCause(err), // 基になるデータベースエラーをラップ
			)
		}

		// その他の予期しないリポジトリエラーの場合
		return nil, apperror.New(
			apperror.CategoryInternal,
			"DB_OPERATION_FAILED",
			"ユーザーデータの取得中に予期しないエラーが発生しました。",
			apperror.WithDevMessage(fmt.Sprintf("データベースからID %s のユーザーを取得できませんでした。", id)),
			apperror.WithContext("operation", "GetUserByID"),
			apperror.WithCause(err),
		)
	}
	return user, nil
}

// CreateUser 新しいユーザーを作成します。
func (s *Service) CreateUser(user *User) error {
	if user.Name == "" || user.Email == "" {
		return apperror.New(
			apperror.CategoryBadRequest,
			"INVALID_USER_DATA",
			"ユーザー名とメールアドレスは必須です。",
			apperror.WithContext("input", user),
		)
	}

	err := s.repo.CreateUser(user)
	if err != nil {
		// 例：データベースからのユニーク制約違反を想定
		if errors.Is(err, apperror.New(apperror.CategoryConflict, "DUPLICATE_EMAIL", "Email already in use")) {
			// 再び、このチェックは単純化されたものです。理想的には、リポジトリが構造化されたエラーを返すべきです。
		}

		if err.Error() == "pq: duplicate key value violates unique constraint \"users_email_key\"" {
			return apperror.New(
				apperror.CategoryConflict,
				"DUPLICATE_EMAIL",
				"提供されたメールアドレスはすでに登録されています。",
				apperror.WithDevMessage(fmt.Sprintf("メールアドレス '%s' はすでに存在します。", user.Email)),
				apperror.WithContext("email", user.Email),
				apperror.WithCause(err),
			)
		}

		return apperror.New(
			apperror.CategoryInternal,
			"DB_INSERT_FAILED",
			"ユーザー作成中に予期しないエラーが発生しました。",
			apperror.WithDevMessage(fmt.Sprintf("データベースへのユーザー '%s' の挿入に失敗しました。", user.Email)),
			apperror.WithCause(err),
		)
	}
	return nil
}

APIレスポンスハンドリング

HTTPハンドラーは、これらの構造化されたエラーを受け取り、適切なAPIレスポンスに変換します。

package httpapi

import (
	"encoding/json"
	"net/http"
	"your_module/apperror" // apperrorパッケージを想定
	"your_module/userservice" // userserviceパッケージを想定
)

// ErrorResponse はAPIエラーレスポンスの構造を定義します。
type ErrorResponse struct {
	Code        string                 `json:"code"`
	Category    apperror.Category      `json:"category"`
	Message     string                 `json:"message"`
	Details     map[string]interface{} `json:"details,omitempty"` // クライアント向けのContextから名称変更
}

// UserHandler はユーザー関連のHTTPリクエストを処理します。
type UserHandler struct {
	service *userservice.Service
}

func NewUserHandler(service *userservice.Service) *UserHandler {
	return &UserHandler{service: service}
}

func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
	userID := r.URL.Query().Get("id")
	if userID == "" {
		h.writeError(w, apperror.New(
			apperror.CategoryBadRequest,
			"MISSING_USER_ID",
			"ユーザーIDが必要です。",
			apperror.WithContext("param", "id"),
		))
		return
	}

	user, err := h.service.GetUser(userID)
	if err != nil {
		h.writeError(w, err)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(user)
}

func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
	var newUser userservice.User
	if err := json.NewDecoder(r.Body).Decode(&newUser); err != nil {
		h.writeError(w, apperror.New(
			apperror.CategoryBadRequest,
			"INVALID_JSON_BODY",
			"リクエストボディが無効なJSONです。",
			apperror.WithCause(err),
		))
		return
	}

	err := h.service.CreateUser(&newUser)
	if err != nil {
		h.writeError(w, err)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	json.NewEncoder(w).Encode(newUser) // または成功メッセージ
}

func (h *UserHandler) writeError(w http.ResponseWriter, err error) {
	var appErr *apperror.Error
	if !errors.As(err, &appErr) {
		// これは予期しない、構造化されていないエラーです。徹底的にログに記録してください。
		// APIレスポンスについては、汎用内部サーバーエラーを返します。
		appErr = apperror.New(
			apperror.CategoryInternal,
			"UNEXPECTED_ERROR",
			"予期しない内部エラーが発生しました。",
			apperror.WithDevMessage(err.Error()), // 開発者向けに元のメッセージをキャプチャ
			apperror.WithCause(err),
		)
	}

	logError(appErr) // 中央集権的なロギング機能

	httpStatus := apperror.MapCategoryToHTTPStatus(appErr.Category)

	resp := ErrorResponse{
		Code:     appErr.Code,
		Category: appErr.Category,
		Message:  appErr.UserMessage,
		Details:  appErr.Context, // クライアント表示のためのDetailsとしてContextを使用
	}

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(httpStatus)
	json.NewEncoder(w).Encode(resp)
}

構造化ロギング

ロギングについては、apperror.Error構造体に埋め込まれたリッチなコンテキストを活用できます。

package httpapi // または専用のロギングパッケージ

import (
	"log/slog" // Go 1.21+ 構造化ロギング
	"your_module/apperror"
)

// カスタムロガー、おそらくslogをラップしたもの。
// これは単純化された例です。実際のロガーはより設定可能になります。
var logger = slog.Default()

// logError は構造化されたアプリケーションエラーをロギングのために処理します。
func logError(err error) {
	var appErr *apperror.Error
	if !errors.As(err, &appErr) {
		// 真に予期しない、構造化されていないエラーをログに記録する
		logger.Error("Unhandled error encountered", "error", err)
		return
	}

	logAttrs := []slog.Attr{
		slog.String("error_code", appErr.Code),
		slog.String("error_category", string(appErr.Category)),
		slog.String("user_message", appErr.UserMessage),
	}

	if appErr.DevMessage != "" {
		logAttrs = append(logAttrs, slog.String("developer_message", appErr.DevMessage))
	}

	// コンテキストフィールドを追加
	for k, v := range appErr.Context {
		logAttrs = append(logAttrs, slog.Any(k, v))
	}

	// 基になる原因が存在する場合はログに記録
	if appErr.Cause != nil {
		logAttrs = append(logAttrs, slog.Any("cause", appErr.Cause.Error())) // 原因のメッセージをログに記録
	}

	// エラーカテゴリに基づいてログレベルを決定
	logLevel := slog.LevelError
	if appErr.Category == apperror.CategoryBadRequest || appErr.Category == apperror.CategoryNotFound || appErr.Category == apperror.CategoryConflict {
		// クライアント側のエラーは、ポリシーに応じてInfoまたはWarnとしてログに記録される場合があります
		logLevel = slog.LevelWarn
	}

	logger.LogAttrs(r.Context(), logLevel, "Application error", logAttrs...)
}

このロギング機能により、構造化されたエラーのすべての関連詳細がログにキーと値のペアとしてキャプチャされ、ELKスタック、Splunk、またはクラウドロギングサービスのようなツールを使用してエラーをフィルタリング、検索、分析することが容易になります。クライアント側のエラーは WARNING レベルでログに記録される可能性があり、サーバー側のエラーは通常 ERROR レベルに値し、より明確な運用上の洞察を提供します。

このアプローチの利点

  1. 一貫性: API全体のエラーは均一な構造を持ち、クライアント側のエラー解析と処理を簡素化します。
  2. 明瞭性: ユーザーと開発者向けのメッセージが分かれているため、両方の受信者が適切な情報を受け取ることが保証されます。
  3. 追跡可能性: エラーコードとカテゴリにより、迅速な識別が可能になります。Contextにより、特定のインスタンスのデバッグがはるかに容易になります。
  4. 観測可能性: 構造化されたログは機械で解析可能であり、エラー傾向の監視、アラート、分析を改善します。
  5. 保守性: 新しいエラータイプを追加し、それらを分類し、エラーレスポンスを一元管理するのが容易になります。
  6. 分離: 内部エラー表現は外部HTTPステータスコードから独立しており、柔軟なマッピングを可能にします。

結論

適切に設計されたエラーハンドリングシステムは、堅牢で保守性の高いGo APIアプリケーションを構築するために不可欠です。カスタム構造化エラータイプにエラー詳細をカプセル化することにより、一貫したAPIレスポンス、詳細で機械可読なログ、および大幅に改善された開発者エクスペリエンスを達成できます。このアプローチは、エラーハンドリングを単なる必要性から、アプリケーションの信頼性と観測可能性のための強力なツールへと変えます。構造化エラーシステムにより、問題が発生したときに、混乱ではなく明瞭さが得られます。

Share this article

HackerNews

More Posts from Leapcell

cover

gRPCとRESTを自動で連携させるgRPC-Gateway

cover

Goose対GORMマイグレーション - Goプロジェクトに最適なデータベースマイグレーションツールの選択

Popular Posts