Go JSON Responses

Pacote Go simples e eficiente para padronizar respostas JSON em APIs REST.

Instalação

go get github.com/brunohfonseca/gojsonresponses

Uso

Importe o pacote no seu controlador ou handler:

import "github.com/brunohfonseca/gojsonresponses"

Resposta de Sucesso

Use a função Success para retornar uma resposta positiva (2xx).

func GetUser(w http.ResponseWriter, r *http.Request) {
    user := User{Name: "Bruno", ID: 1}
    
    // w: http.ResponseWriter
    // statusCode: int
    // message: string
    // data: interface{}
	responses.Success(w, http.StatusOK, "Usuário encontrado", user)
}

Saída JSON:

{
  "status": 200,
  "message": "Usuário encontrado",
  "data": {
    "name": "Bruno",
    "id": 1
  }
}

Resposta de Erro

Use a função Error para retornar erros (4xx, 5xx).

func CreateUser(w http.ResponseWriter, r *http.Request) {
    err := errors.New("email inválido")
    
    // w: http.ResponseWriter
    // statusCode: int
    // message: string
    // error: interface{}
	responses.Error(w, http.StatusBadRequest, "Falha ao criar usuário", err.Error())
}

Saída JSON:

{
  "status": 400,
  "message": "Falha ao criar usuário",
  "error": "email inválido"
}

Resposta Genérica

Para maior controle, você pode usar a função JSON diretamente.

responses.JSON(w, 200, map[string]string{"foo": "bar"})

Estrutura da Resposta

Todas as respostas padronizadas seguem esta estrutura:

type Response struct {
    Status  int         `json:"status"`
    Message string      `json:"message,omitempty"`
    Data    interface{} `json:"data,omitempty"`
    Error   interface{} `json:"error,omitempty"`
}

Compatibilidade com Frameworks

Este pacote utiliza a interface padrão http.ResponseWriter, sendo nativamente compatível com a biblioteca padrão net/http e roteadores como Chi, Gorilla Mux e HttpRouter.

Exemplo com Gin

No Gin, você pode passar o c.Writer:

func(c *gin.Context) {
    responses.Success(c.Writer, http.StatusOK, "Sucesso", nil)
}

Exemplo com Echo

No Echo, use o c.Response().Writer:

func(c echo.Context) error {
    responses.Success(c.Response().Writer, http.StatusOK, "Sucesso", nil)
    return nil
}

Nota sobre Fiber

Frameworks baseados em fasthttp (como Fiber) não usam net/http e, portanto, não são compatíveis diretamente com este pacote sem o uso de adaptadores.