go-micro

A reference microservice template built on the shared platform package git.hayshin.dev/platform/go-pkg. It ships a complete Item CRUD gRPC service with a transactional outbox → NATS JetStream event flow, so you can clone it, rename the sample domain, and start building.

What it demonstrates:

• gRPC API (item.v1.ItemService) with the platform interceptor stack (grpcstack.CoreConfig): error mapping, metadata, tracing, metrics, logging, health, and reflection.
• Layered architecture: transport → service → repository → entity.
• PostgreSQL access via sqlc-generated queries and explicit transactions (pgtx.Manager.DoTx).
• Atomic domain writes + event emission through the transactional outbox (pgoutbox), relayed to NATS JetStream (natsoutbox).
• Config from the environment (config.Load), client lifecycle (clients.NewList), a telemetry server with health probes, and goose migrations.

Layout

.
├── api/proto/item/v1/         # protobuf source (item + item_api)
├── pkg/grpcapi/item/v1/       # generated gRPC/protobuf Go (importable)
├── cmd/
│   ├── server/                # service entrypoint (srv.Run → app.Run)
│   └── migrator/              # migrations entrypoint (up|down|status)
├── internal/
│   ├── api/grpc/itemapiv1/    # gRPC controller + proto<->entity converters
│   ├── app/                   # config, wiring (app.go), modules/, migrator
│   ├── db/                    # sqlc queries + schema
│   ├── entity/                # domain models
│   ├── gen/pgqueries/         # generated sqlc code
│   ├── migrations/pg/         # goose migrations
│   ├── repository/            # itemrepo port + pg impl + mocks
│   └── service/item/          # business logic
├── tests/                     # integration suite (build tag: integration)
├── scripts/rename.sh          # rebrand the sample domain
├── example.env                # sample configuration
└── devenv.nix                 # service identity override

Quick start

This module uses the released git.hayshin.dev/platform/go-pkg Go module. For private module access, configure Go once if needed:

go env -w GOPRIVATE=git.hayshin.dev GONOSUMDB=git.hayshin.dev

Then:

devenv shell             # enter the dev environment (or prefix: devenv shell <cmd>)
compose-up               # start postgres + nats
migrate up               # apply migrations (service + outbox)
run                      # start the gRPC server on :50051

# In another shell:
grpcurl                  # calls ItemService.CreateItem via reflection

Run help inside the dev shell for the full command list (gen, proto, sqlc, mocks, lint, test, test-integration, migrate, compose-up, rename, ...). devenv.yaml imports the reusable microservice profile from the remote go-pkg input; local devenv.nix only overrides service identity. docker-compose.yaml extends services from the shared go-pkg Docker Compose file. compose-up/compose-down resolve that file from the Go module cache via go list and export GO_PKG_DOCKER_COMPOSE for Compose.

Testing

test-unit          # unit tests (no infrastructure)
test-integration   # starts shared go-pkg Docker deps, then runs integration tests
test               # unit and integration tests

The integration suite uses git.hayshin.dev/platform/go-pkg/runtime/integrationtest to start PostgreSQL and NATS from the released go-pkg module, then starts the service in-process and exercises the full CRUD surface plus the outbox event flow.

Code generation

After editing .proto or .sql files, regenerate:

gen        # proto (buf) + sqlc + mocks (go generate)

Rename the sample domain

Replace the item sample with your own aggregate:

./scripts/rename.sh --domain order
./scripts/rename.sh --domain order --module git.example.com/team/orders

It rewrites identifiers and paths, then regenerates code. Review the diff and run go mod tidy && go build ./....

Configuration

All configuration is read from environment variables — see example.env. Key groups: GRPC_*, TELEMETRY_*, PG_*, NATS_*.