Documentos

GopherLIght

Olá pessoal, primeiro gostaria de agradecer por escolherem usar nosso projeto. Mesmo sendo pequeno, fizemos isso com muito entusiasmo! Para começar a usá-lo você primeiro precisa instalá-lo, vamos supor que você já o tenha. Em seguida instale os módulos principais do framework, que são req e roteador

go get github.com/BrunoCiccarino/GopherLight/router
go get github.com/BrunoCiccarino/GopherLight/req

Já baixou? Ufa! Agora podemos fazer nosso primeiro hello world.

package main

import (
    "fmt"
    "github.com/BrunoCiccarino/GopherLight/router"
    "github.com/BrunoCiccarino/GopherLight/req"
)


func main() {
    app := router.NewApp()

    // Define a route that responds to a GET request at "/hello".
    app.Get("/hello", func(r *req.Request, w *req.Response) {
        w.Send("Hello, World!")
    })

    fmt.Println("Server listening on port 3333")
    app.Listen(":3333")
}

Muito simples, certo? E podemos fazer muito mais com GopherLight. Continue lendo para obter uma análise completa dos métodos HTTP e de nossas ferramentas de solicitação e resposta.

Métodos HTTP suportados
Aqui está a lista de métodos HTTP que você pode usar com router.App. Cada um deles permite configurar rotas para lidar com diferentes tipos de solicitações. Vamos mergulhar!

PEGAR

• Uso: app.Get(caminho, manipulador)

Recupera dados sem modificar nada.
Exemplo: buscando uma lista de itens ou lendo detalhes do usuário.

PUBLICAR

• Uso: app.Post(caminho, manipulador)

Envia dados para criar um novo recurso.
Exemplo: Enviando um formulário ou adicionando um novo item a uma lista.

COLOCAR

Uso: app.Put(caminho, manipulador)

Atualiza ou substitui um recurso. É uma ação de “substituir”.
Exemplo: Atualizando um perfil de usuário completo.

EXCLUIR

Uso: app.Delete(caminho, manipulador)

Exclui um recurso.
Exemplo: Removendo um usuário ou excluindo uma postagem.

CORREÇÃO

Uso: app.Patch(caminho, manipulador)

Atualiza parcialmente um recurso sem substituir tudo.
Exemplo: Atualizando apenas o e-mail em um perfil de usuário.

OPÇÕES

Uso: app.Options(caminho, manipulador)

Retorna métodos HTTP permitidos para um URL, principalmente para solicitações de simulação de CORS.

CABEÇA

Uso: app.Head(caminho, manipulador)

Como GET, mas sem corpo de resposta. Use-o para verificar se existe um recurso.

CONECTAR e RASTREAR

Uso: app.Connect(caminho, manipulador), app.Trace(caminho, manipulador)

Métodos avançados: CONNECT configura um túnel (para SSL) e TRACE é para depuração, ecoando a solicitação.

Trabalhando com req.Request e req.Response

Agora que você viu as rotas, vamos falar sobre os objetos Request e Response, seus ajudantes essenciais para lidar com solicitações recebidas e enviar respostas.

Solicitar

Cada manipulador de solicitação recebe um objeto Request carregado com informações sobre a solicitação recebida. Aqui está o que você pode fazer com isso:

• Parâmetros de consulta: obtenha parâmetros de consulta com .QueryParam("key").
• Cabeçalhos: acesse os cabeçalhos usando .Header("key").
• Body as String: pegue o corpo da solicitação com .BodyAsString().

Exemplo:

app.Get("/greet", func(r *req.Request, w *req.Response) {
    name := r.QueryParam("name")
    if name == "" {
        name = "stranger"
    }
    w.Send("Hello, "   name   "!")
})

Resposta

O objeto Response ajuda você a enviar uma resposta de volta ao cliente. Aqui está o que você pode fazer:

• Enviar texto: .Send(data string) escreve texto simples de volta.
• Definir status: .Status(code) define o status HTTP.
• Enviar JSON: .JSON(data) serializa um objeto Go para JSON e o envia.
• Tratar erros: .JSONError(message) envia uma resposta de erro no formato JSON.

Exemplo:

app.Get("/user", func(r *req.Request, w *req.Response) {
    user := map[string]string{"name": "Gopher", "language": "Go"}
    w.JSON(user)
})

Middlewares

Temos um lote de middlewares prontos para você adicionar algumas funcionalidades importantes ao seu aplicativo da web Go. Cada um desses middlewares traz sua própria magia: segurança, registro, tempos limite e muito mais! Vamos dividi-los um por um. ?

Middleware de autenticação (JWT)

Nosso AuthMiddleware ajuda a proteger suas rotas com JSON Web Tokens (JWT). É flexível, permitindo personalizar a chave secreta, o tratamento de erros e o método de extração de token.

Configurar
Para começar, defina suas configurações de JWT usando JWTConfig:

• SecretKey: a chave secreta para assinar JWTs.
• SigningMethod: o algoritmo de assinatura JWT.
• ErrorHandler: manipulador de erros personalizado para lidar com erros de autenticação (opcional).
• TokenExtractor: extrai o token do cabeçalho da solicitação (opcional).

Exemplo

import (
    "github.com/BrunoCiccarino/GopherLight/middleware"
)

config := middleware.JWTConfig{
    SecretKey: []byte("your_secret_key"),
}
app.Use(middleware.NewAuthMiddleware(config))

Middleware CORS

Precisa permitir solicitações de origem cruzada? Sem problemas! Nosso CORSMiddleware define as configurações de Cross-Origin Resource Sharing (CORS) para tornar sua API acessível de outros domínios.

Opções de configuração

• AllowOrigin: defina como "*" para permitir qualquer origem ou especificar um domínio (por exemplo, "http://example.com").
• AllowMethods: quais métodos HTTP são permitidos? As escolhas comuns incluem "GET", "POST", etc.
• AllowHeaders: Especifique quais cabeçalhos os clientes podem usar.
• AllowCredentials: defina como verdadeiro se desejar que cookies ou autenticação HTTP sejam incluídos.
• ExposeHeaders: permite que o cliente leia cabeçalhos específicos da resposta.
• MaxAge: tempo de cache (em segundos) para solicitações de simulação.

Exemplo

corsOptions := middleware.CORSOptions{
    AllowOrigin: "*",
    AllowMethods: []string{"GET", "POST"},
}
app.Use(middleware.CORSMiddleware(corsOptions))

Middleware CSRF

Nosso CSRFMiddleware protege contra falsificação de solicitação entre sites, validando um token CSRF enviado com cada solicitação. Use GenerateCSRFToken() para criar um token seguro e, em seguida, valide-o com sua própria função isValidToken.

Exemplo

app.Use(middleware.CSRFMiddleware(func(token string) bool {
    return token == "your_valid_token"
}))

E não se esqueça de gerar tokens com:

csrfToken := middleware.GenerateCSRFToken()

Middleware de registro

Quer acompanhar o que está acontecendo no seu servidor? LoggingMiddleware registra cada solicitação, incluindo o método, caminho e tempo gasto. É uma ótima maneira de se manter informado sobre o desempenho do aplicativo e qualquer atividade incomum.

Exemplo

app.Use(middleware.LoggingMiddleware)

Cada solicitação será registrada assim:

• Iniciado: registra o horário de início da solicitação.
• Concluído: registra quando a solicitação termina, incluindo a duração.

Middleware de tempo limite

Evite essas esperas intermináveis ​​definindo limites de tempo no processamento de solicitações com TimeoutMiddleware. Este middleware cancelará a solicitação se ela não for concluída a tempo, enviando um status 504 Gateway Timeout para o cliente.

Exemplo

import (
    "time"
    "github.com/BrunoCiccarino/GopherLight/middleware"
)

timeout := 2 * time.Second
app.Use(middleware.TimeoutMiddleware(timeout))

A interface do plug-in

A interface do plugin é super simples, mas super poderosa. Oferece um único método: registrar-se. Isso permite que você se conecte ao sistema de roteamento do aplicativo para adicionar as rotas necessárias, seja um novo endpoint de API, um webhook ou qualquer outra coisa que você possa imaginar.

O método de registro
Aqui está a parte mágica da interface do plugin:

type Plugin interface {
    Register(route func(method, path string, handler func(req *req.Request, res *req.Response)))
}

O método Register aceita uma função de rota que permite definir novas rotas em seu plugin especificando:

• método: método HTTP (por exemplo, "GET", "POST", etc.)
• caminho: o caminho da rota (por exemplo, "/my-plugin-route")
• handler: A função a ser executada quando a rota é atingida. Esta função recebe:
  • req: O objeto de solicitação com acesso aos parâmetros de consulta, cabeçalhos e corpo.
  • res: O objeto de resposta para enviar dados de volta ao cliente.

Plug-in de exemplo

Digamos que você queira criar um plugin que adicione um endpoint simples em /hello-plugin para cumprimentar os usuários. Esta seria a aparência do plugin:

package main

import (
    "github.com/BrunoCiccarino/GopherLight/plugins"
    "github.com/BrunoCiccarino/GopherLight/req"
)

type HelloPlugin struct{}

// Register adds a new route for the HelloPlugin.
func (p *HelloPlugin) Register(route func(method, path string, handler func(req *req.Request, res *req.Response))) {
    route("GET", "/hello-plugin", func(req *req.Request, res *req.Response) {
        res.Send("Hello from the HelloPlugin!")
    })
}

Adicionando o plugin ao seu aplicativo

Para carregar um plugin, basta criar uma instância e chamar Register na configuração principal do seu aplicativo:

package main

import (
    "github.com/BrunoCiccarino/GopherLight/router"
)

func main() {
    app := router.NewApp()
    helloPlugin := &HelloPlugin{}
    helloPlugin.Register(app.Route)

    app.Listen(":3333")
}

Personalizando seus plug-ins

Cada plugin pode adicionar quantas rotas forem necessárias. Basta chamar route várias vezes em sua função Register para definir pontos de extremidade adicionais. Use diferentes métodos, caminhos e manipuladores HTTP para moldar a funcionalidade do seu plug-in da maneira que desejar.