Go言語でHTTPステータスコードを正しく設定する基本！初心者でもわかるWeb開発

1. Go言語でHTTPステータスコードを返す方法

1. Go言語でHTTPステータスコードを返す方法

Go言語の標準ライブラリにはnet/httpパッケージがあり、http.ResponseWriterを使ってHTTPステータスコードを設定できます。WriteHeaderメソッドでコードを指定し、その後にレスポンス本文を書きます。

package main

import (
    "fmt"
    "net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK) // 200 OK
    fmt.Fprintln(w, "リクエストは成功しました！")
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

この例では、http.StatusOKを使って200ステータスを返しています。WriteHeaderはレスポンス本文より前に呼ぶ必要があります。

2. よく使うHTTPステータスコード一覧

2. よく使うHTTPステータスコード一覧

HTTPステータスコードは大きく5つのカテゴリに分かれます。1xxは情報、2xxは成功、3xxはリダイレクト、4xxはクライアントエラー、5xxはサーバーエラーです。代表的なコードをいくつか紹介します。

• 200 OK：リクエスト成功
• 201 Created：新しいリソースが作成された
• 400 Bad Request：リクエストが不正
• 401 Unauthorized：認証が必要
• 403 Forbidden：アクセス禁止
• 404 Not Found：ページが見つからない
• 500 Internal Server Error：サーバー内部エラー

Go言語では、これらのコードに対応する定数がhttp.StatusOKやhttp.StatusNotFoundなどとして用意されており、数字を直接書くより可読性が高くなります。

3. ステータスコードによるエラーハンドリング

3. ステータスコードによるエラーハンドリング

クライアントからのリクエストに問題がある場合は、適切なステータスコードを返してエラーを伝えることが重要です。

func errorHandler(w http.ResponseWriter, r *http.Request) {
    path := r.URL.Path
    if path != "/ok" {
        w.WriteHeader(http.StatusNotFound) // 404 Not Found
        fmt.Fprintln(w, "ページが見つかりません")
        return
    }
    w.WriteHeader(http.StatusOK)
    fmt.Fprintln(w, "正常にアクセスできました")
}

この例では、リクエストURLが"/ok"でなければ404を返し、正常なら200を返します。これにより、ブラウザやAPIクライアントに正しい情報を伝えられます。

4. JSONレスポンスとステータスコードの組み合わせ

4. JSONレスポンスとステータスコードの組み合わせ

APIを作る場合、JSONレスポンスとステータスコードを組み合わせることがよくあります。Goではencoding/jsonパッケージを使ってJSONを返すことができます。

import (
    "encoding/json"
)

type Response struct {
    Message string `json:"message"`
}

func jsonHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(Response{Message: "JSONレスポンス成功"})
}

このようにWriteHeaderでステータスコードを設定し、JSON形式でレスポンスを返すことで、クライアントに正しい情報と状態を伝えられます。

5. 注意点とベストプラクティス

5. 注意点とベストプラクティス

• WriteHeaderはレスポンス本文を書く前に必ず呼ぶ
• HTTPステータスコードは意味に沿って正しく設定する（成功は2xx、エラーは4xx/5xxなど）
• API開発では、ステータスコードとレスポンス内容を一貫させる
• 数字より定数（http.StatusOKなど）を使うと可読性が向上

正しいステータスコードの設定は、WebアプリやAPIの信頼性を高め、開発や運用の効率化にも繋がります。

まとめ

まとめ

HTTPステータスコードを理解することの重要性

本記事では、Go言語を使ったWeb開発において欠かせないHTTPステータスコードの基本から、具体的な使い方、実践的な注意点までを段階的に解説してきました。HTTPステータスコードは、単なる数字ではなく、サーバーとクライアントの間で「処理結果を正確に伝えるための共通言語」です。ブラウザやAPIクライアントは、この数値をもとに次の動作を判断するため、正しく設定されていないと、動作不良や誤解を招く原因になります。

Go言語では net/http パッケージが非常に充実しており、http.ResponseWriter と WriteHeader を使うだけで、HTTPステータスコードを明示的に制御できます。特に初心者の方は「レスポンスが表示されているから大丈夫」と考えがちですが、裏側でどのステータスコードが返っているかを意識することで、より品質の高いWebアプリケーションを作れるようになります。

成功と失敗を正しく伝える設計の考え方

記事内で紹介したように、成功時には 200 OK や 201 Created、クライアント側の入力ミスには 400 Bad Request、存在しないページには 404 Not Found、サーバー内部の問題には 500 Internal Server Error を返すなど、用途に応じた使い分けが重要です。これにより、フロントエンド開発者やAPI利用者がレスポンスの意味を直感的に理解できるようになります。

特にJSON APIを開発する場合は、ステータスコードとレスポンスボディの内容をセットで考えることが大切です。ステータスコードで大まかな結果を伝え、JSONの中身で詳細なメッセージやデータを返すことで、実用性の高いAPI設計が可能になります。

ステータスコードとJSONを組み合わせた実践例

type ApiResponse struct {
    Status  string `json:"status"`
    Message string `json:"message"`
}

func sampleHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    if r.Method != "GET" {
        w.WriteHeader(http.StatusMethodNotAllowed)
        json.NewEncoder(w).Encode(ApiResponse{
            Status:  "error",
            Message: "このメソッドは許可されていません",
        })
        return
    }

    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(ApiResponse{
        Status:  "success",
        Message: "正常に処理されました",
    })
}

このように、Go言語ではHTTPステータスコードとJSONレスポンスを自然に組み合わせることができます。ステータスコードだけ、あるいはJSONだけに頼るのではなく、両方を意識することで、クライアントにとって分かりやすく、拡張性の高いWeb APIを構築できます。

初心者が意識しておきたいポイント

初心者のうちは、まず「成功は200」「見つからないは404」「エラーは500」という基本的な使い分けを確実に身につけることが大切です。そのうえで、WriteHeader をレスポンス本文より前に呼ぶ必要がある点や、数値ではなく http.StatusOK のような定数を使う習慣を意識すると、コードの読みやすさと保守性が向上します。

HTTPステータスコードを正しく扱えるようになると、Webアプリケーションの挙動が明確になり、デバッグやトラブルシューティングも格段に楽になります。これは小規模な個人開発だけでなく、チーム開発や実務の現場でも大きな強みになります。