go-prototype

Prototipo Go mínimo con configuración vía viper, logging estructurado con slog y una API REST básica siguiendo una estructura hexagonal ligera.

Estructura principal

• src/cmd/: bootstrap y wiring de dependencias
• src/pkg/: carga de configuración y construcción del logger
• src/internal/core/: dominio, puertos de entrada y casos de uso
• src/internal/adapters/inbound/httpapi/: adaptador HTTP basado en net/http

Ejecutar localmente

cd /Users/oscar/projects/poc/go-prototype/src
go test ./...
go run ./cmd

Endpoints de ejemplo

• GET /health
• GET /hello
• GET /hello?name=Oscar
• GET /repository-data

Adaptadores de entrada

• inbound.adapters: [http, grpc] para ejecutar ambos al mismo tiempo.
• Compatibilidad legacy: inbound.adapter: http|grpc (un solo adaptador).
• El adaptador gRPC de ejemplo expone health check y reflection.

Ejemplo rápido para levantar gRPC por entorno:

cd /Users/oscar/projects/poc/go-prototype/src
APP_INBOUND_ADAPTER=grpc APP_GRPC_PORT=9091 go run ./cmd

Ejemplo rápido para levantar HTTP + gRPC por entorno:

cd /Users/oscar/projects/poc/go-prototype/src
APP_INBOUND_ADAPTERS=http,grpc APP_HTTP_PORT=8081 APP_GRPC_PORT=9091 go run ./cmd

Verificar health gRPC con grpcurl (si está instalado):

grpcurl -plaintext 127.0.0.1:9091 grpc.health.v1.Health/Check

Contrato gRPC del repositorio

El contrato del caso de uso de repositorio está en:

• src/api/proto/repository/v1/repository.proto

Ejemplo de invocación al método de repositorio:

grpcurl \
  -plaintext \
  -import-path /Users/oscar/projects/poc/go-prototype/src/api/proto \
  -proto repository/v1/repository.proto \
  -d '{}' \
  127.0.0.1:9091 \
  repository.v1.RepositoryService/ListItems

Configuración

El archivo de ejemplo vive en src/conf/config.yaml.

Autenticación OAuth2 configurable en HTTP (introspección):

export APP_HTTP_OAUTH2_ENABLED=true
export APP_HTTP_OAUTH2_INTROSPECTION_URL=http://127.0.0.1:8082/oauth2/introspect
export APP_HTTP_OAUTH2_CLIENT_ID=api-client
export APP_HTTP_OAUTH2_CLIENT_SECRET=api-secret
export APP_HTTP_OAUTH2_REQUIRED_SCOPES=read,repository

Nota: cuando OAuth2 está habilitado, GET /health queda público y el resto de rutas HTTP requieren Authorization: Bearer <token> válido.

Adaptadores de salida (repositorio)

• outbound.adapter: mock (default) usa datos estáticos en memoria.
• outbound.adapter: postgres consulta PostgreSQL en la tabla repository_items(id text, title text).
• outbound.adapter: mongodb consulta MongoDB en la colección repository_items.

Levantar PostgreSQL local con datos semilla:

cd /Users/oscar/projects/poc/go-prototype
docker compose up -d postgres

Levantar MongoDB local con datos semilla:

cd /Users/oscar/projects/poc/go-prototype
docker compose up -d mongodb

Probar API HTTP usando adaptador PostgreSQL:

cd /Users/oscar/projects/poc/go-prototype/src
APP_OUTBOUND_ADAPTER=postgres APP_INBOUND_ADAPTERS=http APP_HTTP_PORT=8081 go run ./cmd

En otra terminal:

curl --silent http://127.0.0.1:8081/repository-data

Probar API HTTP usando adaptador MongoDB:

cd /Users/oscar/projects/poc/go-prototype/src
APP_OUTBOUND_ADAPTER=mongodb APP_INBOUND_ADAPTERS=http APP_HTTP_PORT=8081 go run ./cmd

Ejemplo para usar PostgreSQL por entorno:

export APP_OUTBOUND_ADAPTER=postgres
export APP_OUTBOUND_POSTGRES_HOST=127.0.0.1
export APP_OUTBOUND_POSTGRES_PORT=5432
export APP_OUTBOUND_POSTGRES_USER=postgres
export APP_OUTBOUND_POSTGRES_PASSWORD=postgres
export APP_OUTBOUND_POSTGRES_DATABASE=go_prototype
export APP_OUTBOUND_POSTGRES_SSLMODE=disable

Ejemplo para usar MongoDB por entorno:

export APP_OUTBOUND_ADAPTER=mongodb
export APP_OUTBOUND_MONGODB_URI=mongodb://127.0.0.1:27017
export APP_OUTBOUND_MONGODB_DATABASE=go_prototype
export APP_OUTBOUND_MONGODB_COLLECTION=repository_items

Overrides por entorno:

export APP_HTTP_PORT=9090
export APP_GREETING_MESSAGE=Hola
export APP_LOGGING_FORMAT=text
export APP_INBOUND_ADAPTER=grpc
export APP_OUTBOUND_ADAPTER=postgres