import "github.com/gin-gonic/gin"
 
func main() {
    r := gin.Default() // Logger + Recovery ミドルウェア付き
 
    r.GET("/users", listUsers)
    r.POST("/users", createUser)
    r.GET("/users/:id", getUser)
    r.PUT("/users/:id", updateUser)
    r.DELETE("/users/:id", deleteUser)
 
    r.Run(":8080")
}
 
func getUser(c *gin.Context) {
    id := c.Param("id")
    c.JSON(http.StatusOK, gin.H{"id": id, "name": "Tanaka"})
}

// ワイルドカードルーティングの例
r.GET("/files/*filepath", func(c *gin.Context) {
    filepath := c.Param("filepath")
    // filepath = "/images/logo.png" のように先頭スラッシュ付き
    c.String(http.StatusOK, "Serving: %s", filepath)
})

func listUsers(c *gin.Context) {
    // クエリパラメータ
    page := c.DefaultQuery("page", "1")
    limit := c.DefaultQuery("limit", "20")
    sort := c.Query("sort") // 空文字列がデフォルト
 
    // 数値変換
    pageNum, err := strconv.Atoi(page)
    if err != nil || pageNum < 1 {
        pageNum = 1
    }
    limitNum, err := strconv.Atoi(limit)
    if err != nil || limitNum < 1 || limitNum > 100 {
        limitNum = 20
    }
 
    // ページネーション付きレスポンス
    c.JSON(http.StatusOK, gin.H{
        "page":  pageNum,
        "limit": limitNum,
        "sort":  sort,
        "users": []gin.H{},
    })
}

import "github.com/labstack/echo/v4"
 
func main() {
    e := echo.New()
    e.Use(middleware.Logger())
    e.Use(middleware.Recover())
 
    e.GET("/users", listUsers)
    e.POST("/users", createUser)
    e.GET("/users/:id", getUser)
 
    e.Logger.Fatal(e.Start(":8080"))
}
 
func getUser(c echo.Context) error {
    id := c.Param("id")
    return c.JSON(http.StatusOK, map[string]string{"id": id})
}

// Echo のエラーハンドリングはハンドラの戻り値で制御できる
func getUser(c echo.Context) error {
    id := c.Param("id")
    user, err := userService.FindByID(c.Request().Context(), id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return echo.NewHTTPError(http.StatusNotFound, "user not found")
        }
        return echo.NewHTTPError(http.StatusInternalServerError, err.Error())
    }
    return c.JSON(http.StatusOK, user)
}

// Echo ワイルドカード
e.GET("/files/*", func(c echo.Context) error {
    filepath := c.Param("*")
    return c.String(http.StatusOK, "Serving: "+filepath)
})
 
// クエリパラメータ
func listUsers(c echo.Context) error {
    page := c.QueryParam("page")
    limit := c.QueryParam("limit")
    if page == "" {
        page = "1"
    }
    if limit == "" {
        limit = "20"
    }
    return c.JSON(http.StatusOK, map[string]string{
        "page":  page,
        "limit": limit,
    })
}

type CreateUserRequest struct {
    Name     string `json:"name" binding:"required,min=2,max=50"`
    Email    string `json:"email" binding:"required,email"`
    Age      int    `json:"age" binding:"gte=0,lte=150"`
    Password string `json:"password" binding:"required,min=8"`
}
 
func createUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    // バリデーション通過
    c.JSON(http.StatusCreated, gin.H{"name": req.Name})
}

// カスタムバリデーションルールの登録
func setupValidator() {
    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
        // カスタムバリデーション: 日本の電話番号
        v.RegisterValidation("jpphone", func(fl validator.FieldLevel) bool {
            phone := fl.Field().String()
            matched, _ := regexp.MatchString(`^0\d{1,4}-?\d{1,4}-?\d{4}$`, phone)
            return matched
        })
 
        // カスタムバリデーション: パスワード強度
        v.RegisterValidation("strongpassword", func(fl validator.FieldLevel) bool {
            password := fl.Field().String()
            hasUpper := regexp.MustCompile(`[A-Z]`).MatchString(password)
            hasLower := regexp.MustCompile(`[a-z]`).MatchString(password)
            hasNumber := regexp.MustCompile(`[0-9]`).MatchString(password)
            hasSpecial := regexp.MustCompile(`[!@#$%^&*]`).MatchString(password)
            return hasUpper && hasLower && hasNumber && hasSpecial
        })
 
        // JSON タグ名をエラーメッセージに使用
        v.RegisterTagNameFunc(func(fld reflect.StructField) string {
            name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
            if name == "-" {
                return ""
            }
            return name
        })
    }
}
 
// カスタムバリデーションを使用する構造体
type RegisterRequest struct {
    Name     string `json:"name" binding:"required,min=2,max=50"`
    Email    string `json:"email" binding:"required,email"`
    Phone    string `json:"phone" binding:"required,jpphone"`
    Password string `json:"password" binding:"required,min=8,strongpassword"`
}

// バリデーションエラーの変換
func formatValidationErrors(err error) []map[string]string {
    var ve validator.ValidationErrors
    if !errors.As(err, &ve) {
        return []map[string]string{{"error": err.Error()}}
    }
 
    errs := make([]map[string]string, len(ve))
    for i, fe := range ve {
        errs[i] = map[string]string{
            "field":   fe.Field(),
            "tag":     fe.Tag(),
            "value":   fmt.Sprintf("%v", fe.Value()),
            "message": validationMessage(fe),
        }
    }
    return errs
}
 
func validationMessage(fe validator.FieldError) string {
    switch fe.Tag() {
    case "required":
        return fmt.Sprintf("%s は必須です", fe.Field())
    case "email":
        return fmt.Sprintf("%s は有効なメールアドレスではありません", fe.Field())
    case "min":
        return fmt.Sprintf("%s は %s 以上である必要があります", fe.Field(), fe.Param())
    case "max":
        return fmt.Sprintf("%s は %s 以下である必要があります", fe.Field(), fe.Param())
    case "jpphone":
        return fmt.Sprintf("%s は有効な日本の電話番号ではありません", fe.Field())
    case "strongpassword":
        return "パスワードには大文字・小文字・数字・特殊文字が必要です"
    default:
        return fmt.Sprintf("%s は %s を満たしていません", fe.Field(), fe.Tag())
    }
}
 
// ハンドラでの使用
func createUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "code":   "VALIDATION_ERROR",
            "errors": formatValidationErrors(err),
        })
        return
    }
    // ...
}

func main() {
    r := gin.Default()
 
    // 公開API
    public := r.Group("/api/v1")
    {
        public.POST("/login", login)
        public.POST("/register", register)
    }
 
    // 認証必須API
    authorized := r.Group("/api/v1")
    authorized.Use(authMiddleware())
    {
        authorized.GET("/profile", getProfile)
        authorized.PUT("/profile", updateProfile)
    }
 
    // 管理者API
    admin := r.Group("/api/v1/admin")
    admin.Use(authMiddleware(), adminMiddleware())
    {
        admin.GET("/users", adminListUsers)
    }
 
    r.Run(":8080")
}
 
func authMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(401, gin.H{"error": "unauthorized"})
            return
        }
        claims, err := validateToken(token)
        if err != nil {
            c.AbortWithStatusJSON(401, gin.H{"error": "invalid token"})
            return
        }
        c.Set("userID", claims.UserID)
        c.Next()
    }
}

// ミドルウェアの実行順序を理解するための例
func middleware1() gin.HandlerFunc {
    return func(c *gin.Context) {
        fmt.Println("middleware1: before")
        c.Next()
        fmt.Println("middleware1: after")
    }
}
 
func middleware2() gin.HandlerFunc {
    return func(c *gin.Context) {
        fmt.Println("middleware2: before")
        c.Next()
        fmt.Println("middleware2: after")
    }
}
 
// 出力順序:
// middleware1: before
// middleware2: before
// handler
// middleware2: after
// middleware1: after

import "github.com/go-playground/validator/v10"
 
type CustomValidator struct {
    validator *validator.Validate
}
 
func (cv *CustomValidator) Validate(i interface{}) error {
    return cv.validator.Struct(i)
}
 
func main() {
    e := echo.New()
    e.Validator = &CustomValidator{validator: validator.New()}
 
    e.POST("/users", func(c echo.Context) error {
        u := new(CreateUserRequest)
        if err := c.Bind(u); err != nil {
            return echo.NewHTTPError(http.StatusBadRequest, err.Error())
        }
        if err := c.Validate(u); err != nil {
            return echo.NewHTTPError(http.StatusBadRequest, err.Error())
        }
        return c.JSON(http.StatusCreated, u)
    })
}

// 拡張カスタムバリデータ
type CustomValidator struct {
    validator *validator.Validate
}
 
func NewCustomValidator() *CustomValidator {
    v := validator.New()
 
    // JSON タグ名をフィールド名として使用
    v.RegisterTagNameFunc(func(fld reflect.StructField) string {
        name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
        if name == "-" {
            return ""
        }
        return name
    })
 
    return &CustomValidator{validator: v}
}
 
func (cv *CustomValidator) Validate(i interface{}) error {
    if err := cv.validator.Struct(i); err != nil {
        var ve validator.ValidationErrors
        if errors.As(err, &ve) {
            return &ValidationError{Errors: formatErrors(ve)}
        }
        return err
    }
    return nil
}
 
// カスタムエラー型
type ValidationError struct {
    Errors []FieldError `json:"errors"`
}
 
type FieldError struct {
    Field   string `json:"field"`
    Message string `json:"message"`
}
 
func (e *ValidationError) Error() string {
    return "validation failed"
}
 
func formatErrors(ve validator.ValidationErrors) []FieldError {
    errs := make([]FieldError, len(ve))
    for i, fe := range ve {
        errs[i] = FieldError{
            Field:   fe.Field(),
            Message: msgForTag(fe),
        }
    }
    return errs
}
 
func msgForTag(fe validator.FieldError) string {
    switch fe.Tag() {
    case "required":
        return "この項目は必須です"
    case "email":
        return "有効なメールアドレスを入力してください"
    default:
        return fe.Error()
    }
}

// 統一レスポンス構造体
type Response struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
    Meta    *Meta       `json:"meta,omitempty"`
}
 
type Meta struct {
    Page       int   `json:"page"`
    PerPage    int   `json:"per_page"`
    Total      int64 `json:"total"`
    TotalPages int   `json:"total_pages"`
}
 
type ErrorDetail struct {
    Code    string      `json:"code"`
    Message string      `json:"message"`
    Field   string      `json:"field,omitempty"`
    Details interface{} `json:"details,omitempty"`
}
 
type ErrorResponse struct {
    Code    int           `json:"code"`
    Message string        `json:"message"`
    Errors  []ErrorDetail `json:"errors,omitempty"`
}
 
// レスポンスヘルパー関数
func respondOK(c *gin.Context, data interface{}) {
    c.JSON(http.StatusOK, Response{
        Code:    http.StatusOK,
        Message: "success",
        Data:    data,
    })
}
 
func respondCreated(c *gin.Context, data interface{}) {
    c.JSON(http.StatusCreated, Response{
        Code:    http.StatusCreated,
        Message: "created",
        Data:    data,
    })
}
 
func respondPaginated(c *gin.Context, data interface{}, page, perPage int, total int64) {
    totalPages := int(total) / perPage
    if int(total)%perPage > 0 {
        totalPages++
    }
    c.JSON(http.StatusOK, Response{
        Code:    http.StatusOK,
        Message: "success",
        Data:    data,
        Meta: &Meta{
            Page:       page,
            PerPage:    perPage,
            Total:      total,
            TotalPages: totalPages,
        },
    })
}
 
func respondError(c *gin.Context, status int, code, message string) {
    c.JSON(status, ErrorResponse{
        Code:    status,
        Message: message,
        Errors:  []ErrorDetail{{Code: code, Message: message}},
    })
}
 
func respondValidationError(c *gin.Context, errors []ErrorDetail) {
    c.JSON(http.StatusBadRequest, ErrorResponse{
        Code:    http.StatusBadRequest,
        Message: "validation error",
        Errors:  errors,
    })
}
 
// ハンドラでの使用例
func listUsers(c *gin.Context) {
    page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
    perPage, _ := strconv.Atoi(c.DefaultQuery("per_page", "20"))
 
    users, total, err := userService.List(c.Request.Context(), page, perPage)
    if err != nil {
        respondError(c, http.StatusInternalServerError, "INTERNAL_ERROR", "ユーザー一覧の取得に失敗しました")
        return
    }
    respondPaginated(c, users, page, perPage, total)
}

func setupMiddlewares(e *echo.Echo) {
    // リカバリー
    e.Use(middleware.RecoverWithConfig(middleware.RecoverConfig{
        StackSize:         4 << 10, // 4 KB
        DisableStackAll:   false,
        DisablePrintStack: false,
        LogErrorFunc: func(c echo.Context, err error, stack []byte) error {
            log.Printf("PANIC: %v\n%s", err, stack)
            return nil
        },
    }))
 
    // CORS
    e.Use(middleware.CORSWithConfig(middleware.CORSConfig{
        AllowOrigins: []string{"https://example.com", "https://app.example.com"},
        AllowMethods: []string{http.MethodGet, http.MethodPost, http.MethodPut, http.MethodDelete},
        AllowHeaders: []string{
            echo.HeaderOrigin,
            echo.HeaderContentType,
            echo.HeaderAccept,
            echo.HeaderAuthorization,
        },
        AllowCredentials: true,
        MaxAge:           3600,
    }))
 
    // レート制限
    e.Use(middleware.RateLimiterWithConfig(middleware.RateLimiterConfig{
        Skipper: middleware.DefaultSkipper,
        Store: middleware.NewRateLimiterMemoryStoreWithConfig(
            middleware.RateLimiterMemoryStoreConfig{
                Rate:      10,              // 10 requests
                Burst:     30,              // burst of 30
                ExpiresIn: 3 * time.Minute, // TTL
            },
        ),
        IdentifierExtractor: func(ctx echo.Context) (string, error) {
            id := ctx.RealIP()
            return id, nil
        },
        ErrorHandler: func(ctx echo.Context, err error) error {
            return ctx.JSON(http.StatusForbidden, map[string]string{
                "error": "rate limit exceeded",
            })
        },
        DenyHandler: func(ctx echo.Context, identifier string, err error) error {
            return ctx.JSON(http.StatusTooManyRequests, map[string]string{
                "error": "too many requests",
            })
        },
    }))
 
    // リクエストID
    e.Use(middleware.RequestID())
 
    // タイムアウト
    e.Use(middleware.TimeoutWithConfig(middleware.TimeoutConfig{
        Timeout: 30 * time.Second,
    }))
 
    // Gzip圧縮
    e.Use(middleware.GzipWithConfig(middleware.GzipConfig{
        Level: 5,
        Skipper: func(c echo.Context) bool {
            return strings.Contains(c.Path(), "ws")
        },
    }))
 
    // セキュリティヘッダ
    e.Use(middleware.SecureWithConfig(middleware.SecureConfig{
        XSSProtection:         "1; mode=block",
        ContentTypeNosniff:    "nosniff",
        XFrameOptions:         "DENY",
        HSTSMaxAge:            31536000,
        ContentSecurityPolicy: "default-src 'self'",
    }))
}

// リクエストIDミドルウェア
func RequestIDMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        requestID := c.GetHeader("X-Request-ID")
        if requestID == "" {
            requestID = uuid.New().String()
        }
        c.Set("requestID", requestID)
        c.Header("X-Request-ID", requestID)
        c.Next()
    }
}
 
// 構造化ログミドルウェア
func StructuredLoggerMiddleware(logger *slog.Logger) gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        path := c.Request.URL.Path
        raw := c.Request.URL.RawQuery
 
        c.Next()
 
        latency := time.Since(start)
        status := c.Writer.Status()
        clientIP := c.ClientIP()
        method := c.Request.Method
        requestID, _ := c.Get("requestID")
 
        attrs := []slog.Attr{
            slog.String("request_id", fmt.Sprintf("%v", requestID)),
            slog.String("method", method),
            slog.String("path", path),
            slog.String("query", raw),
            slog.Int("status", status),
            slog.Duration("latency", latency),
            slog.String("client_ip", clientIP),
            slog.Int("body_size", c.Writer.Size()),
        }
 
        if status >= 500 {
            logger.LogAttrs(c.Request.Context(), slog.LevelError, "Server error", attrs...)
        } else if status >= 400 {
            logger.LogAttrs(c.Request.Context(), slog.LevelWarn, "Client error", attrs...)
        } else {
            logger.LogAttrs(c.Request.Context(), slog.LevelInfo, "Request", attrs...)
        }
    }
}
 
// CORSミドルウェア
func CORSMiddleware(allowOrigins []string) gin.HandlerFunc {
    originMap := make(map[string]bool)
    for _, o := range allowOrigins {
        originMap[o] = true
    }
 
    return func(c *gin.Context) {
        origin := c.Request.Header.Get("Origin")
        if originMap[origin] {
            c.Header("Access-Control-Allow-Origin", origin)
            c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
            c.Header("Access-Control-Allow-Headers", "Origin, Content-Type, Accept, Authorization, X-Request-ID")
            c.Header("Access-Control-Allow-Credentials", "true")
            c.Header("Access-Control-Max-Age", "3600")
        }
 
        if c.Request.Method == "OPTIONS" {
            c.AbortWithStatus(http.StatusNoContent)
            return
        }
 
        c.Next()
    }
}
 
// レート制限ミドルウェア (Token Bucket)
func RateLimitMiddleware(rps int, burst int) gin.HandlerFunc {
    var mu sync.Mutex
    limiters := make(map[string]*rate.Limiter)
 
    getLimiter := func(key string) *rate.Limiter {
        mu.Lock()
        defer mu.Unlock()
        if limiter, exists := limiters[key]; exists {
            return limiter
        }
        limiter := rate.NewLimiter(rate.Limit(rps), burst)
        limiters[key] = limiter
        return limiter
    }
 
    // 古いエントリの定期クリーンアップ
    go func() {
        for range time.Tick(10 * time.Minute) {
            mu.Lock()
            limiters = make(map[string]*rate.Limiter)
            mu.Unlock()
        }
    }()
 
    return func(c *gin.Context) {
        limiter := getLimiter(c.ClientIP())
        if !limiter.Allow() {
            c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{
                "code":    "RATE_LIMIT_EXCEEDED",
                "message": "リクエスト数が制限を超えました",
            })
            return
        }
        c.Next()
    }
}
 
// タイムアウトミドルウェア
func TimeoutMiddleware(timeout time.Duration) gin.HandlerFunc {
    return func(c *gin.Context) {
        ctx, cancel := context.WithTimeout(c.Request.Context(), timeout)
        defer cancel()
 
        c.Request = c.Request.WithContext(ctx)
 
        done := make(chan struct{})
        go func() {
            c.Next()
            close(done)
        }()
 
        select {
        case <-done:
            return
        case <-ctx.Done():
            c.AbortWithStatusJSON(http.StatusGatewayTimeout, gin.H{
                "code":    "TIMEOUT",
                "message": "リクエストがタイムアウトしました",
            })
        }
    }
}
 
// セキュリティヘッダミドルウェア
func SecurityHeadersMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Header("X-Content-Type-Options", "nosniff")
        c.Header("X-Frame-Options", "DENY")
        c.Header("X-XSS-Protection", "1; mode=block")
        c.Header("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
        c.Header("Content-Security-Policy", "default-src 'self'")
        c.Header("Referrer-Policy", "strict-origin-when-cross-origin")
        c.Header("Permissions-Policy", "camera=(), microphone=(), geolocation=()")
        c.Next()
    }
}

import (
    "github.com/golang-jwt/jwt/v5"
)
 
// JWT設定
type JWTConfig struct {
    SecretKey     []byte
    Issuer        string
    AccessExpiry  time.Duration
    RefreshExpiry time.Duration
}
 
// カスタムクレーム
type Claims struct {
    UserID int64  `json:"user_id"`
    Email  string `json:"email"`
    Role   string `json:"role"`
    jwt.RegisteredClaims
}
 
// トークンペア
type TokenPair struct {
    AccessToken  string `json:"access_token"`
    RefreshToken string `json:"refresh_token"`
    ExpiresAt    int64  `json:"expires_at"`
}
 
// トークン生成
func (cfg *JWTConfig) GenerateTokenPair(userID int64, email, role string) (*TokenPair, error) {
    now := time.Now()
 
    // アクセストークン
    accessClaims := Claims{
        UserID: userID,
        Email:  email,
        Role:   role,
        RegisteredClaims: jwt.RegisteredClaims{
            Issuer:    cfg.Issuer,
            Subject:   strconv.FormatInt(userID, 10),
            ExpiresAt: jwt.NewNumericDate(now.Add(cfg.AccessExpiry)),
            IssuedAt:  jwt.NewNumericDate(now),
            NotBefore: jwt.NewNumericDate(now),
            ID:        uuid.New().String(),
        },
    }
    accessToken := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims)
    accessTokenStr, err := accessToken.SignedString(cfg.SecretKey)
    if err != nil {
        return nil, fmt.Errorf("access token signing: %w", err)
    }
 
    // リフレッシュトークン
    refreshClaims := jwt.RegisteredClaims{
        Issuer:    cfg.Issuer,
        Subject:   strconv.FormatInt(userID, 10),
        ExpiresAt: jwt.NewNumericDate(now.Add(cfg.RefreshExpiry)),
        IssuedAt:  jwt.NewNumericDate(now),
        ID:        uuid.New().String(),
    }
    refreshToken := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims)
    refreshTokenStr, err := refreshToken.SignedString(cfg.SecretKey)
    if err != nil {
        return nil, fmt.Errorf("refresh token signing: %w", err)
    }
 
    return &TokenPair{
        AccessToken:  accessTokenStr,
        RefreshToken: refreshTokenStr,
        ExpiresAt:    accessClaims.ExpiresAt.Unix(),
    }, nil
}
 
// トークン検証
func (cfg *JWTConfig) ValidateToken(tokenStr string) (*Claims, error) {
    token, err := jwt.ParseWithClaims(tokenStr, &Claims{}, func(token *jwt.Token) (interface{}, error) {
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
        }
        return cfg.SecretKey, nil
    })
    if err != nil {
        return nil, fmt.Errorf("token parse: %w", err)
    }
 
    claims, ok := token.Claims.(*Claims)
    if !ok || !token.Valid {
        return nil, fmt.Errorf("invalid token claims")
    }
    return claims, nil
}
 
// JWT認証ミドルウェア
func JWTAuthMiddleware(jwtCfg *JWTConfig) gin.HandlerFunc {
    return func(c *gin.Context) {
        authHeader := c.GetHeader("Authorization")
        if authHeader == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
                "code":    "UNAUTHORIZED",
                "message": "Authorization ヘッダが必要です",
            })
            return
        }
 
        // "Bearer <token>" 形式の検証
        parts := strings.SplitN(authHeader, " ", 2)
        if len(parts) != 2 || !strings.EqualFold(parts[0], "bearer") {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
                "code":    "INVALID_TOKEN_FORMAT",
                "message": "Bearer トークン形式が無効です",
            })
            return
        }
 
        claims, err := jwtCfg.ValidateToken(parts[1])
        if err != nil {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
                "code":    "INVALID_TOKEN",
                "message": "トークンが無効または期限切れです",
            })
            return
        }
 
        // コンテキストにユーザー情報をセット
        c.Set("userID", claims.UserID)
        c.Set("email", claims.Email)
        c.Set("role", claims.Role)
        c.Set("claims", claims)
        c.Next()
    }
}
 
// ロールベース認可ミドルウェア
func RequireRole(roles ...string) gin.HandlerFunc {
    roleSet := make(map[string]bool)
    for _, r := range roles {
        roleSet[r] = true
    }
 
    return func(c *gin.Context) {
        role, exists := c.Get("role")
        if !exists {
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
                "code":    "FORBIDDEN",
                "message": "権限がありません",
            })
            return
        }
 
        if !roleSet[role.(string)] {
            c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
                "code":    "INSUFFICIENT_ROLE",
                "message": fmt.Sprintf("必要なロール: %v", roles),
            })
            return
        }
        c.Next()
    }
}
 
// ログインハンドラ
func loginHandler(jwtCfg *JWTConfig, userService UserService) gin.HandlerFunc {
    return func(c *gin.Context) {
        var req LoginRequest
        if err := c.ShouldBindJSON(&req); err != nil {
            respondError(c, http.StatusBadRequest, "VALIDATION_ERROR", err.Error())
            return
        }
 
        user, err := userService.Authenticate(c.Request.Context(), req.Email, req.Password)
        if err != nil {
            respondError(c, http.StatusUnauthorized, "INVALID_CREDENTIALS", "メールアドレスまたはパスワードが間違っています")
            return
        }
 
        tokens, err := jwtCfg.GenerateTokenPair(user.ID, user.Email, user.Role)
        if err != nil {
            respondError(c, http.StatusInternalServerError, "TOKEN_GENERATION_ERROR", "トークンの生成に失敗しました")
            return
        }
 
        c.JSON(http.StatusOK, gin.H{
            "code":    200,
            "message": "success",
            "data":    tokens,
        })
    }
}

// カスタムコンテキスト
type AppContext struct {
    echo.Context
    UserID int64
    Role   string
}
 
// カスタムコンテキストミドルウェア
func CustomContextMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
    return func(c echo.Context) error {
        cc := &AppContext{Context: c}
        return next(cc)
    }
}
 
// カスタムコンテキストを使ったハンドラ
func getProfile(c echo.Context) error {
    cc := c.(*AppContext)
    user, err := userService.FindByID(cc.Request().Context(), cc.UserID)
    if err != nil {
        return echo.NewHTTPError(http.StatusNotFound, "user not found")
    }
    return cc.JSON(http.StatusOK, user)
}
 
// Echo グループの構成
func setupRoutes(e *echo.Echo, jwtCfg *JWTConfig) {
    // APIバージョニング
    v1 := e.Group("/api/v1")
    v1.Use(CustomContextMiddleware)
 
    // 公開エンドポイント
    public := v1.Group("")
    {
        public.POST("/auth/login", loginHandler)
        public.POST("/auth/register", registerHandler)
        public.POST("/auth/refresh", refreshTokenHandler)
    }
 
    // 認証必須エンドポイント
    auth := v1.Group("")
    auth.Use(echoJWTMiddleware(jwtCfg))
    {
        auth.GET("/profile", getProfile)
        auth.PUT("/profile", updateProfile)
        auth.GET("/users/:id", getUserByID)
    }
 
    // 管理者エンドポイント
    admin := v1.Group("/admin")
    admin.Use(echoJWTMiddleware(jwtCfg), echoRequireRole("admin"))
    {
        admin.GET("/users", adminListUsers)
        admin.DELETE("/users/:id", adminDeleteUser)
        admin.GET("/stats", getStats)
    }
}

// Swaggerアノテーション付きハンドラ
 
// @Summary ユーザー一覧取得
// @Description ページネーション付きのユーザー一覧を取得する
// @Tags users
// @Accept json
// @Produce json
// @Param page query int false "ページ番号" default(1)
// @Param per_page query int false "1ページあたりの件数" default(20) maximum(100)
// @Param sort query string false "ソート項目" Enums(name, email, created_at)
// @Param order query string false "ソート順序" Enums(asc, desc) default(asc)
// @Success 200 {object} Response{data=[]User,meta=Meta} "成功"
// @Failure 400 {object} ErrorResponse "バリデーションエラー"
// @Failure 401 {object} ErrorResponse "認証エラー"
// @Failure 500 {object} ErrorResponse "サーバーエラー"
// @Security BearerAuth
// @Router /api/v1/users [get]
func listUsers(c *gin.Context) {
    // 実装
}
 
// @Summary ユーザー作成
// @Description 新しいユーザーを作成する
// @Tags users
// @Accept json
// @Produce json
// @Param request body CreateUserRequest true "ユーザー作成リクエスト"
// @Success 201 {object} Response{data=User} "作成成功"
// @Failure 400 {object} ErrorResponse "バリデーションエラー"
// @Failure 409 {object} ErrorResponse "メールアドレス重複"
// @Failure 500 {object} ErrorResponse "サーバーエラー"
// @Security BearerAuth
// @Router /api/v1/users [post]
func createUser(c *gin.Context) {
    // 実装
}
 
// @Summary ユーザー取得
// @Description IDでユーザーを取得する
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "ユーザーID"
// @Success 200 {object} Response{data=User} "成功"
// @Failure 404 {object} ErrorResponse "ユーザーが見つかりません"
// @Failure 500 {object} ErrorResponse "サーバーエラー"
// @Security BearerAuth
// @Router /api/v1/users/{id} [get]
func getUser(c *gin.Context) {
    // 実装
}
 
// Swaggerの設定
// @title My API
// @version 1.0
// @description ユーザー管理API
// @host localhost:8080
// @BasePath /api/v1
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
 
func main() {
    r := gin.Default()
 
    // Swaggerエンドポイント
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
 
    // API ルーティング
    v1 := r.Group("/api/v1")
    {
        v1.GET("/users", listUsers)
        v1.POST("/users", createUser)
        v1.GET("/users/:id", getUser)
    }
 
    r.Run(":8080")
}

# swag のインストール
go install github.com/swaggo/swag/cmd/swag@latest
 
# ドキュメント生成
swag init -g cmd/api/main.go -o docs
 
# 生成されるファイル:
# docs/docs.go
# docs/swagger.json
# docs/swagger.yaml

import (
    "net/http"
    "net/http/httptest"
    "testing"
 
    "github.com/gin-gonic/gin"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)
 
// テスト用のGinエンジンを作成するヘルパー
func setupTestRouter() *gin.Engine {
    gin.SetMode(gin.TestMode)
    r := gin.New()
    return r
}
 
// ハンドラのユニットテスト
func TestGetUser(t *testing.T) {
    r := setupTestRouter()
 
    mockService := &MockUserService{
        users: map[int64]*User{
            1: {ID: 1, Name: "Tanaka", Email: "tanaka@example.com"},
        },
    }
 
    r.GET("/users/:id", getUserHandler(mockService))
 
    tests := []struct {
        name       string
        userID     string
        wantStatus int
        wantBody   string
    }{
        {
            name:       "正常系: ユーザー取得",
            userID:     "1",
            wantStatus: http.StatusOK,
            wantBody:   `"name":"Tanaka"`,
        },
        {
            name:       "異常系: ユーザーが存在しない",
            userID:     "999",
            wantStatus: http.StatusNotFound,
            wantBody:   `"code":"NOT_FOUND"`,
        },
        {
            name:       "異常系: 無効なID",
            userID:     "abc",
            wantStatus: http.StatusBadRequest,
            wantBody:   `"code":"INVALID_ID"`,
        },
    }
 
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            req := httptest.NewRequest(http.MethodGet, "/users/"+tt.userID, nil)
            w := httptest.NewRecorder()
 
            r.ServeHTTP(w, req)
 
            assert.Equal(t, tt.wantStatus, w.Code)
            assert.Contains(t, w.Body.String(), tt.wantBody)
        })
    }
}
 
// POST ハンドラのテスト
func TestCreateUser(t *testing.T) {
    r := setupTestRouter()
    mockService := &MockUserService{users: make(map[int64]*User)}
    r.POST("/users", createUserHandler(mockService))
 
    tests := []struct {
        name       string
        body       string
        wantStatus int
    }{
        {
            name:       "正常系: ユーザー作成",
            body:       `{"name":"Yamada","email":"yamada@example.com","password":"P@ssw0rd!"}`,
            wantStatus: http.StatusCreated,
        },
        {
            name:       "異常系: 名前が空",
            body:       `{"name":"","email":"yamada@example.com","password":"P@ssw0rd!"}`,
            wantStatus: http.StatusBadRequest,
        },
        {
            name:       "異常系: 無効なメール",
            body:       `{"name":"Yamada","email":"invalid","password":"P@ssw0rd!"}`,
            wantStatus: http.StatusBadRequest,
        },
        {
            name:       "異常系: JSONパースエラー",
            body:       `{invalid json`,
            wantStatus: http.StatusBadRequest,
        },
    }
 
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            req := httptest.NewRequest(http.MethodPost, "/users",
                strings.NewReader(tt.body))
            req.Header.Set("Content-Type", "application/json")
            w := httptest.NewRecorder()
 
            r.ServeHTTP(w, req)
 
            assert.Equal(t, tt.wantStatus, w.Code)
        })
    }
}
 
// ミドルウェアのテスト
func TestAuthMiddleware(t *testing.T) {
    jwtCfg := &JWTConfig{
        SecretKey:    []byte("test-secret"),
        Issuer:       "test",
        AccessExpiry: time.Hour,
    }
 
    r := setupTestRouter()
    r.Use(JWTAuthMiddleware(jwtCfg))
    r.GET("/protected", func(c *gin.Context) {
        userID := c.GetInt64("userID")
        c.JSON(http.StatusOK, gin.H{"user_id": userID})
    })
 
    t.Run("トークンなし", func(t *testing.T) {
        req := httptest.NewRequest(http.MethodGet, "/protected", nil)
        w := httptest.NewRecorder()
        r.ServeHTTP(w, req)
        assert.Equal(t, http.StatusUnauthorized, w.Code)
    })
 
    t.Run("有効なトークン", func(t *testing.T) {
        tokens, err := jwtCfg.GenerateTokenPair(42, "test@example.com", "user")
        require.NoError(t, err)
 
        req := httptest.NewRequest(http.MethodGet, "/protected", nil)
        req.Header.Set("Authorization", "Bearer "+tokens.AccessToken)
        w := httptest.NewRecorder()
        r.ServeHTTP(w, req)
 
        assert.Equal(t, http.StatusOK, w.Code)
        assert.Contains(t, w.Body.String(), `"user_id":42`)
    })
 
    t.Run("無効なトークン", func(t *testing.T) {
        req := httptest.NewRequest(http.MethodGet, "/protected", nil)
        req.Header.Set("Authorization", "Bearer invalid-token")
        w := httptest.NewRecorder()
        r.ServeHTTP(w, req)
        assert.Equal(t, http.StatusUnauthorized, w.Code)
    })
}

func TestEchoGetUser(t *testing.T) {
    e := echo.New()
    e.Validator = NewCustomValidator()
 
    mockService := &MockUserService{
        users: map[int64]*User{
            1: {ID: 1, Name: "Tanaka", Email: "tanaka@example.com"},
        },
    }
 
    tests := []struct {
        name       string
        userID     string
        wantStatus int
        wantBody   string
    }{
        {
            name:       "正常系",
            userID:     "1",
            wantStatus: http.StatusOK,
            wantBody:   `"name":"Tanaka"`,
        },
        {
            name:       "ユーザー未存在",
            userID:     "999",
            wantStatus: http.StatusNotFound,
        },
    }
 
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            req := httptest.NewRequest(http.MethodGet, "/", nil)
            rec := httptest.NewRecorder()
            c := e.NewContext(req, rec)
            c.SetPath("/users/:id")
            c.SetParamNames("id")
            c.SetParamValues(tt.userID)
 
            handler := getUserHandler(mockService)
            err := handler(c)
 
            if tt.wantStatus >= 400 {
                he, ok := err.(*echo.HTTPError)
                assert.True(t, ok)
                assert.Equal(t, tt.wantStatus, he.Code)
            } else {
                assert.NoError(t, err)
                assert.Equal(t, tt.wantStatus, rec.Code)
                if tt.wantBody != "" {
                    assert.Contains(t, rec.Body.String(), tt.wantBody)
                }
            }
        })
    }
}
 
// Echo ミドルウェアのテスト
func TestEchoRateLimitMiddleware(t *testing.T) {
    e := echo.New()
    e.Use(middleware.RateLimiterWithConfig(middleware.RateLimiterConfig{
        Store: middleware.NewRateLimiterMemoryStoreWithConfig(
            middleware.RateLimiterMemoryStoreConfig{
                Rate:  2,
                Burst: 2,
            },
        ),
        IdentifierExtractor: func(ctx echo.Context) (string, error) {
            return ctx.RealIP(), nil
        },
        DenyHandler: func(ctx echo.Context, identifier string, err error) error {
            return ctx.JSON(http.StatusTooManyRequests, map[string]string{
                "error": "rate limited",
            })
        },
    }))
    e.GET("/test", func(c echo.Context) error {
        return c.String(http.StatusOK, "ok")
    })
 
    // 最初の2リクエストは成功
    for i := 0; i < 2; i++ {
        req := httptest.NewRequest(http.MethodGet, "/test", nil)
        rec := httptest.NewRecorder()
        e.ServeHTTP(rec, req)
        assert.Equal(t, http.StatusOK, rec.Code)
    }
 
    // 3番目のリクエストはレート制限
    req := httptest.NewRequest(http.MethodGet, "/test", nil)
    rec := httptest.NewRecorder()
    e.ServeHTTP(rec, req)
    assert.Equal(t, http.StatusTooManyRequests, rec.Code)
}

func main() {
    // Releaseモード設定
    gin.SetMode(gin.ReleaseMode)
 
    r := gin.New()
 
    // ミドルウェアの設定
    r.Use(RequestIDMiddleware())
    r.Use(StructuredLoggerMiddleware(slog.Default()))
    r.Use(gin.Recovery())
    r.Use(CORSMiddleware([]string{"https://example.com"}))
    r.Use(SecurityHeadersMiddleware())
 
    // ヘルスチェック
    r.GET("/health", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "status": "ok",
            "time":   time.Now().UTC().Format(time.RFC3339),
        })
    })
 
    // Readiness チェック (DBなど外部依存の状態も確認)
    r.GET("/ready", func(c *gin.Context) {
        if err := db.PingContext(c.Request.Context()); err != nil {
            c.JSON(http.StatusServiceUnavailable, gin.H{
                "status": "not ready",
                "error":  err.Error(),
            })
            return
        }
        c.JSON(http.StatusOK, gin.H{"status": "ready"})
    })
 
    // API ルーティング
    setupRoutes(r)
 
    // サーバー設定
    srv := &http.Server{
        Addr:         ":8080",
        Handler:      r,
        ReadTimeout:  15 * time.Second,
        WriteTimeout: 30 * time.Second,
        IdleTimeout:  60 * time.Second,
        // ヘッダサイズの制限
        MaxHeaderBytes: 1 << 20, // 1 MB
    }
 
    // Graceful Shutdown
    go func() {
        slog.Info("Server starting", "addr", srv.Addr)
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            slog.Error("Server error", "error", err)
            os.Exit(1)
        }
    }()
 
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    sig := <-quit
    slog.Info("Shutdown signal received", "signal", sig)
 
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
 
    if err := srv.Shutdown(ctx); err != nil {
        slog.Error("Server forced to shutdown", "error", err)
        os.Exit(1)
    }
 
    slog.Info("Server exited properly")
}

func main() {
    e := echo.New()
    e.HideBanner = true
 
    // ミドルウェアの設定
    setupMiddlewares(e)
 
    // ルーティングの設定
    setupRoutes(e, jwtCfg)
 
    // ヘルスチェック
    e.GET("/health", func(c echo.Context) error {
        return c.JSON(http.StatusOK, map[string]string{
            "status": "ok",
            "time":   time.Now().UTC().Format(time.RFC3339),
        })
    })
 
    // カスタムHTTPエラーハンドラ
    e.HTTPErrorHandler = func(err error, c echo.Context) {
        if c.Response().Committed {
            return
        }
 
        var he *echo.HTTPError
        if errors.As(err, &he) {
            msg := he.Message
            if m, ok := msg.(string); ok {
                c.JSON(he.Code, map[string]interface{}{
                    "code":    he.Code,
                    "message": m,
                })
            } else {
                c.JSON(he.Code, map[string]interface{}{
                    "code":    he.Code,
                    "message": msg,
                })
            }
            return
        }
 
        var ve *ValidationError
        if errors.As(err, &ve) {
            c.JSON(http.StatusBadRequest, map[string]interface{}{
                "code":    http.StatusBadRequest,
                "message": "validation error",
                "errors":  ve.Errors,
            })
            return
        }
 
        // 未知のエラー
        slog.Error("Unhandled error", "error", err, "path", c.Path())
        c.JSON(http.StatusInternalServerError, map[string]interface{}{
            "code":    http.StatusInternalServerError,
            "message": "internal server error",
        })
    }
 
    // Graceful Shutdown
    go func() {
        if err := e.Start(":8080"); err != nil && err != http.ErrServerClosed {
            e.Logger.Fatal("shutting down the server")
        }
    }()
 
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
    <-quit
 
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
 
    if err := e.Shutdown(ctx); err != nil {
        e.Logger.Fatal(err)
    }
    slog.Info("Server exited")
}