Extender backends Go exportados con middleware personalizado seguro

Qué sale mal cuando personalizas código exportado

El código exportado no es lo mismo que un repo Go escrito a mano. Con plataformas como AppMaster, el backend se genera a partir de un modelo visual (esquema de datos, procesos de negocio, configuración de API). Cuando vuelves a exportar, el generador puede reescribir grandes partes del código para que coincida con el modelo actualizado. Eso es bueno para mantener las cosas limpias, pero cambia cómo debes personalizar.

El fallo más común es editar archivos generados directamente. Funciona una vez y luego la siguiente exportación sobrescribe tus cambios o crea conflictos de fusión feos. Aún peor, pequeñas ediciones manuales pueden romper en silencio suposiciones que hace el generador (orden de las rutas, cadenas de middleware, validación de solicitudes). La app sigue compilando, pero el comportamiento cambia.

Una personalización segura significa que tus cambios son repetibles y fáciles de revisar. Si puedes re-exportar el backend, aplicar tu capa personalizada y ver claramente qué cambió, vas por buen camino. Si cada actualización se siente como arqueología, no lo estás haciendo bien.

Aquí están los problemas que típicamente ves cuando la personalización ocurre en el lugar equivocado:

• Tus ediciones desaparecen tras la re-exportación, o pasas horas resolviendo conflictos.
• Las rutas se desplazan y tu middleware ya no se ejecuta donde esperas.
• La lógica se duplica entre el modelo no-code y el código Go, y luego diverge.
• Un "cambio de una línea" se convierte en una bifurcación que nadie quiere tocar.

Una regla simple te ayuda a decidir dónde van los cambios. Si el cambio forma parte del comportamiento de negocio que los no-desarrolladores deberían poder ajustar (campos, validación, flujos, permisos), ponlo en el modelo no-code. Si es comportamiento de infraestructura (integración de auth personalizada, logging de peticiones, cabeceras especiales, límites de tasa), ponlo en una capa Go personalizada que sobreviva a re-exports.

Ejemplo: el logging de auditoría para cada petición suele ser middleware (código personalizado). Un nuevo campo obligatorio en un pedido suele pertenecer al modelo de datos (no-code). Mantén esa separación clara y las actualizaciones seguirán siendo predecibles.

Mapea el codebase: partes generadas vs tus partes

Antes de extender un backend exportado, dedica 20 minutos a mapear qué se regenerará al re-exportar y qué es realmente tuyo. Ese mapa es lo que mantiene las actualizaciones aburridas.

El código generado suele delatarse: comentarios en el encabezado como "Code generated" o "DO NOT EDIT", patrones de nombres consistentes y una estructura muy uniforme con pocos comentarios humanos.

Una forma práctica de clasificar el repo es ordenar todo en tres cubos:

• Generado (solo lectura): archivos con marcadores claros del generador, patrones repetidos o carpetas que parecen esqueleto de framework.
• De tu propiedad: paquetes que creaste, wrappers y configuración que controlas.
• Costuras compartidas: puntos de cableado pensados para registro (rutas, middleware, hooks), donde pueden ser necesarias pequeñas ediciones pero que deberían mantenerse mínimas.

Trata el primer cubo como solo lectura incluso si técnicamente puedes editarlo. Si lo cambias, asume que el generador lo sobrescribirá más tarde o que cargarás una deuda de fusión para siempre.

Haz la frontera real para el equipo escribiendo una nota corta y manteniéndola en el repo (por ejemplo, un README en la raíz). Manténlo simple:

"Generator-owned files: anything with a DO NOT EDIT header and folders X/Y. Our code lives under internal/custom (or similar). Only touch wiring points A/B, and keep changes there small. Any wiring edit needs a comment explaining why it can't live in our own package."

Esa nota evita que arreglos rápidos se conviertan en dolor permanente de actualización.

Dónde poner código personalizado para que las actualizaciones sean simples

La regla más segura es simple: trata el código exportado como solo lectura y pon tus cambios en un área personalizada claramente propia. Cuando vuelvas a exportar más tarde (por ejemplo desde AppMaster), quieres que el merge sea principalmente "reemplazar código generado, conservar código personalizado".

Crea un paquete separado para tus añadidos. Puede vivir dentro del repo, pero no debería mezclarse en paquetes generados. El código generado ejecuta la app core; tu paquete añade middleware, rutas y helpers.

Una disposición práctica:

• internal/custom/ para middleware, handlers y pequeños helpers
• internal/custom/routes.go para registrar rutas personalizadas en un solo lugar
• internal/custom/middleware/ para lógica de request/response
• internal/custom/README.md con algunas reglas para ediciones futuras

Evita editar el wiring del servidor en cinco lugares distintos. Apunta a un delgado "hook point" donde adjuntar middleware y registrar rutas extra. Si el servidor generado expone un router o cadena de handlers, conéctate ahí. Si no lo hace, añade un único archivo de integración cerca del entrypoint que llame a algo como custom.Register(router).

Escribe el código personalizado como si pudieras colocarlo en una exportación totalmente nueva mañana. Mantén las dependencias mínimas, evita copiar tipos generados cuando puedas y usa pequeños adaptadores en su lugar.

Paso a paso: añadir middleware personalizado de forma segura

El objetivo es poner la lógica en tu propio paquete y tocar el código generado en solo un lugar para cablearlo.

Primero, mantén el middleware estrecho: logging de solicitudes, una comprobación simple de auth, un límite de tasa o un ID de petición. Si intenta hacer tres trabajos, acabarás cambiando más archivos después.

Crea un paquete pequeño (por ejemplo, internal/custom/middleware) que no necesite conocer toda tu app. Mantén la superficie pública mínima: una función constructora que devuelva un envoltorio estándar de handler Go.

package middleware

import "net/http"

func RequestID(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Add header, log, or attach to context here.
		next.ServeHTTP(w, r)
	})
}

Ahora elige un punto de integración: el lugar donde se crea el router o el servidor HTTP. Registra tu middleware ahí, una vez, y evita dispersar cambios por rutas individuales.

Mantén el bucle de verificación corto:

• Añade una prueba enfocada usando httptest que verifique un resultado (código de estado o header).
• Haz una solicitud manual y confirma el comportamiento.
• Confirma que el middleware se comporta correctamente ante errores.
• Añade un comentario corto junto a la línea de registro explicando por qué existe.

Diff pequeño, un punto de wiring, re-exports sencillos.

Paso a paso: añadir un nuevo endpoint sin bifurcarlo todo

Trata el código generado como solo lectura y añade tu endpoint en un paquete personalizado pequeño que la app importe. Eso es lo que mantiene las actualizaciones razonables.

Empieza por escribir el contrato antes de tocar el código. ¿Qué acepta el endpoint (params de query, body JSON, headers)? ¿Qué devuelve (forma JSON)? Elige códigos de estado desde el principio para no terminar con comportamientos de "lo que funcionó".

Crea un handler en tu paquete personalizado. Manténlo aburrido: leer entrada, validar, llamar a servicios existentes o helpers de BD, escribir una respuesta.

Registra la ruta en el mismo punto de integración que usas para el middleware, no dentro de archivos de handlers generados. Busca dónde se ensambla el router durante el arranque y monta tus rutas personalizadas allí. Si el proyecto generado ya soporta hooks de usuario o registro personalizado, úsalo.

Una lista de verificación corta mantiene el comportamiento consistente:

• Valida entradas temprano (campos obligatorios, formatos, min/max).
• Devuelve siempre una forma de error uniforme (mensaje, código, detalles).
• Usa timeouts de contexto donde el trabajo pueda colgar (BD, llamadas de red).
• Loggea errores inesperados una sola vez y luego devuelve un 500 limpio.
• Añade una pequeña prueba que haga hit al nuevo route y verifique estado y JSON.

También confirma que el router registra tu endpoint exactamente una vez. El registro duplicado es una trampa común tras fusiones.

Patrones de integración que mantienen los cambios contenidos

Trata el backend generado como una dependencia. Prefiere la composición: cablea características alrededor de la app generada en vez de editar su lógica central.

Prefiere configuración y composición

Antes de escribir código, comprueba si el comportamiento se puede añadir mediante configuración, hooks o composición estándar. Middleware es un buen ejemplo: añádelo en el borde (router/pila HTTP) para que pueda eliminarse o reordenarse sin tocar la lógica de negocio.

Si necesitas un nuevo comportamiento (rate limiting, audit logging, request IDs), mantenlo en tu propio paquete y regístralo desde un único archivo de integración. En la revisión debería ser fácil explicar: "un paquete nuevo, un punto de registro".

Usa adaptadores para evitar filtrar tipos generados

Los modelos y DTOs generados suelen cambiar entre exportaciones. Para reducir el dolor de actualizaciones, traduce en el límite:

• Convierte tipos de petición generados en tus propios structs internos.
• Ejecuta la lógica de dominio usando solo tus structs.
• Convierte resultados de nuevo en tipos de respuesta generados.

Así, si los tipos generados cambian, el compilador te señala un solo lugar para actualizar.

Cuando realmente necesites tocar código generado, aísla ese cambio a un solo archivo de wiring. Evita ediciones en muchos handlers generados.

// internal/integrations/http.go
func RegisterCustom(r *mux.Router) {
    r.Use(RequestIDMiddleware)
    r.Use(AuditLogMiddleware)
}

Una regla práctica: si no puedes describir el cambio en 2-3 frases, probablemente está demasiado entrelazado.

Cómo mantener los diffs manejables con el tiempo

El objetivo es que una re-exportación no se convierta en una semana de conflictos. Mantén las ediciones pequeñas, fáciles de encontrar y de explicar.

Usa Git desde el primer día y separa las actualizaciones generadas de tu trabajo personalizado. Si las mezclas, no sabrás más tarde qué causó un bug.

Una rutina de commits que siga siendo legible:

• Un propósito por commit ("Add request ID middleware", no "fixes varios").
• No mezcles cambios solo de formato con cambios lógicos.
• Después de cada re-export, commitea la actualización generada primero y luego tus ajustes personalizados.
• Usa mensajes de commit que mencionen el paquete o archivo tocado.

Mantén un CHANGELOG_CUSTOM.md simple (o similar) listando cada personalización, por qué existe y dónde vive. Esto es especialmente útil con exports desde AppMaster porque la plataforma puede regenerar el código por completo y quieres un mapa rápido de lo que debe reaplicarse o revalidarse.

Reduce el ruido de diffs con formateo y reglas de lint consistentes. Ejecuta gofmt en cada commit y aplica las mismas comprobaciones en CI. Si el código generado usa un estilo particular, no lo "limpies" a mano a menos que estés dispuesto a repetir esa limpieza tras cada re-export.

Si tu equipo repite las mismas ediciones manuales después de cada exportación, considera un flujo de parches: exporta, aplica parches (o un script), ejecuta pruebas, despliega.

Planear actualizaciones: re-exportar, fusionar y validar

Las actualizaciones son más fáciles cuando tratas el backend como algo que puedes regenerar, no como algo que vas a mantener a mano para siempre. El objetivo es consistente: re-exportar código limpio y luego reaplicar tu comportamiento personalizado a través de los mismos puntos de integración cada vez.

Elige un ritmo de actualización que coincida con tu tolerancia al riesgo y la frecuencia de cambios en la app:

• Por release de la plataforma si necesitas arreglos de seguridad o funciones nuevas rápido
• Trimestral si la app es estable y los cambios son pequeños
• Solo cuando sea necesario si el backend raramente cambia y el equipo es pequeño

Cuando llegue el momento de actualizar, haz una re-exportación de prueba en una rama separada. Compila y ejecuta la versión recién exportada sola primero, así sabes qué cambió antes de involucrar tu capa personalizada.

Luego reaplica las personalizaciones a través de las costuras planificadas (registro de middleware, grupo de rutas personalizado, tu paquete custom). Evita edits quirúrgicos dentro de archivos generados. Si un cambio no puede expresarse mediante un punto de integración, eso es una señal para añadir una nueva costura una vez y usarla para siempre.

Valida con una lista corta de comprobaciones de regresión enfocadas en comportamiento:

• El flujo de auth funciona (login, refresh de token, logout)
• 3 a 5 endpoints clave devuelven los mismos códigos de estado y formas
• Un camino de error por endpoint (entrada inválida, falta de auth)
• Los jobs en background o tareas programadas siguen ejecutándose
• El endpoint de health/readiness responde OK en tu entorno de despliegue

Si añadiste middleware de auditoría, verifica que los logs aún incluyan ID de usuario y nombre de ruta para una operación de escritura después de cada re-export y merge.

Errores comunes que hacen las actualizaciones dolorosas

La forma más rápida de arruinar tu próxima re-exportación es editar archivos generados "solo esta vez". Parece inofensivo cuando arreglas un bug pequeño o añades una comprobación de header, pero meses después no recordarás qué cambió, por qué cambió o si el generador ahora produce la misma salida.

Otra trampa es esparcir código personalizado por todas partes: un helper en un paquete, una comprobación auth en otro, un tweak de middleware cerca del routing y un handler puntual en una carpeta aleatoria. Nadie lo posee y cada merge se convierte en una búsqueda del tesoro. Mantén los cambios en un pequeño número de lugares obvios.

Acoplamiento fuerte a internos generados

Las actualizaciones se vuelven dolorosas cuando tu código personalizado depende de structs internos generados, campos privados o detalles del layout de paquetes. Incluso un refactor pequeño en el código generado puede romper tu build.

Fronteras más seguras:

• Usa DTOs de request/response que controles para endpoints personalizados.
• Interactúa con capas generadas mediante interfaces o funciones exportadas, no tipos internos.
• Basa decisiones de middleware en primitivos HTTP (headers, método, path) cuando sea posible.

Omitir pruebas donde más se necesitan

Los bugs de middleware y routing consumen tiempo porque las fallas pueden parecer 401 aleatorios o "endpoint not found". Unas pocas pruebas enfocadas ahorran horas.

Un ejemplo realista: añades middleware de auditoría que lee el body de la request para loguearlo y de repente algunos endpoints reciben un body vacío. Una pequeña prueba que haga un POST a través del router y compruebe tanto el efecto de auditoría como el comportamiento del handler detecta esa regresión y da confianza tras una re-export.

Lista rápida antes del release

Antes de publicar cambios personalizados, haz un repaso rápido que te proteja durante la próxima re-export. Debes saber exactamente qué volver a aplicar, dónde vive y cómo verificarlo.

• Mantén todo el código personalizado en un paquete o carpeta claramente nombrada (por ejemplo, internal/custom/).
• Limita los puntos de contacto con el wiring generado a uno o dos archivos. Trátalos como puentes: registra rutas una vez, registra middleware una vez.
• Documenta el orden del middleware y la razón ("Auth antes de rate limiting" y por qué).
• Asegura que cada endpoint personalizado tenga al menos una prueba que demuestre que funciona.
• Escribe una rutina de actualización repetible: re-exportar, reaplicar capa personalizada, ejecutar pruebas, desplegar.

Si solo haces una cosa, haz la nota de actualización. Convierte "creo que está bien" en "podemos probar que sigue funcionando".

Ejemplo: añadir auditoría y un endpoint health

Imagina que exportaste un backend Go (por ejemplo, desde AppMaster) y quieres dos añadidos: un request ID más logging de auditoría para acciones admin, y un pequeño endpoint /health para monitorización. El objetivo es mantener tus cambios fáciles de reaplicar tras una re-export.

Para auditoría, pon el código en un lugar claramente propio como internal/custom/middleware/. Crea un middleware que (1) lea X-Request-Id o genere uno, (2) lo almacene en el contexto de la request y (3) loguee una línea corta de auditoría para rutas admin (método, path, ID de usuario si está disponible y resultado). Mantén una línea por petición y evita volcar payloads grandes.

Conéctalo en el borde, cerca de donde se registran las rutas. Si el router generado tiene un único archivo de setup, añade allí un pequeño hook que importe tu middleware y lo aplique solo al grupo admin.

Para /health, añade un handler pequeño en internal/custom/handlers/health.go. Devuelve 200 OK con un cuerpo corto como ok. No añadas auth a menos que tus monitores lo necesiten. Si lo haces, documentalo.

Para mantener el cambio fácil de reaplicar, estructura los commits así:

• Commit 1: Añadir internal/custom/middleware/audit.go y pruebas
• Commit 2: Cablear middleware en las rutas admin (diff mínimo posible)
• Commit 3: Añadir internal/custom/handlers/health.go y registrar /health

Tras una actualización o re-export, verifica lo básico: las rutas admin siguen requiriendo auth, los request IDs aparecen en logs admin, /health responde rápido y el middleware no añade latencia notable bajo carga ligera.

Próximos pasos: define un flujo de personalización mantenible

Trata cada exportación como una compilación fresca que puedes repetir. Tu código personalizado debería sentirse como una capa añadida, no como una reescritura.

Decide qué pertenece al código vs al modelo no-code la próxima vez. Reglas de negocio, formas de datos y lógica CRUD estándar suelen pertenecer al modelo. Integraciones puntuales y middleware específico de la empresa suelen pertenecer al código personalizado.

Si usas AppMaster (appmaster.io), diseña tu trabajo personalizado como una capa de extensión limpia alrededor del backend Go generado: mantén middleware, rutas y helpers en un pequeño conjunto de carpetas que puedas llevar entre re-exports, y deja intactos los archivos propiedad del generador.

Una comprobación final práctica: si un compañero puede re-exportar, aplicar tus pasos y obtener el mismo resultado en menos de una hora, tu flujo es sostenible.