Simulações codegen

Uma simulação codegen é um servidor Go gerado: o motor lê o seu spec e escreve handlers tipados para cada operação. Recém-gerado, cada handler devolve o mesmo mock gerado que qualquer outro tipo de simulação serve. A diferença é que você pode abrir o arquivo e assumir o controle, uma operação por vez, onde uma resposta precisar de lógica de verdade, estado ou cálculo. O spec nunca sai do seu repositório, o que também livra ele de qualquer limite de upload.

Do spec ao serviço

Um comando gera um pacote de serviço a partir de um 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 e registro gerados - nunca edite
  service.go       # a sua lógica de negócio - nunca é sobrescrita
  middleware.go    # o seu middleware - nunca é sobrescrito
  setup/
    codegen.yml    # o que é gerado
    config.yml     # comportamento em tempo de execução
    context.yml    # valores para os dados gerados
    openapi.json   # o spec

Essa separação é o contrato: gen.go é gerado de novo sempre que o spec muda, service.go e middleware.go são escritos uma vez e continuam seus. Atualizar a API é atualizar o spec e rodar go generate ./..., e a sua lógica sobrevive a cada regeneração.

Um handler quando você precisar

Cada operação ganha um método no service.go. Devolva nil, nil e o mock gerado responde, que é por isso que um serviço codegen novo se comporta como qualquer outra simulação. Assuma o controle onde importa:

func (s *service) GetPetByID(ctx context.Context, opts *GetPetByIDServiceRequestOptions) (*GetPetByIDResponseData, error) {
    resp, err := opts.GenerateResponse()   // parte do mock gerado
    if err != nil {
        return nil, err
    }
    resp.Body.ID = opts.PathParams.PetId   // depois faça ele se comportar
    resp.Body.Name = "Custom Pet"
    return resp, nil
}

As requisições e as respostas são tipadas a partir do spec, então o compilador pega o que um mock escrito na mão deixaria passar calado. O middleware.go é a mesma ideia um nível acima: autenticação, log e reescrita de requisição para o serviço inteiro.

Configuração

Tudo que é configurável fica em setup/:

• codegen.yml controla a geração em si: quais handlers existem, se o middleware.go é gerado, a filtragem.
• config.yml é a mesma configuração de tempo de execução que todo tipo de simulação usa: latência, injeção de erro, um upstream com queda para o mock, cache, replay. As opções batem com a página Configurações do serviço.
• context.yml dá forma aos dados gerados, exatamente como em todo o resto.

As referências completas ficam junto do motor: modo codegen e configuração de codegen.

Rodar e publicar

O go build produz um binário que se basta: rode local, no CI, ou em qualquer máquina sem dependência de runtime. Para uma URL hospedada, o modo codegen do GitHub Action compila e faz o deploy do projeto a cada push, com URLs por branch junto.

Comece pelo template, que já vem com CI, o explorador de API e serviços de exemplo prontos: mockzilla-codegen-template

Quando codegen é o tipo certo

Vá nele quando o mock tiver que se comportar: validar uma assinatura, manter um contador, devolver campos da requisição com cálculo aplicado, exigir autenticação. Para tudo que fica aquém disso, o portable chega lá sem nenhum código, e os dois dividem a configuração, então começar portable e gerar depois não perde nada.