goserve

goserve es una biblioteca de Go diseñada para simplificar la creación de aplicaciones backend o servicios que interactúan con solicitudes HTTP. Aprovecha el poderoso enrutador gorilla/mux para proporcionar flexibilidad, rendimiento y escalabilidad mientras se adhiere a las mejores prácticas en desarrollo de servidores.

🛠️ Requisitos Previos

Antes de usar goserve, asegúrate de tener lo siguiente instalado:

Lenguaje de Programación Go 👉 Instalar Go ✅ Verificar instalación:
```
go version
```
Git (Sistema de Control de Versiones) 👉 Instalar Git ✅ Verificar instalación:
```
git --version
```
Configuración del Entorno Añade binarios de Go a tu PATH:
```
export PATH="$HOME/go/bin:$PATH"
```
Añade esta línea a tu archivo de configuración de shell (p. ej., .bashrc, .zshrc) para persistirla.

Herramienta oapi-codegen (para integración OpenAPI/Swagger):

go install github.com/deepmap/oapi-codegen/v2/cmd/[email protected]

📦 Instalación

Instala la herramienta CLI goserve-generator:

go install github.com/softwareplace/goserve/cmd/goserve-generator@latest

O añade la biblioteca a tu proyecto Go:

go get -u github.com/softwareplace/goserve

🚀 Uso

Genera un nuevo proyecto goserve:

goserve-generator -n <project-name> -u <github-username> [-r true|false] [-gi true|false]

Banderas

Bandera	Descripción	Requerido	Por Defecto
`-n`	Nombre de tu proyecto	✅ Sí
`-u`	Tu nombre de usuario de GitHub	✅ Sí
`-r`	Forzar reemplazo de archivos existentes	❌ No	false
`-gi`	Inicialización del proyecto Git	❌ No	true
`-cgf`	Plantilla del archivo de configuración de codegen	❌ No
`-gsv`	Versión específica de `goserve`	❌ No
`version`	Verificar versión actual	❌ No
`update`	Actualizar a la última versión lanzada	❌ No

Ejemplo

goserve-generator -n goserve-example -u myuser -r true -gi false -gsv <una tag o un commit hash>

✨ Características Principales

Servidor de Aplicación Backend: Inicia rápidamente un servidor backend con seguridad, control de acceso basado en roles y enrutamiento escalable.
Seguridad Mejorada: Soporte integrado para autenticación de clave API usando private.key y public.key.
Integración Swagger-UI: Documentación OpenAPI integrada a través de oapi-codegen.
Flexibilidad del Enrutador: Impulsado por gorilla/mux para enrutamiento limpio y RESTful.
Middleware Integrado: Soporte para autenticación, verificación de roles y manejo estructurado de errores.

🛡️ Variables de Entorno

Nombre de Variable	¿Requerido?	Por Defecto	Descripción
`CONTEXT_PATH`	No	`/`	Ruta base para todos los endpoints
`PORT`	No	`8080`	Puerto en el que escucha el servidor
`API_SECRET_KEY`	Sí*		Usado en encriptación/autenticación
`API_PRIVATE_KEY`	Sí*		Ruta del archivo private.key
`B_CRYPT_COST`	No	`10`	Factor de costo para bcrypt
`LOG_DIR`	No	`./.log`	Dónde se almacenan los archivos de log
`LOG_APP_NAME`	No		Usado en el nombre del archivo de log
`LOG_REPORT_CALLER`	No	`false`	Habilitar reporte de nombre de método en logs
`LOG_FILE_NAME_DATE_FORMAT`	No	`2006-01-02`	Formato de fecha para nombres de archivo de log
`JWT_ISSUER`	No		Nombre del emisor JWT
`JWT_CLAIMS_ENCRYPTION_ENABLED`	No	`true`	Encriptar claims dentro de JWT
`SWAGGER_RESURCE_ENABLED`	No	`true`	Habilitar recurso swagger

* Requerido solo si se usa security.Service

🧪 Ejemplo: Configuración Segura del Servidor

package main

import (
	log "github.com/sirupsen/logrus"
	"github.com/softwareplace/goserve/internal/handler"
	"github.com/softwareplace/goserve/internal/service/apiservice"
	"github.com/softwareplace/goserve/internal/service/login"
	"github.com/softwareplace/goserve/internal/service/provider"
	"github.com/softwareplace/goserve/logger"
	"github.com/softwareplace/goserve/security"
	"github.com/softwareplace/goserve/security/secret"
	"github.com/softwareplace/goserve/server"
)

func init() {
	logger.LogSetup()
}

var (
	userPrincipalService = login.NewPrincipalService()
	securityService      = security.New(
		userPrincipalService,
	)
	loginService   = login.NewLoginService(securityService)
	secretProvider = provider.NewSecretProvider()
	secretService  = secret.New(
		secretProvider,
		securityService,
	)
)

func main() {
	server.Default().
		LoginResourceEnabled(true).
		SecretKeyGeneratorResourceEnabled(true).
		LoginService(loginService).
		SecretService(secretService).
		SecurityService(securityService).
		EmbeddedServer(apiservice.Register).
		Get(apiservice.ReportCallerHandler, "/report/caller").
		SwaggerDocHandler("./internal/resource/pet-store.yaml").
		StartServer()
}

🔧 Configuración de Generación de Código (oapi-codegen)

Para personalizar la generación de código:

package: gen

generate:
  gorilla-server: true
  models: true

output: ./gen/api.gen.go

output-options:
  user-templates:
    imports.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/imports.tmpl
    param-types.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/param-types.tmpl
    request-bodies.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/request-bodies.tmpl
    typedef.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/typedef.tmpl
    gorilla/gorilla-register.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/gorilla/gorilla-register.tmpl
    gorilla/gorilla-middleware.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/gorilla/gorilla-middleware.tmpl
    gorilla/gorilla-interface.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/gorilla/gorilla-interface.tmpl

Generar Código

oapi-codegen --config path/to/config.yaml path/to/swagger.yaml

📋 Pruebas de API

Iniciar servidor

go run test/main.go

Abre http://localhost:8080/swagger/index.html

Iniciar en modo protegido

PROTECTED_API=true go run test/main.go

Sin token:

{
  "message": "No tienes permiso para acceder a este recurso",
  "statusCode": 401,
  "timestamp": 1742781093916
}

Con token válido:

curl -X GET 'http://localhost:8080/swagger/index.html' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: <your-jwt-token>'

📚 ¿Por Qué Elegir goserve?

Ya sea que estés construyendo microservicios o aplicaciones full-stack, goserve proporciona una base de servidor limpia, segura y lista para producción. Con integraciones poderosas y configuración fácil, goserve te ayuda a enfocarte en construir características, no en boilerplate.

🧩 Licencia

🎉 ¡Bienvenido a la Comunidad de Código Abierto!

El código abierto es más que solo código — ¡es un esfuerzo colaborativo impulsado por ti! Contribuir a goserve significa que te estás uniendo a una comunidad de desarrolladores que creen en hacer el software más accesible, seguro y escalable para todos.

¡Gracias por ser parte de este viaje! Juntos, creamos, innovamos y crecemos. 🚀