API REST de Galería en Go con MongoDB, JWT, Bcrypt y Swagger

Tabla de Contenidos

1. Introducción

Este manual detalla cómo construir una API RESTful completa para una galería de imágenes con:

Requisitos previos:

2. Configuración del Proyecto

2.1 Crear un nuevo proyecto

mkdir gallery-api
cd gallery-api
go mod init github.com/tu-usuario/gallery-api

2.2 Instalar dependencias

go get github.com/gin-gonic/gin                   # Framework web
go get go.mongodb.org/mongo-driver/mongo       # Driver MongoDB
go get golang.org/x/crypto/bcrypt              # Hashing de contraseñas
go get github.com/golang-jwt/jwt/v4            # JWT
go get github.com/swaggo/swag/cmd/swag@latest  # Generador Swagger
go get github.com/swaggo/gin-swagger           # Integración Swagger con Gin
go get github.com/google/uuid                  # Generación de UUIDs

2.3 Configurar variables de entorno (.env)

MONGODB_URI=mongodb://localhost:27017
DB_NAME=gallery_db
JWT_SECRET=tu_super_secreto_jwt
JWT_EXPIRATION_HOURS=24
BCRYPT_COST=12
SERVER_ADDRESS=:8080
UPLOAD_DIR=./uploads

3. Estructura del Proyecto

gallery-api/
├── cmd/
│   └── server/
│       └── main.go          # Punto de entrada
├── internal/
│   ├── auth/                # Autenticación
│   │   ├── handler.go       # Manejadores HTTP
│   │   ├── service.go       # Lógica de negocio
│   │   └── repository.go    # Acceso a datos
│   ├── gallery/             # Gestión de galería
│   ├── config/              # Configuración
│   ├── middleware/          # Middlewares
│   └── models/              # Modelos de datos
├── pkg/
│   ├── database/            # Conexión a MongoDB
│   ├── storage/             # Almacenamiento de imágenes
│   └── utils/               # Utilidades
├── docs/                    # Documentación Swagger
├── uploads/                 # Imágenes subidas
├── .env                     # Variables de entorno
└── go.mod                   # Dependencias

4. Modelos de Datos con MongoDB

4.1 Modelo de Usuario

// internal/models/user.go
package models

import (
    "time"
    
    "go.mongodb.org/mongo-driver/bson/primitive"
)

type User struct {
    ID        primitive.ObjectID `bson:"_id,omitempty" json:"id"`
    Username  string             `bson:"username" json:"username" binding:"required,min=3,max=50"`
    Email     string             `bson:"email" json:"email" binding:"required,email"`
    Password  string             `bson:"password" json:"-" binding:"required,min=8"`
    CreatedAt time.Time          `bson:"created_at" json:"created_at"`
    UpdatedAt time.Time          `bson:"updated_at" json:"updated_at"`
}

type RegisterRequest struct {
    Username string `json:"username" binding:"required,min=3,max=50"`
    Email    string `json:"email" binding:"required,email"`
    Password string `json:"password" binding:"required,min=8"`
}

type LoginRequest struct {
    Email    string `json:"email" binding:"required,email"`
    Password string `json:"password" binding:"required"`
}

type UserResponse struct {
    ID        string    `json:"id"`
    Username  string    `json:"username"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
}

4.2 Modelo de Imagen

// internal/models/image.go
package models

import (
    "time"
    
    "go.mongodb.org/mongo-driver/bson/primitive"
)

type Image struct {
    ID          primitive.ObjectID `bson:"_id,omitempty" json:"id"`
    UserID      primitive.ObjectID `bson:"user_id" json:"user_id"`
    Title       string             `bson:"title" json:"title" binding:"required"`
    Description string             `bson:"description" json:"description"`
    Filename    string             `bson:"filename" json:"filename"`
    Filepath    string             `bson:"filepath" json:"filepath"`
    Size        int64              `bson:"size" json:"size"`
    MimeType    string             `bson:"mime_type" json:"mime_type"`
    CreatedAt   time.Time          `bson:"created_at" json:"created_at"`
    UpdatedAt   time.Time          `bson:"updated_at" json:"updated_at"`
}

type ImageResponse struct {
    ID          string    `json:"id"`
    Title       string    `json:"title"`
    Description string    `json:"description"`
    URL         string    `json:"url"`
    CreatedAt   time.Time `json:"created_at"`
}

type UploadRequest struct {
    Title       string `form:"title" binding:"required"`
    Description string `form:"description"`
}

5. Autenticación con JWT y Bcrypt

5.1 Configuración de JWT

// pkg/utils/auth.go
package utils

import (
    "time"
    
    "github.com/golang-jwt/jwt/v4"
)

func GenerateToken(userID string) (string, error) {
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
        "sub": userID,
        "exp": time.Now().Add(time.Hour * time.Duration(config.JWTExpirationHours)).Unix(),
        "iat": time.Now().Unix(),
    })
    
    return token.SignedString([]byte(config.JWTSecret))
}

func ParseToken(tokenString string) (string, error) {
    token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, jwt.ErrSignatureInvalid
        }
        return []byte(config.JWTSecret), nil
    })
    
    if err != nil {
        return "", err
    }
    
    if claims, ok := token.Claims.(jwt.MapClaims); ok && token.Valid {
        return claims["sub"].(string), nil
    }
    
    return "", jwt.ErrSignatureInvalid
}

5.2 Registro de Usuario

// internal/auth/handler.go
package auth

import (
    "net/http"
    
    "github.com/gin-gonic/gin"
    "github.com/tu-usuario/gallery-api/internal/models"
    "github.com/tu-usuario/gallery-api/pkg/utils"
    "golang.org/x/crypto/bcrypt"
)

func (h *Handler) Register(c *gin.Context) {
    var req models.RegisterRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    
    // Verificar si el usuario ya existe
    if _, err := h.repo.GetUserByEmail(req.Email); err == nil {
        c.JSON(http.StatusConflict, gin.H{"error": "email ya registrado"})
        return
    }
    
    // Hashear contraseña
    hashedPassword, err := bcrypt.GenerateFromPassword([]byte(req.Password), utils.BCRYPT_COST)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "error al hashear contraseña"})
        return
    }
    
    // Crear usuario
    user := models.User{
        Username:  req.Username,
        Email:     req.Email,
        Password:  string(hashedPassword),
        CreatedAt: time.Now(),
        UpdatedAt: time.Now(),
    }
    
    userID, err := h.repo.CreateUser(&user)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "error al crear usuario"})
        return
    }
    
    c.JSON(http.StatusCreated, gin.H{"id": userID.Hex()})
}

5.3 Login de Usuario

// internal/auth/handler.go
func (h *Handler) Login(c *gin.Context) {
    var req models.LoginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    
    // Obtener usuario
    user, err := h.repo.GetUserByEmail(req.Email)
    if err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "credenciales inválidas"})
        return
    }
    
    // Verificar contraseña
    if err := bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(req.Password)); err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "credenciales inválidas"})
        return
    }
    
    // Generar token JWT
    token, err := utils.GenerateToken(user.ID.Hex())
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "error al generar token"})
        return
    }
    
    c.JSON(http.StatusOK, gin.H{"token": token})
}

6. Gestión de la Galería

6.1 Subida de Imágenes

// internal/gallery/handler.go
package gallery

import (
    "mime/multipart"
    "net/http"
    "path/filepath"
    
    "github.com/gin-gonic/gin"
    "github.com/google/uuid"
    "github.com/tu-usuario/gallery-api/internal/models"
    "github.com/tu-usuario/gallery-api/pkg/storage"
)

func (h *Handler) UploadImage(c *gin.Context) {
    userID := c.MustGet("userID").(string)
    
    var req models.UploadRequest
    if err := c.ShouldBind(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    
    file, err := c.FormFile("file")
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "archivo requerido"})
        return
    }
    
    // Validar tipo de archivo
    if !storage.IsImage(file) {
        c.JSON(http.StatusBadRequest, gin.H{"error": "solo se permiten imágenes"})
        return
    }
    
    // Generar nombre único para el archivo
    ext := filepath.Ext(file.Filename)
    filename := uuid.New().String() + ext
    
    // Guardar archivo
    filePath, err := storage.SaveUploadedFile(file, filename)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "error al guardar imagen"})
        return
    }
    
    // Crear registro en la base de datos
    objID, _ := primitive.ObjectIDFromHex(userID)
    image := models.Image{
        UserID:      objID,
        Title:       req.Title,
        Description: req.Description,
        Filename:    filename,
        Filepath:    filePath,
        Size:        file.Size,
        MimeType:    file.Header.Get("Content-Type"),
        CreatedAt:   time.Now(),
        UpdatedAt:   time.Now(),
    }
    
    imageID, err := h.repo.CreateImage(&image)
    if err != nil {
        storage.DeleteFile(filePath)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "error al guardar metadatos"})
        return
    }
    
    c.JSON(http.StatusCreated, gin.H{"id": imageID.Hex()})
}

6.2 Listado de Imágenes

// internal/gallery/handler.go
func (h *Handler) GetImages(c *gin.Context) {
    userID := c.MustGet("userID").(string)
    objID, _ := primitive.ObjectIDFromHex(userID)
    
    images, err := h.repo.GetImagesByUserID(objID)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "error al obtener imágenes"})
        return
    }
    
    response := make([]models.ImageResponse, len(images))
    for i, img := range images {
        response[i] = models.ImageResponse{
            ID:          img.ID.Hex(),
            Title:       img.Title,
            Description: img.Description,
            URL:         storage.GetImageURL(img.Filepath),
            CreatedAt:   img.CreatedAt,
        }
    }
    
    c.JSON(http.StatusOK, response)
}

7. Middlewares

7.1 Middleware de Autenticación JWT

// internal/middleware/auth.go
package middleware

import (
    "github.com/gin-gonic/gin"
    "github.com/tu-usuario/gallery-api/pkg/utils"
)

func JWTAuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "autorización requerida"})
            return
        }
        
        // Extraer el token del formato "Bearer "
        if len(token) > 7 && token[:7] == "Bearer " {
            token = token[7:]
        }
        
        userID, err := utils.ParseToken(token)
        if err != nil {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "token inválido"})
            return
        }
        
        c.Set("userID", userID)
        c.Next()
    }
}

7.2 Configuración de Rutas

// cmd/server/main.go
package main

import (
    "github.com/gin-gonic/gin"
    "github.com/tu-usuario/gallery-api/internal/auth"
    "github.com/tu-usuario/gallery-api/internal/gallery"
    "github.com/tu-usuario/gallery-api/internal/middleware"
    "github.com/tu-usuario/gallery-api/pkg/database"
)

func main() {
    // Configurar MongoDB
    client, err := database.Connect()
    if err != nil {
        panic(err)
    }
    defer client.Disconnect()
    
    // Inicializar repositorios
    authRepo := auth.NewRepository(client)
    galleryRepo := gallery.NewRepository(client)
    
    // Inicializar handlers
    authHandler := auth.NewHandler(authRepo)
    galleryHandler := gallery.NewHandler(galleryRepo)
    
    // Configurar router
    r := gin.Default()
    
    // Rutas públicas
    r.POST("/api/v1/auth/register", authHandler.Register)
    r.POST("/api/v1/auth/login", authHandler.Login)
    
    // Rutas protegidas
    protected := r.Group("/api/v1")
    protected.Use(middleware.JWTAuthMiddleware())
    {
        protected.POST("/gallery", galleryHandler.UploadImage)
        protected.GET("/gallery", galleryHandler.GetImages)
    }
    
    // Iniciar servidor
    r.Run(config.ServerAddress)
}

8. Documentación con Swagger

8.1 Anotar endpoints para Swagger

// internal/auth/handler.go

// Register godoc
// @Summary Registrar nuevo usuario
// @Description Crea una nueva cuenta de usuario
// @Tags auth
// @Accept json
// @Produce json
// @Param input body models.RegisterRequest true "Datos de registro"
// @Success 201 {object} map[string]string
// @Failure 400 {object} map[string]string
// @Failure 409 {object} map[string]string
// @Failure 500 {object} map[string]string
// @Router /api/v1/auth/register [post]
func (h *Handler) Register(c *gin.Context) {
    // ... implementación
}

// Login godoc
// @Summary Iniciar sesión
// @Description Autentica un usuario y devuelve un token JWT
// @Tags auth
// @Accept json
// @Produce json
// @Param input body models.LoginRequest true "Credenciales"
// @Success 200 {object} map[string]string
// @Failure 400 {object} map[string]string
// @Failure 401 {object} map[string]string
// @Failure 500 {object} map[string]string
// @Router /api/v1/auth/login [post]
func (h *Handler) Login(c *gin.Context) {
    // ... implementación
}

8.2 Configurar Swagger en main.go

// cmd/server/main.go
import (
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    _ "github.com/tu-usuario/gallery-api/docs"
)

// @title API de Galería
// @version 1.0
// @description API para gestión de galería de imágenes con autenticación JWT
// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @host localhost:8080
// @BasePath /api/v1
func main() {
    r := gin.Default()
    
    // Configurar Swagger
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
    // ... resto de la configuración
}

8.3 Generar documentación

swag init -g cmd/server/main.go

9. Despliegue en Linux

9.1 Compilar para producción

# Compilación optimizada
GOOS=linux GOARCH=amd64 go build -o gallery-api cmd/server/main.go

9.2 Configurar systemd

# /etc/systemd/system/gallery-api.service
[Unit]
Description=Gallery API Service
After=network.target

[Service]
User=gallery
Group=gallery
WorkingDirectory=/opt/gallery-api
ExecStart=/opt/gallery-api/gallery-api
Restart=always
EnvironmentFile=/opt/gallery-api/.env

[Install]
WantedBy=multi-user.target

9.3 Configurar Nginx como proxy inverso

# /etc/nginx/sites-available/gallery-api
server {
    listen 80;
    server_name api.tudominio.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    
    location /uploads/ {
        alias /opt/gallery-api/uploads/;
    }
    
    location /swagger/ {
        proxy_pass http://localhost:8080/swagger/;
    }
}

10. Conclusión

Hemos construido una API REST completa para una galería de imágenes con:

Mejoras posibles: