Goで本格的なRESTful API作成ガイド【2025最新版】

Contents

1 1️⃣ RESTful API の基本概念と設計原則
2 2️⃣ Go 開発環境のセットアップ
- 2.1 📌 ポイント
- 2.2 🛠️ 手順
3 3️⃣ 標準ライブラリ vs 主流フレームワーク比較と選定基準
4 4️⃣ 実務で必要な機能実装
- 4.1 📌 ポイント
- 4.2 🧩 コード例（Gin + Go 1.20）
5 5️⃣ テスト・ドキュメント自動生成・CI/CD デプロイフロー
6 6️⃣ セキュリティ・スケーラビリティのベストプラクティス
7 🎯 記事まとめ
- 7.1 参考リンク

スポンサードリンク

1️⃣ RESTful API の基本概念と設計原則

📌 ポイント

リソース を URL にマッピングし、HTTP メソッドで操作を統一する。
ステートレス な通信とキャッシュ可能なエンドポイントを意識すると、拡張性・保守性が格段に向上する。

📖 背景（Reason）

リソース指向にすることで、クライアント側は「何を取得／作成／更新したいか」だけを宣言すればよくなり、サーバーはその意図に合わせて適切なステータスコードやヘッダーを返すだけで済む。

📚 具体例（Example）

操作	HTTP メソッド	推奨ステータスコード	典型的エンドポイント
一覧取得	`GET`	`200 OK`	`/users`
単体取得	`GET`	`200 OK` / `404 Not Found`	`/users/{id}`
作成	`POST`	`201 Created`	`/users`
完全置換更新	`PUT`	`200 OK` / `204 No Content`	`/users/{id}`
部分更新	`PATCH`	`200 OK`	`/users/{id}`
削除	`DELETE`	`204 No Content`	`/users/{id}`

※ 補足
ステータスコードはあくまで「推奨」ですが、クライアントが期待通りに動作するように統一しておくと API の利用体験が向上します。

2️⃣ Go 開発環境のセットアップ

📌 ポイント

Go 1.20+（2024‑04 時点で最新の安定版）を前提に、モジュール管理は go.mod に一任。
Docker のマルチステージビルドでローカルと本番環境の差異を最小化し、CI/CD と相性の良い再現可能な開発基盤を構築。

🛠️ 手順

2‑1. プロジェクト初期化

mkdir myapi &amp;&amp; cd myapi
go mod init github.com/yourname/myapi

mkdir myapi && cd myapi

go mod init github.com/yourname/myapi

2‑2. 必要パッケージの取得（例示）

# Web フレームワーク &amp; バリデータ &amp; Swagger ツール
go get -u github.com/gin-gonic/gin
go get -u github.com/go-playground/validator/v10
go get -u github.com/swaggo/swag/cmd/swag

# Web フレームワーク & バリデータ & Swagger ツール

go get -u github.com/gin-gonic/gin

go get -u github.com/go-playground/validator/v10

go get -u github.com/swaggo/swag/cmd/swag

2‑3. エディタ・コード品質ツール

ツール	用途
VSCode Go 拡張 (`golang.go`)	補完、インラインドキュメント、デバッグ
gopls	静的解析・リファクタリング
golangci-lint	複数リンターの統合実行

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

1 2	go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

2‑4. Docker によるローカル開発環境

Dockerfile（マルチステージビルド）

# ---------- Build stage ----------
FROM golang:1.20-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags=&quot;-s -w&quot; -o /app/server ./cmd/server

# ---------- Runtime stage ----------
FROM alpine:3.18
WORKDIR /app
COPY --from=builder /app/server .
EXPOSE 8080
ENTRYPOINT [&quot;./server&quot;]

# ---------- Build stage ----------

FROM golang:1.20-alpine AS builder

WORKDIR /src

COPY go.mod go.sum ./

RUN go mod download

COPY . .

RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server ./cmd/server

# ---------- Runtime stage ----------

FROM alpine:3.18

WORKDIR /app

COPY --from=builder /app/server .

EXPOSE 8080

ENTRYPOINT ["./server"]

# docker‑compose.yml（ローカルデバッグ用）
version: &quot;3.8&quot;
services:
  api:
    build: .
    ports:
      - &quot;8080:8080&quot;
    environment:
      GIN_MODE: debug   # 開発時は debug、リリース時は release に切り替える

# docker‑compose.yml（ローカルデバッグ用）

version: "3.8"

services:

api:

build: .

ports:

- "8080:8080"

environment:

GIN_MODE: debug # 開発時は debug、リリース時は release に切り替える

実行
bash docker compose up --build

3️⃣ 標準ライブラリ vs 主流フレームワーク比較と選定基準

📌 ポイント

net/http は学習コストが最も低く、外部依存を排除できる。
Gin / Echo / Fiber は 高速ルーティング と ミドルウェアエコシステム が充実しているため、開発速度と保守性が向上する。

📊 ベンチマーク情報（2024‑03 実測）

フレームワーク	1 秒あたりのリクエスト数 (RPS)	平均応答時間 (ms)	ソース
net/http	13,200	7.5	https://github.com/golang/go/wiki/Performance
Gin	23,400 → 1.77× net/http	4.2	https://github.com/gin-gonic/gin#benchmark
Echo	22,800 → 1.73× net/http	4.5	https://echo.labstack.com/guide#performance
Fiber (fasthttp)	28,500 → 2.16× net/http	3.8	https://github.com/gofiber/fiber#benchmark

※ 注意点
ベンチマークはシンプルな「Hello World」ハンドラで測定したもので、実際のアプリケーションでは DB アクセスやミドルウェアの有無により差が縮小・拡大します。導入時は自プロジェクトで 同条件ベンチマーク を走らせることを推奨します。

📚 フレームワーク比較表

項目	net/http	Gin	Echo	Fiber (Go 1.20)
学習コスト	★☆☆	★★☆（公式サンプルが豊富）	★★☆（シンプル API）	★★★（fasthttp 上で高速）
パフォーマンス	中	高（ベンチマークで約 1.8 倍速）	高（同等だがミドルウェアがやや重い）	非常に高（fasthttp 基盤）
ミドルウェア数	乏しい	豊富（logging, CORS, JWT 等）	標準的	増加中
エラーハンドリング	手動実装	コンテキストベースで統一可能	カスタムハンドラがシンプル	同様にシンプル
ドキュメント生成	外部ツール必要	`swaggo` と相性良好	`echo-swagger` が利用可	`fiber-swagger`

📌 選定指針

要件	推奨フレームワーク
最高性能（数十万 RPS）	Fiber
開発スピードとプラグイン豊富さ	Gin
シンプルで成熟した API	Echo
外部依存を極力排除した軽量サービス	net/http

4️⃣ 実務で必要な機能実装

（バインディング・バリデーション・ミドルウェア・エラーハンドリング）

📌 ポイント

構造体への JSON バインド と validator による入力チェックは、ハンドラ冒頭で一括処理する。
共通ミドルウェア（ロギング・CORS・JWT・レートリミット）はフレームワークのコンテキストに依存し、エラーは即座に JSON 形式で返す。
統一レスポンス型 を定義しておけば、全ハンドラが同じフォーマットで応答できる。

🧩 コード例（Gin + Go 1.20）

4‑1. 統一レスポンス構造体

// APIResponse はすべてのエンドポイントが返す共通型です。
type APIResponse struct {
    Code    int         `json:&quot;code&quot;`               // アプリケーション固有コード（0 が成功）
    Message string      `json:&quot;message&quot;`            // 人間が読むメッセージ
    Data    interface{} `json:&quot;data,omitempty&quot;`     // 任意のペイロード
}

// APIResponse はすべてのエンドポイントが返す共通型です。

type APIResponse struct {

Code int `json:"code"` // アプリケーション固有コード（0 が成功）

Message string `json:"message"` // 人間が読むメッセージ

Data interface{} `json:"data,omitempty"` // 任意のペイロード

}

4‑2. バリデーション対象リクエスト

type CreateUserReq struct {
    Name  string `json:&quot;name&quot; binding:&quot;required,min=2,max=50&quot;`
    Email string `json:&quot;email&quot; binding:&quot;required,email&quot;`
}

type CreateUserReq struct {

Name string `json:"name" binding:"required,min=2,max=50"`

Email string `json:"email" binding:"required,email"`

}

4‑3. ハンドラ実装（バインド＋バリデーション＋コンテキスト活用）

func createUser(c *gin.Context) {
    // ① リクエストボディを構造体へバインド
    var req CreateUserReq
    if err := c.ShouldBindJSON(&amp;req); err != nil {
        // バリデーションエラーは validator.ValidationErrors にキャスト可能
        var ve validator.ValidationErrors
        if errors.As(err, &amp;ve) {
            msgs := make([]string, len(ve))
            for i, fe := range ve {
                msgs[i] = fmt.Sprintf(&quot;%s: %s&quot;, fe.Field(), fe.Tag())
            }
            c.JSON(http.StatusBadRequest,
                APIResponse{Code: 4001, Message: strings.Join(msgs, &quot;, &quot;), Data: nil})
        } else {
            c.JSON(http.StatusBadRequest,
                APIResponse{Code: 4000, Message: err.Error(), Data: nil})
        }
        return
    }

    // ② DB 操作はコンテキストでタイムアウト制御（例：5 秒）
    ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second)
    defer cancel()
    if err := repo.CreateUser(ctx, req.Name, req.Email); err != nil {
        c.JSON(http.StatusInternalServerError,
            APIResponse{Code: 5001, Message: &quot;failed to store user&quot;, Data: nil})
        return
    }

    // ③ 正常レスポンス
    c.JSON(http.StatusCreated,
        APIResponse{Code: 0, Message: &quot;user created&quot;, Data: req})
}

func createUser(c *gin.Context) {

// ① リクエストボディを構造体へバインド

var req CreateUserReq

if err := c.ShouldBindJSON(&req); err != nil {

// バリデーションエラーは validator.ValidationErrors にキャスト可能

var ve validator.ValidationErrors

if errors.As(err, &ve) {

msgs := make([]string, len(ve))

for i, fe := range ve {

msgs[i] = fmt.Sprintf("%s: %s", fe.Field(), fe.Tag())

}

c.JSON(http.StatusBadRequest,

APIResponse{Code: 4001, Message: strings.Join(msgs, ", "), Data: nil})

} else {

c.JSON(http.StatusBadRequest,

APIResponse{Code: 4000, Message: err.Error(), Data: nil})

}

return

}

// ② DB 操作はコンテキストでタイムアウト制御（例：5 秒）

ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second)

defer cancel()

if err := repo.CreateUser(ctx, req.Name, req.Email); err != nil {

c.JSON(http.StatusInternalServerError,

APIResponse{Code: 5001, Message: "failed to store user", Data: nil})

return

}

// ③ 正常レスポンス

c.JSON(http.StatusCreated,

APIResponse{Code: 0, Message: "user created", Data: req})

}

4‑4. ロギングミドルウェア（Zap + Gin コンテキスト）

func Logger() gin.HandlerFunc {
    logger, _ := zap.NewProduction()
    return func(c *gin.Context) {
        start := time.Now()
        c.Next() // 後続ハンドラを実行

        latency := time.Since(start)
        logger.Info(&quot;request&quot;,
            zap.String(&quot;method&quot;, c.Request.Method),
            zap.String(&quot;path&quot;, c.FullPath()),
            zap.Int(&quot;status&quot;, c.Writer.Status()),
            zap.Duration(&quot;latency&quot;, latency),
            zap.String(&quot;client_ip&quot;, c.ClientIP()))
    }
}

func Logger() gin.HandlerFunc {

logger, _ := zap.NewProduction()

return func(c *gin.Context) {

start := time.Now()

c.Next() // 後続ハンドラを実行

latency := time.Since(start)

logger.Info("request",

zap.String("method", c.Request.Method),

zap.String("path", c.FullPath()),

zap.Int("status", c.Writer.Status()),

zap.Duration("latency", latency),

zap.String("client_ip", c.ClientIP()))

}

4‑5. CORS ミドルウェア（公式パッケージ）

import &quot;github.com/gin-contrib/cors&quot;

func setupCORS(r *gin.Engine) {
    r.Use(cors.New(cors.Config{
        AllowOrigins:     []string{&quot;https://example.com&quot;},
        AllowMethods:     []string{&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;, &quot;PATCH&quot;, &quot;DELETE&quot;},
        AllowHeaders:     []string{&quot;Origin&quot;, &quot;Authorization&quot;, &quot;Content-Type&quot;},
        ExposeHeaders:    []string{&quot;Content-Length&quot;},
        AllowCredentials: true,
        MaxAge:           12 * time.Hour,
    }))
}

import "github.com/gin-contrib/cors"

func setupCORS(r *gin.Engine) {

r.Use(cors.New(cors.Config{

AllowOrigins: []string{"https://example.com"},

AllowMethods: []string{"GET", "POST", "PUT", "PATCH", "DELETE"},

AllowHeaders: []string{"Origin", "Authorization", "Content-Type"},

ExposeHeaders: []string{"Content-Length"},

AllowCredentials: true,

MaxAge: 12 * time.Hour,

}))

}

4‑6. JWT 認証ミドルウェア（golang-jwt/v5）

func JWTAuth() gin.HandlerFunc {
    secret := []byte(os.Getenv(&quot;JWT_SECRET&quot;))
    return func(c *gin.Context) {
        tokenStr := strings.TrimPrefix(c.GetHeader(&quot;Authorization&quot;), &quot;Bearer &quot;)
        if tokenStr == &quot;&quot; {
            c.AbortWithStatusJSON(http.StatusUnauthorized,
                APIResponse{Code: 4010, Message: &quot;missing token&quot;, Data: nil})
            return
        }

        token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (any, error) {
            if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
                return nil, fmt.Errorf(&quot;unexpected signing method&quot;)
            }
            return secret, nil
        })
        if err != nil || !token.Valid {
            c.AbortWithStatusJSON(http.StatusUnauthorized,
                APIResponse{Code: 4011, Message: &quot;invalid token&quot;, Data: nil})
            return
        }

        // トークンからユーザー情報を取得したい場合はここでコンテキストに格納
        claims := token.Claims.(jwt.MapClaims)
        c.Set(&quot;userID&quot;, claims[&quot;sub&quot;])
        c.Next()
    }
}

func JWTAuth() gin.HandlerFunc {

secret := []byte(os.Getenv("JWT_SECRET"))

return func(c *gin.Context) {

tokenStr := strings.TrimPrefix(c.GetHeader("Authorization"), "Bearer ")

if tokenStr == "" {

c.AbortWithStatusJSON(http.StatusUnauthorized,

APIResponse{Code: 4010, Message: "missing token", Data: nil})

return

}

token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (any, error) {

if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {

return nil, fmt.Errorf("unexpected signing method")

}

return secret, nil

})

if err != nil || !token.Valid {

c.AbortWithStatusJSON(http.StatusUnauthorized,

APIResponse{Code: 4011, Message: "invalid token", Data: nil})

return

}

// トークンからユーザー情報を取得したい場合はここでコンテキストに格納

claims := token.Claims.(jwt.MapClaims)

c.Set("userID", claims["sub"])

c.Next()

}

4‑7. レートリミット（golang.org/x/time/rate）

※ IP 単位のシンプル実装例です。実運用では分散レートリミッター（Redis 等）を検討してください。

var limiter = rate.NewLimiter(5, 10) // 1 秒あたり 5 リクエスト、バースト 10

func RateLimit() gin.HandlerFunc {
    return func(c *gin.Context) {
        if !limiter.Allow() {
            c.AbortWithStatusJSON(http.StatusTooManyRequests,
                APIResponse{Code: 4290, Message: &quot;rate limit exceeded&quot;, Data: nil})
            return
        }
        c.Next()
    }
}

var limiter = rate.NewLimiter(5, 10) // 1 秒あたり 5 リクエスト、バースト 10

func RateLimit() gin.HandlerFunc {

return func(c *gin.Context) {

if !limiter.Allow() {

c.AbortWithStatusJSON(http.StatusTooManyRequests,

APIResponse{Code: 4290, Message: "rate limit exceeded", Data: nil})

return

}

c.Next()

}

4‑8. パニックリカバリ（全ハンドラで共通）

func Recover() gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if r := recover(); r != nil {
                // 本番環境では Sentry 等へ送信するのが望ましい
                c.JSON(http.StatusInternalServerError,
                    APIResponse{Code: 5000, Message: &quot;internal server error&quot;, Data: nil})
                c.Abort()
            }
        }()
        c.Next()
    }
}

func Recover() gin.HandlerFunc {

return func(c *gin.Context) {

defer func() {

if r := recover(); r != nil {

// 本番環境では Sentry 等へ送信するのが望ましい

c.JSON(http.StatusInternalServerError,

APIResponse{Code: 5000, Message: "internal server error", Data: nil})

c.Abort()

}

}()

c.Next()

}

4‑9. ルーティング全体例

func main() {
    r := gin.New()

    // グローバルミドルウェア設定
    r.Use(Recover(), Logger(), RateLimit())
    setupCORS(r)

    // 認証が必要なエンドポイントは JWTAuth を付与
    auth := r.Group(&quot;/&quot;, JWTAuth())
    {
        auth.POST(&quot;/users&quot;, createUser)
        // 例: GET /users/:id, PUT /users/:id ...
    }

    // 公開エンドポイント（認証不要）
    r.GET(&quot;/healthz&quot;, func(c *gin.Context) {
        c.JSON(http.StatusOK,
            APIResponse{Code: 0, Message: &quot;ok&quot;})
    })

    // Swagger UI （開発モードのみ公開例）
    if gin.Mode() != gin.ReleaseMode {
        r.GET(&quot;/swagger/*any&quot;, ginSwagger.WrapHandler(files.Handler))
    }

    srv := &amp;http.Server{
        Addr:         &quot;:8080&quot;,
        Handler:      r,
        ReadTimeout:  10 * time.Second,
        WriteTimeout: 15 * time.Second,
        IdleTimeout:  60 * time.Second,
    }
    log.Println(&quot;&#x1f680; API server listening on :8080&quot;)
    if err := srv.ListenAndServe(); err != nil &amp;&amp; err != http.ErrServerClosed {
        log.Fatalf(&quot;server error: %v&quot;, err)
    }
}

func main() {

r := gin.New()

// グローバルミドルウェア設定

r.Use(Recover(), Logger(), RateLimit())

setupCORS(r)

// 認証が必要なエンドポイントは JWTAuth を付与

auth := r.Group("/", JWTAuth())

{

auth.POST("/users", createUser)

// 例: GET /users/:id, PUT /users/:id ...

}

// 公開エンドポイント（認証不要）

r.GET("/healthz", func(c *gin.Context) {

c.JSON(http.StatusOK,

APIResponse{Code: 0, Message: "ok"})

})

// Swagger UI （開発モードのみ公開例）

if gin.Mode() != gin.ReleaseMode {

r.GET("/swagger/*any", ginSwagger.WrapHandler(files.Handler))

}

srv := &http.Server{

Addr: ":8080",

Handler: r,

ReadTimeout: 10 * time.Second,

WriteTimeout: 15 * time.Second,

IdleTimeout: 60 * time.Second,

}

log.Println("🚀 API server listening on :8080")

if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {

log.Fatalf("server error: %v", err)

}

5️⃣ テスト・ドキュメント自動生成・CI/CD デプロイフロー

📌 ポイント

単体テストは httptest とモックインターフェースで実装。
Swagger (OpenAPI) は swaggo/swag がコードコメントから自動生成。
GitHub Actions で lint、テスト、ビルドを走らせ、Docker イメージをレジストリへプッシュ。

🧪 テスト例

5‑1. ハンドラ単体テスト（Gin + httptest）

func TestCreateUser_Success(t *testing.T) {
    // 準備：モックリポジトリを注入（省略）
    r := gin.New()
    r.POST(&quot;/users&quot;, createUser)

    payload := `{&quot;name&quot;:&quot;Alice&quot;,&quot;email&quot;:&quot;alice@example.com&quot;}`
    req, _ := http.NewRequest(http.MethodPost, &quot;/users&quot;, strings.NewReader(payload))
    req.Header.Set(&quot;Content-Type&quot;, &quot;application/json&quot;)
    w := httptest.NewRecorder()

    r.ServeHTTP(w, req)

    if w.Code != http.StatusCreated {
        t.Fatalf(&quot;expected 201, got %d&quot;, w.Code)
    }

    var resp APIResponse
    if err := json.Unmarshal(w.Body.Bytes(), &amp;resp); err != nil {
        t.Fatalf(&quot;invalid JSON: %v&quot;, err)
    }
    if resp.Code != 0 {
        t.Errorf(&quot;unexpected app code: %d, msg=%s&quot;, resp.Code, resp.Message)
    }
}

func TestCreateUser_Success(t *testing.T) {

// 準備：モックリポジトリを注入（省略）

r := gin.New()

r.POST("/users", createUser)

payload := `{"name":"Alice","email":"alice@example.com"}`

req, _ := http.NewRequest(http.MethodPost, "/users", strings.NewReader(payload))

req.Header.Set("Content-Type", "application/json")

w := httptest.NewRecorder()

r.ServeHTTP(w, req)

if w.Code != http.StatusCreated {

t.Fatalf("expected 201, got %d", w.Code)

}

var resp APIResponse

if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {

t.Fatalf("invalid JSON: %v", err)

}

if resp.Code != 0 {

t.Errorf("unexpected app code: %d, msg=%s", resp.Code, resp.Message)

}

5‑2. DB リポジトリインターフェースと Gomock

type UserRepository interface {
    CreateUser(ctx context.Context, name, email string) error
}

// gomock の生成例（テストディレクトリ内）
// $ mockgen -source=repo.go -destination=mocks/mock_repo_test.go -package=mocks

type UserRepository interface {

CreateUser(ctx context.Context, name, email string) error

}

// gomock の生成例（テストディレクトリ内）

// $ mockgen -source=repo.go -destination=mocks/mock_repo_test.go -package=mocks

📚 Swagger 自動生成手順

インストール
bash go install github.com/swaggo/swag/cmd/swag@latest
ハンドラにコメント注釈（例：createUser）
go // @Summary Create a new user // @Description Register a user with name and email // @Tags users // @Accept json // @Produce json // @Param body body CreateUserReq true "User data" // @Success 201 {object} APIResponse{data=CreateUserReq} // @Failure 400 {object} APIResponse // @Router /users [post]
生成
bash swag init -g cmd/server/main.go -o docs
Gin へ組み込み（上記コード参照）

🚀 CI/CD パイプライン例（GitHub Actions）

name: Go CI

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.20'

      - name: Cache modules
        uses: actions/cache@v3
        with:
          path: |
            ~/.cache/go-build
            ~/go/pkg/mod
          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-go-

      - name: Install tools
        run: |
          go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
          go install github.com/swaggo/swag/cmd/swag@latest

      - name: Lint
        run: golangci-lint run ./...

      - name: Generate Swagger docs
        run: swag init -g cmd/server/main.go -o docs

      - name: Test
        env:
          GOFLAGS: &quot;-mod=readonly&quot;
        run: go test ./... -v -coverprofile=coverage.out

      - name: Build Docker image
        run: |
          docker build -t ghcr.io/${{ github.repository_owner }}/myapi:${{ github.sha }} .
          echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker push ghcr.io/${{ github.repository_owner }}/myapi:${{ github.sha }}

      - name: Upload coverage report
        uses: actions/upload-artifact@v3
        with:
          name: coverage-report
          path: coverage.out

name: Go CI

on:

push:

branches: [ main ]

pull_request:

jobs:

build-test:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v3

- name: Set up Go

uses: actions/setup-go@v4

with:

go-version: '1.20'

- name: Cache modules

uses: actions/cache@v3

with:

path: |

~/.cache/go-build

~/go/pkg/mod

key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

restore-keys: |

${{ runner.os }}-go-

- name: Install tools

run: |

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

go install github.com/swaggo/swag/cmd/swag@latest

- name: Lint

run: golangci-lint run ./...

- name: Generate Swagger docs

run: swag init -g cmd/server/main.go -o docs

- name: Test

env:

GOFLAGS: "-mod=readonly"

run: go test ./... -v -coverprofile=coverage.out

- name: Build Docker image

run: |

docker build -t ghcr.io/${{ github.repository_owner }}/myapi:${{ github.sha }} .

echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin

docker push ghcr.io/${{ github.repository_owner }}/myapi:${{ github.sha }}

- name: Upload coverage report

uses: actions/upload-artifact@v3

with:

name: coverage-report

path: coverage.out

📦 本番デプロイ（Docker Compose + 環境変数）

version: &quot;3.8&quot;
services:
  api:
    image: ghcr.io/yourname/myapi:${IMAGE_TAG}
    ports:
      - &quot;80:8080&quot;
    environment:
      GIN_MODE: release
      JWT_SECRET: ${JWT_SECRET}
    restart: always
    healthcheck:
      test: [&quot;CMD&quot;, &quot;curl&quot;, &quot;-f&quot;, &quot;http://localhost:8080/healthz&quot;]
      interval: 30s
      timeout: 5s
      retries: 3

version: "3.8"

services:

api:

image: ghcr.io/yourname/myapi:${IMAGE_TAG}

ports:

- "80:8080"

environment:

GIN_MODE: release

JWT_SECRET: ${JWT_SECRET}

restart: always

healthcheck:

test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]

interval: 30s

timeout: 5s

retries: 3

デプロイ手順
bash export IMAGE_TAG=$(git rev-parse --short HEAD) docker compose -f docker-compose.prod.yml up -d

6️⃣ セキュリティ・スケーラビリティのベストプラクティス

項目	実装例
HTTP タイムアウト	`http.Server{ReadTimeout:10s, WriteTimeout:15s}`
コンテキスト活用	DB/外部 API 呼び出しは `ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)`
入力サニタイズ	SQL は必ずプレースホルダー、HTML 出力は `html.EscapeString`
ヘッダー強化	ミドルウェアで `Strict-Transport-Security`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: same-origin` を付与
監視・ロギング	Prometheus メトリクス (`github.com/prometheus/client_golang`) と Loki/Grafana へログ集約
レートリミット (分散)	Redis ベースの `go-redis/ratelimit` を導入し、複数インスタンス間で共有

🎯 記事まとめ

RESTful 設計 – リソース指向・ステータスコード遵守が基本。
開発環境 – Go 1.20+、go.mod、Docker マルチステージで再現性確保。
フレームワーク選定 – 標準 net/http と Gin/Echo/Fiber を性能・学習コストで比較し、要件に合わせて選択。ベンチマークは公式リポジトリの数値を参照（※自プロジェクトでも再測定推奨）。
実務機能 – バインディング＋ validator、ロギング・CORS・JWT・レートリミット・パニックリカバリの共通ミドルウェアで堅牢性向上。統一レスポンス型によりクライアント側実装が簡潔になる。
品質保証 – httptest とインターフェースモックで単体テスト、Swagger で API 定義自動生成、GitHub Actions で CI → Docker イメージのビルド・プッシュまでを一貫化。
運用・セキュリティ – タイムアウト・コンテキスト・ヘッダー強化・監視・分散レートリミットで本番環境に耐える設計。

これらの手順とベストプラクティスをプロジェクトに組み込めば、Go 言語だけで 認証・バリデーション・テスト・CI/CD を備えた実務レベルの RESTful API が構築できます。ぜひローカルでサンプルコードを動かし、自分のサービス要件に合わせてカスタマイズしてみてください。

参考リンク

内容	URL
Go 標準ライブラリ性能ページ	https://golang.org/wiki/Performance
Gin ベンチマーク	https://github.com/gin-gonic/gin#benchmark
Echo パフォーマンス比較	https://echo.labstack.com/guide#performance
Fiber ベンチマーク (fasthttp)	https://github.com/gofiber/fiber#benchmark
validator v10 ドキュメント	https://pkg.go.dev/github.com/go-playground/validator/v10
swaggo/swag 公式リポジトリ	https://github.com/swaggo/swag
golangci-lint 公式ページ	https://golangci.github.io/lint/
Prometheus Go client	https://github.com/prometheus/client_golang

本稿は執筆時点（2024 年 4 月）に基づく情報です。Go の新バージョンやライブラリの更新があった場合は、公式ドキュメントで最新情報をご確認ください。

スポンサードリンク

Goで本格的なRESTful API作成ガイド【2025最新版】

1️⃣ RESTful API の基本概念と設計原則

📌 ポイント

📖 背景（Reason）

📚 具体例（Example）

2️⃣ Go 開発環境のセットアップ

📌 ポイント

🛠️ 手順

2‑1. プロジェクト初期化

2‑2. 必要パッケージの取得（例示）

2‑3. エディタ・コード品質ツール

2‑4. Docker によるローカル開発環境

3️⃣ 標準ライブラリ vs 主流フレームワーク比較と選定基準

📌 ポイント

📊 ベンチマーク情報（2024‑03 実測）

📚 フレームワーク比較表

📌 選定指針

4️⃣ 実務で必要な機能実装

📌 ポイント

🧩 コード例（Gin + Go 1.20）

4‑1. 統一レスポンス構造体

4‑2. バリデーション対象リクエスト

4‑3. ハンドラ実装（バインド＋バリデーション＋コンテキスト活用）

4‑4. ロギングミドルウェア（Zap + Gin コンテキスト）

4‑5. CORS ミドルウェア（公式パッケージ）

4‑6. JWT 認証ミドルウェア（golang-jwt/v5）

4‑7. レートリミット（golang.org/x/time/rate）

4‑8. パニックリカバリ（全ハンドラで共通）

4‑9. ルーティング全体例

5️⃣ テスト・ドキュメント自動生成・CI/CD デプロイフロー

📌 ポイント

🧪 テスト例

5‑1. ハンドラ単体テスト（Gin + httptest）

5‑2. DB リポジトリインターフェースと Gomock

📚 Swagger 自動生成手順

🚀 CI/CD パイプライン例（GitHub Actions）

📦 本番デプロイ（Docker Compose + 環境変数）

6️⃣ セキュリティ・スケーラビリティのベストプラクティス

🎯 記事まとめ

参考リンク

🧩 コード例（Gin + Go 1.20）