goserve

goserve é uma biblioteca Go projetada para simplificar a criação de aplicações backend ou serviços que interagem com requisições HTTP. Ela aproveita o poderoso roteador gorilla/mux para fornecer flexibilidade, performance e escalabilidade, aderindo às melhores práticas no desenvolvimento de servidores.

🛠️ Pré-requisitos

Antes de usar o goserve, certifique-se de ter o seguinte instalado:

Linguagem de Programação Go 👉 Instalar Go ✅ Verificar instalação:
```
go version
```
Git (Sistema de Controle de Versão) 👉 Instalar Git ✅ Verificar instalação:
```
git --version
```
Configuração do Ambiente Adicione os binários do Go ao seu PATH:
```
export PATH="$HOME/go/bin:$PATH"
```
Adicione esta linha ao seu arquivo de configuração do shell (ex: .bashrc, .zshrc) para torná-la persistente.

Ferramenta oapi-codegen (para integração OpenAPI/Swagger):

go install github.com/deepmap/oapi-codegen/v2/cmd/[email protected]

📦 Instalação

Instale a ferramenta CLI goserve-generator:

go install github.com/softwareplace/goserve/cmd/goserve-generator@latest

Ou adicione a biblioteca ao seu projeto Go:

go get -u github.com/softwareplace/goserve

🚀 Uso

Gere um novo projeto goserve:

goserve-generator -n <nome-do-projeto> -u <usuario-github> [-r true|false] [-gi true|false]

Flags

Flag	Descrição	Obrigatório	Padrão
`-n`	Nome do seu projeto	✅ Sim
`-u`	Seu nome de usuário do GitHub	✅ Sim
`-r`	Forçar substituição de arquivos	❌ Não	false
`-gi`	Inicialização do projeto Git	❌ Não	true
`-cgf`	Template do arquivo de config codegen	❌ Não
`-gsv`	Versão específica do `goserve`	❌ Não
`version`	Verificar versão atual	❌ Não
`update`	Atualizar para última versão	❌ Não

Exemplo

goserve-generator -n goserve-exemplo -u meuusuario -r true -gi false -gsv <versão de um tag ou um commit hash>

✨ Principais Recursos

Servidor de Aplicação Backend: Inicie um servidor backend com segurança, controle de acesso baseado em papéis e roteamento escalável.
Segurança Aprimorada: Suporte integrado para autenticação por chave API usando private.key e public.key.
Integração Swagger-UI: Documentação OpenAPI integrada via oapi-codegen.
Flexibilidade de Roteamento: Alimentado pelo gorilla/mux para roteamento RESTful limpo.
Middleware Integrado: Suporte para autenticação, verificação de papéis e tratamento estruturado de erros.

🛡️ Variáveis de Ambiente

Nome da Variável	Obrigatório?	Padrão	Descrição
`CONTEXT_PATH`	Não	`/`	Caminho base para todos os endpoints
`PORT`	Não	`8080`	Porta na qual o servidor escuta
`API_SECRET_KEY`	Sim*		Usado em criptografia/autenticação
`API_PRIVATE_KEY`	Sim*		Caminho do arquivo private.key
`B_CRYPT_COST`	Não	`10`	Fator de custo para bcrypt
`LOG_DIR`	Não	`./.log`	Onde os arquivos de log são armazenados
`LOG_APP_NAME`	Não		Usado na nomenclatura do arquivo de log
`LOG_REPORT_CALLER`	Não	`false`	Habilitar relatório de nome do método
`LOG_FILE_NAME_DATE_FORMAT`	Não	`2006-01-02`	Formato de data para nomes de arquivos log
`JWT_ISSUER`	Não		Nome do emissor JWT
`JWT_CLAIMS_ENCRYPTION_ENABLED`	Não	`true`	Criptografar claims dentro do JWT
`SWAGGER_RESURCE_ENABLED`	Não	`true`	Habilitar recurso swagger

* Obrigatório apenas se usar security.Service

🧪 Exemplo: Configuração de Servidor Seguro

package main

import (
	log "github.com/sirupsen/logrus"
	"github.com/softwareplace/goserve/internal/handler"
	"github.com/softwareplace/goserve/internal/service/apiservice"
	"github.com/softwareplace/goserve/internal/service/login"
	"github.com/softwareplace/goserve/internal/service/provider"
	"github.com/softwareplace/goserve/logger"
	"github.com/softwareplace/goserve/security"
	"github.com/softwareplace/goserve/security/secret"
	"github.com/softwareplace/goserve/server"
)

func init() {
	logger.LogSetup()
}

var (
	userPrincipalService = login.NewPrincipalService()
	securityService      = security.New(
		userPrincipalService,
	)
	loginService   = login.NewLoginService(securityService)
	secretProvider = provider.NewSecretProvider()
	secretService  = secret.New(
		secretProvider,
		securityService,
	)
)

func main() {
	server.Default().
		LoginResourceEnabled(true).
		SecretKeyGeneratorResourceEnabled(true).
		LoginService(loginService).
		SecretService(secretService).
		SecurityService(securityService).
		EmbeddedServer(apiservice.Register).
		Get(apiservice.ReportCallerHandler, "/report/caller").
		SwaggerDocHandler("./internal/resource/pet-store.yaml").
		StartServer()
}

🔧 Configuração de Geração de Código (oapi-codegen)

Para customizar a geração de código:

package: gen

generate:
  gorilla-server: true
  models: true

output: ./gen/api.gen.go

output-options:
  user-templates:
    imports.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/imports.tmpl
    param-types.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/param-types.tmpl
    request-bodies.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/request-bodies.tmpl
    typedef.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/typedef.tmpl
    gorilla/gorilla-register.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/gorilla/gorilla-register.tmpl
    gorilla/gorilla-middleware.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/gorilla/gorilla-middleware.tmpl
    gorilla/gorilla-interface.tmpl: https://raw.githubusercontent.com/softwareplace/goserve/refs/heads/main/resource/templates/gorilla/gorilla-interface.tmpl

Gerar Código

oapi-codegen --config caminho/para/config.yaml caminho/para/swagger.yaml

📋 Testando a API

Iniciar servidor

go run test/main.go

Abra http://localhost:8080/swagger/index.html

Iniciar em modo protegido

PROTECTED_API=true go run test/main.go

Sem token:

{
  "message": "You are not allowed to access this resource",
  "statusCode": 401,
  "timestamp": 1742781093916
}

Com token válido:

curl -X GET 'http://localhost:8080/swagger/index.html' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: <seu-jwt-token>'

📚 Por que Escolher goserve?

Seja você desenvolvendo microserviços ou aplicações full-stack, o goserve fornece uma base de servidor limpa, segura e pronta para produção. Com integrações poderosas e configuração fácil, o goserve ajuda você a focar na construção de funcionalidades—não em código boilerplate.

🧩 Licença

🎉 Bem-vindo à Comunidade Open Source!

Open source é mais do que apenas código — é um esforço colaborativo impulsionado por você! Contribuir com o goserve significa que você está se juntando a uma comunidade de desenvolvedores que acreditam em tornar o software mais acessível, seguro e escalável para todos.

Obrigado por fazer parte desta jornada! Juntos, criamos, inovamos e crescemos. 🚀