Simulaciones codegen

Una simulación codegen es un servidor Go generado: el motor lee tu spec y escribe handlers tipados para cada operación. Recién generado, cada handler devuelve el mismo mock generado que sirve cualquier otro tipo de simulación. La diferencia es que puedes abrir el archivo y tomar el control, una operación a la vez, donde una respuesta necesite lógica real, estado o cálculos. La spec nunca sale de tu repositorio, lo que además la libera de cualquier límite de subida.

De la spec al servicio

Un comando genera un paquete de servicio desde una spec:

go run github.com/mockzilla/mockzilla/v2/cmd/gen/service@latest \
  -name petstore \
  https://petstore3.swagger.io/api/v3/openapi.json

petstore/
  gen.go           # tipos, handlers y registro generados - nunca lo edites
  service.go       # tu lógica de negocio - nunca se sobrescribe
  middleware.go    # tu middleware - nunca se sobrescribe
  setup/
    codegen.yml    # qué se genera
    config.yml     # comportamiento en tiempo de ejecución
    context.yml    # valores para los datos generados
    openapi.json   # la spec

Esa separación es el contrato: gen.go se regenera cada vez que cambia la spec, service.go y middleware.go se escriben una vez y siguen siendo tuyos. Actualizar la API es actualizar la spec y correr go generate ./..., y tu lógica sobrevive a cada regeneración.

Un handler cuando lo necesitas

Cada operación recibe un método en service.go. Devuelve nil, nil y responde el mock generado, que es por lo que un servicio codegen recién creado se comporta como cualquier otra simulación. Toma el control donde importa:

func (s *service) GetPetByID(ctx context.Context, opts *GetPetByIDServiceRequestOptions) (*GetPetByIDResponseData, error) {
    resp, err := opts.GenerateResponse()   // parte del mock generado
    if err != nil {
        return nil, err
    }
    resp.Body.ID = opts.PathParams.PetId   // y después haz que se comporte
    resp.Body.Name = "Custom Pet"
    return resp, nil
}

Las solicitudes y las respuestas están tipadas desde la spec, así que el compilador atrapa lo que un mock escrito a mano dejaría pasar en silencio. middleware.go es la misma idea un nivel más arriba: autenticación, logging y reescritura de solicitudes para todo el servicio.

Configuración

Todo lo configurable vive en setup/:

• codegen.yml controla la generación misma: qué handlers existen, si se genera middleware.go, el filtrado.
• config.yml es la misma configuración en tiempo de ejecución que usa cualquier tipo de simulación: latencia, inyección de errores, un upstream con caída al mock, caché, replay. Las opciones coinciden con la página Ajustes del servicio.
• context.yml da forma a los datos generados, exactamente igual que en todos lados.

Las referencias completas viven junto al motor: modo codegen y configuración de codegen.

Correr y desplegar

go build produce un binario autocontenido: córrelo en local, en CI, o en cualquier máquina sin dependencias de runtime. Para una URL alojada, el modo codegen de la GitHub Action construye y despliega el proyecto en cada push, con URLs por rama incluidas.

Empieza desde la plantilla, que trae CI, el explorador de API y servicios de ejemplo listos: mockzilla-codegen-template

Cuándo codegen es la clase correcta

Recurre a él cuando el mock tenga que comportarse: validar una firma, llevar un contador, devolver campos de la solicitud con cálculos aplicados, exigir autenticación. Para todo lo que quede corto de eso, portable llega sin nada de código, y los dos comparten su configuración, así que empezar portable y generar después no pierde nada.