菜单
Gin (Go) バックエンドAPIの包括的な実装ガイド。プロジェクト構造、ルーティング、ミドルウェア、リクエストバインディング、バリデーション、レスポンスパターン、認証/認可ミドルウェア、slogによる構造化ログ、DI（wire/manual）、Goイディオム、環境設定をカバー。GinでのAPI実装、ミドルウェア設計時に使用。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | gin-backend |
| description | Gin (Go) バックエンドAPIの包括的な実装ガイド。プロジェクト構造、ルーティング、ミドルウェア、リクエストバインディング、バリデーション、レスポンスパターン、認証/認可ミドルウェア、slogによる構造化ログ、DI（wire/manual）、Goイディオム、環境設定をカバー。GinでのAPI実装、ミドルウェア設計時に使用。 |
Gin フレームワークを使った Go バックエンド API の実装ガイド。Tier 2（フレームワーク固有）スキル。
1. タスク種別を判定
├─ 新規API実装 → 「プロジェクト構造」→「ルーティング」→「リクエスト/レスポンス」
├─ ミドルウェア追加 → 「ミドルウェア」→「認証/認可」
├─ 横断的関心事 → 「ロギング」→「環境設定」→「DI」
└─ レビュー → 「レビューチェックリスト」へ
project-root/
├── cmd/server/main.go # エントリポイント
├── internal/ # 外部非公開パッケージ
│ ├── handler/ # HTTPハンドラ
│ ├── middleware/ # カスタムミドルウェア
│ ├── service/ # ビジネスロジック
│ ├── repository/ # データアクセス
│ ├── model/ # ドメインモデル
│ ├── dto/ # リクエスト/レスポンス構造体
│ └── config/ # 設定管理
├── pkg/ # 外部公開可能パッケージ
├── go.mod / go.sum
internal/ で可視性を制御、cmd/ にエントリポイント配置func SetupRouter(h *handler.UserHandler, mw *middleware.Auth) *gin.Engine {
r := gin.New()
r.Use(gin.Recovery(), middleware.RequestLogger())
api := r.Group("/api/v1")
{
api.POST("/login", h.Login)
auth := api.Group("", mw.Required())
{
auth.GET("/users/:id", h.GetUser)
auth.PUT("/users/:id", h.UpdateUser)
}
}
return r
}
c.Param("id") / クエリ: c.DefaultQuery("limit", "20")r.Use(gin.Recovery()) // パニックリカバリ
r.Use(gin.Logger()) // リクエストログ（本番ではカスタム推奨）
// カスタムミドルウェアの基本形
func RequestID() gin.HandlerFunc {
return func(c *gin.Context) {
id := c.GetHeader("X-Request-ID")
if id == "" { id = uuid.NewString() }
c.Set("request_id", id)
c.Header("X-Request-ID", id)
c.Next()
}
}
type CreateUserRequest struct {
Name string `json:"name" binding:"required,min=1,max=100"`
Email string `json:"email" binding:"required,email"`
Age int `json:"age" binding:"omitempty,gte=0,lte=150"`
}
func (h *UserHandler) Create(c *gin.Context) {
var req CreateUserRequest
if err := c.ShouldBindJSON(&req); err != nil {
Fail(c, http.StatusBadRequest, "VALIDATION_ERROR", err.Error())
return
}
// ビジネスロジック呼び出し
}
| メソッド | 用途 |
|---|---|
ShouldBindJSON | JSON ボディ |
ShouldBindQuery | クエリパラメータ |
ShouldBindUri | パスパラメータ |
ShouldBind 系を使用（Bind 系はエラー時に自動400を返すため制御しづらい）type Response struct {
Data any `json:"data,omitempty"`
Error *Error `json:"error,omitempty"`
}
type Error struct {
Code string `json:"code"`
Message string `json:"message"`
}
func Success(c *gin.Context, data any) { c.JSON(http.StatusOK, Response{Data: data}) }
func Created(c *gin.Context, data any) { c.JSON(http.StatusCreated, Response{Data: data}) }
func Fail(c *gin.Context, status int, code, msg string) {
c.JSON(status, Response{Error: &Error{Code: code, Message: msg}})
}
func (a *AuthMiddleware) Required() gin.HandlerFunc {
return func(c *gin.Context) {
token := extractBearerToken(c)
if token == "" {
c.AbortWithStatusJSON(http.StatusUnauthorized,
Response{Error: &Error{Code: "UNAUTHORIZED", Message: "token required"}})
return
}
claims, err := validateJWT(token, a.secret)
if err != nil {
c.AbortWithStatusJSON(http.StatusUnauthorized,
Response{Error: &Error{Code: "INVALID_TOKEN", Message: "invalid token"}})
return
}
c.Set("user_id", claims.UserID)
c.Set("role", claims.Role)
c.Next()
}
}
func RequireRole(roles ...string) gin.HandlerFunc {
return func(c *gin.Context) {
role, _ := c.Get("role")
for _, r := range roles {
if role == r { c.Next(); return }
}
c.AbortWithStatusJSON(http.StatusForbidden,
Response{Error: &Error{Code: "FORBIDDEN", Message: "insufficient permissions"}})
}
}
func NewLogger(env string) *slog.Logger {
var h slog.Handler
if env == "production" {
h = slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
} else {
h = slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug})
}
return slog.New(h)
}
func RequestLogger() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
c.Next()
slog.Info("request",
"method", c.Request.Method, "path", c.Request.URL.Path,
"status", c.Writer.Status(), "latency_ms", time.Since(start).Milliseconds(),
"request_id", c.GetString("request_id"))
}
}
// Manual DI（小〜中規模推奨）
func main() {
cfg := config.Load()
db := database.New(cfg.DatabaseURL)
userRepo := repository.NewUserRepository(db)
userSvc := service.NewUserService(userRepo)
userHandler := handler.NewUserHandler(userSvc)
SetupRouter(userHandler).Run(cfg.Port)
}
// Wire DI（大規模推奨）
//go:build wireinject
func InitializeServer() (*gin.Engine, error) {
wire.Build(config.Set, database.Set, repository.Set, service.Set, handler.Set, NewRouter)
return nil, nil
}
// ドメインエラー定義
var (
ErrNotFound = errors.New("not found")
ErrConflict = errors.New("conflict")
)
// ハンドラでのエラーマッピング
func mapError(c *gin.Context, err error) {
switch {
case errors.Is(err, service.ErrNotFound):
Fail(c, http.StatusNotFound, "NOT_FOUND", err.Error())
case errors.Is(err, service.ErrConflict):
Fail(c, http.StatusConflict, "CONFLICT", err.Error())
default:
slog.Error("unexpected error", "error", err)
Fail(c, http.StatusInternalServerError, "INTERNAL", "internal server error")
}
}
// インターフェースは利用側で定義（Go の慣例）
type UserRepository interface {
FindByID(ctx context.Context, id string) (*model.User, error)
Save(ctx context.Context, user *model.User) error
}
gin.Context をゴルーチンに渡す場合は c.Copy() を使うsync.Mutex / sync.RWMutex で共有状態を保護type Config struct {
Port string `mapstructure:"PORT"`
DatabaseURL string `mapstructure:"DATABASE_URL"`
JWTSecret string `mapstructure:"JWT_SECRET"`
Env string `mapstructure:"ENV"`
}
func Load() *Config {
viper.SetConfigFile(".env")
viper.AutomaticEnv()
_ = viper.ReadInConfig()
var cfg Config
if err := viper.Unmarshal(&cfg); err != nil { log.Fatalf("config: %v", err) }
return &cfg
}
viper で環境変数と .env を統合、デフォルト値は viper.SetDefault()ShouldBind 系を使用（Bind 系でない）return している（ミドルウェアでは c.Abort）c.Next() / c.Abort の使い分けが正しいerrors.Is / errors.As を使用slog）使用、機密情報非含有gin.Context 渡しに c.Copy() 使用Generate draw.io diagrams as .drawio files, optionally export to PNG/SVG/PDF with embedded XML
Figma MCP を使ってデザインを FE コードに変換するスキル。 Trigger when: Figma URL が共有された時、デザインからコンポーネント実装時、 UI 実装でデザイン参照が必要な時、"Figma", "デザイン", "UI実装" への言及時、 「このデザインを実装して」「Figma から」「デザイン通りに」と言われた時。 Always use with: /web-design-principles
プロジェクト全体の統括エージェント向けスキル。要件整理から技術選定・アーキテクチャ設計・タスク分解・委譲までをカバー。git worktreeを活用した並列開発オーケストレーション（featureブランチ管理、BE/FE統括への委譲、横断レビュー）も担う。プロジェクト全体を俯瞰し、適切なエージェント/スキルに委譲する。新規プロジェクト立ち上げ、技術選定、全体設計、タスク分解・委譲、並列開発時に使用。
Webデザイン実装の鉄則ガイド。CSS/レイアウト設計の原則を提供。 Trigger when: UI/UX実装時、CSS設計時、レイアウト実装時、レスポンシブ対応時、 アクセシビリティ確認時、"レイアウト", "CSS", "スタイル" への言及時。 /figma-to-code スキルと併用する場合に自動で参照される。
Codex CLIワーカーエージェントを起動してタスクを実行する。 Claude CodeがオーケストレーターとしてCodexを呼び出すハイブリッド構成。 トリガー: 「Codexで実行」「Codexに任せて」「並列でCodex」「高速に処理」
CSS の包括的なベストプラクティスガイド（フレームワーク非依存）。パフォーマンス最適化、保守性、シンプルなコード、親子要素の相対値設計、モダン CSS 機能（Container Queries、:has()、ネイティブネスティング、Cascade Layers）をカバー。CSS 設計・実装・レビュー時に使用。Tailwind CSS 等のユーティリティフレームワーク使用時は tailwind-css スキルを参照。