Go Microservice Development

This skill provides guidance for creating and extending Go microservices using the internal service template and backend packages.

Overview

The microservice architecture follows Clean Architecture principles with Uber FX for dependency injection. All services share a common structure and use a set of internal infrastructure packages.

Architecture Overview

cmd/app/main.go              # Entry point with signal handling
config/config.go             # Configuration with fx.Out pattern
internal/
├── app/app.go               # fx bootstrap (CreateApp)
├── domain/                  # Business logic (DDD)
│   ├── fx.go                # Domain modules aggregation
│   └── {name}/              # Domain module
│       ├── fx.go            # Module registration
│       ├── consts/          # Permission scopes
│       ├── entities/        # Domain entities
│       ├── dto/             # Request/Response objects
│       ├── deps/            # Interface definitions
│       ├── errors/          # Domain-specific errors
│       ├── repository/      # Data access (postgres, http_clients)
│       ├── usecase/         # Business logic
│       ├── delivery/        # HTTP, gRPC, Kafka, RabbitMQ handlers
│       └── workers/         # Background tasks
└── infrastructure/          # Servers, clients, interceptors
pkg/                         # Local utilities (errors, httputil, ctxutil)

Domain Development Quick Guide

Creating New Domain - Checklist

1. [ ] Create directory: internal/domain/{name}/
2. [ ] Create subdirectories: entities/, dto/, deps/, repository/postgres/,
       usecase/buissines/, delivery/http/, errors/
3. [ ] Define entities in entities/entities.go
4. [ ] Define DTOs in dto/dto.go
5. [ ] Define interfaces in deps/dep.go
6. [ ] Implement repository in repository/postgres/repo.go
7. [ ] Implement usecase in usecase/buissines/uc.go
8. [ ] Implement HTTP handlers in delivery/http/handlers.go
9. [ ] Implement router in delivery/http/router.go
10. [ ] Create fx.Module in fx.go
11. [ ] Register module in internal/domain/fx.go
12. [ ] Validate: go test -run Test__CreateApp ./internal/app

For detailed file templates, consult examples/new-domain-checklist.md.

Layer Rules Summary

| Layer | Key Rules | Example Tags/Patterns | |-------|-----------|----------------------| | Entities | Use db/json tags, typed constants for enums | db:"column" json:"field" | | DTO | Separate Request/Response, use validate tags | validate:"required" | | Deps | Interface-only, context.Context first | Create(ctx, entity) error | | Repository | Return interface, use NamedExec/Get/SelectContext | func New(db) deps.Repo | | Usecase | Inject via interfaces, return DTOs, validate | Inject deps, return dto | | Delivery HTTP | fasthttp, httputil.WriteResponse | mapper.MapErrorToHttp(err) | | Delivery gRPC | OnStart/OnStop lifecycle | lc.Append(fx.Hook{...}) | | Workers | fx.Lifecycle, graceful shutdown via channels | ticker + done channel |

For detailed patterns and code examples, consult references/layer-patterns.md.

Internal Packages Quick Reference

Infrastructure Connectors

| Package | Purpose | FX Module | Key Interface | |---------|---------|-----------|---------------| | pgconnector | PostgreSQL | pgconnectorfx.PGConnectorFx | IDB | | redisconnector | Redis/Sentinel | redisfx.RedisFx | IRedis | | kafkaconnector | Kafka producer/consumer | Manual | IProducer, IConsumer | | rabbitconnector | RabbitMQ | Manual | IProducer, IConsumer | | vaultconnector | HashiCorp Vault | VaultFx | Connector | | s3 | S3 storage | S3Fx | IS3 | | clickhouseconnector | ClickHouse | clickhouseconnectorfx.ClickHouseConnectorFx | ICH |

Observability

| Package | Purpose | FX Module | Key Interface | |---------|---------|-----------|---------------| | logger | Structured logging (zap) | loggerfx.LoggerFx | ILogger | | tracer | OpenTelemetry tracing | tracerfx.TracerFx | ITracer | | meter | Prometheus metrics | meterFx | IMeter | | healthcheck | /healthz, /readyz probes | healthfx.HealthCheckFx | - |

Utilities

| Package | Purpose | |---------|---------| | configurator | YAML/ENV configuration with validation | | events | Event types for inter-service communication | | outbox | Transactional Outbox pattern | | memcache | In-memory cache (Cache, SnapshotCache, DeadlineCache) | | pagination | Pagination primitives | | access_level_guard | gRPC access control via protobuf annotations | | tlser | TLS certificates for gRPC | | wallet_streamer | Wallet subscription streaming |

For detailed usage with code examples, consult references/internal-packages.md.

FX Module Essentials

Module Registration Pattern

// internal/domain/{name}/fx.go
var Module = fx.Module(
    "{name}",
    fx.Provide(
        postgres.NewRepository,
        buissines.NewUseCase,
        http.NewHandlers,
        http.NewRouter,
    ),
)

Domain Aggregation

// internal/domain/fx.go
var Module = fx.Module(
    "domain",
    order.Module,
    user.Module,
    // Add new domain modules here
)

App Bootstrap

// internal/app/app.go
func CreateApp() fx.Option {
    return fx.Options(
        loggerfx.LoggerFx,
        healthfx.HealthCheckFx,
        pgconnectorfx.PGConnectorFx,
        redisfx.RedisFx,
        domain.Module,
        infrastructure.Module,
        fx.Provide(config.Out, context.Background),
        healthfx.ReadinessProbeFX,
    )
}

Workers with Lifecycle

// internal/domain/{name}/workers/fx.go
var Module = fx.Module(
    "{name}-workers",
    fx.Provide(NewWorker),
    fx.Invoke(registerLifecycle),
)

func registerLifecycle(lc fx.Lifecycle, w *Worker) {
    lc.Append(fx.Hook{
        OnStart: func(ctx context.Context) error { w.Start(ctx); return nil },
        OnStop:  func(ctx context.Context) error { w.Stop(); return nil },
    })
}

For advanced patterns (fx.As, fx.Annotate, fx.In/Out), consult references/fx-patterns.md.

Common Integration Scenarios

Adding HTTP Endpoint

1. Add handler method to delivery/http/handlers.go
2. Register route in delivery/http/router.go
3. Add usecase method if needed
4. Add repository method if needed
5. Validate: go test -run Test__CreateApp ./internal/app

Adding gRPC Endpoint

1. Update proto definition
2. Regenerate proto: protoc --go_out=. --go-grpc_out=. *.proto
3. Implement handler in delivery/grpc/handlers.go
4. Add usecase method if needed
5. Validate fx graph

External HTTP Client Integration

1. Create client: repository/http_clients/{service}/client.go
2. Define interface in deps/dep.go
3. Add config in config/config.go:

   ServiceName containers.RepositoryConfig `envPrefix:"SERVICE_NAME_"`
   

4. Register in fx.Module

Background Worker

1. Create worker: workers/worker.go with ticker + done channel
2. Create fx module: workers/fx.go with lifecycle hooks
3. Register in domain fx.Module

New Configuration Field

1. Add field to config/config.go with env/yaml/validate tags
2. Add to Result struct with fx.Out
3. Return in Out() function

For detailed step-by-step scenarios, consult references/template-structure.md.

Error Handling

Error Types and HTTP Codes

| Type | HTTP Code | Constructor | |------|-----------|-------------| | ValidationError | 400 | NewValidationError(msg) | | UnauthorizedError | 401 | NewUnauthorizedError(msg) | | PermissionError | 403 | NewPermissionError(msg) | | NotFoundError | 404 | NewNotFoundError(msg) | | ConflictError | 409 | NewConflictError(msg) |

Domain Errors Pattern

// internal/domain/{name}/errors/errors.go
package errors

import pkgerrors "service/pkg/errors"

var (
    OrderNotFound      = pkgerrors.NewNotFoundError("order not found")
    OrderAlreadyPaid   = pkgerrors.NewConflictError("order already paid")
    InvalidOrderAmount = pkgerrors.NewValidationError("invalid amount")
)

Handler Error Mapping

resp, err := h.uc.CreateOrder(ctx, &req)
if err != nil {
    status, msg := h.mapper.MapErrorToHttp(err)
    httputil.WriteErrorResponse(ctx, msg, status, err)
    return
}
httputil.WriteResponse(ctx, resp)

Local Utilities (pkg/)

| Package | Purpose | Key Functions | |---------|---------|---------------| | pkg/errors | Typed errors | NewValidationError, NewNotFoundError, NewMapper | | pkg/httputil | HTTP helpers | WriteResponse, WriteError, NewMiddlewareGroup | | pkg/ctxutil | Context helpers | FromCtx[T](ctx, key), HasInCtx(ctx, key) | | pkg/generator | Data generation | GenerateApiKey(prefix, length) | | pkg/hasher | Password hashing | HashPassword(pwd), ValidatePassword(hash, pwd) | | pkg/mapfn | Slice transforms | ConvertSlice[T,R](input, fn) | | pkg/timetools | Time formatting | FrontendTime (JSON-compatible) |

Context Keys (infrastructure/constants)

const (
    UserIDContextKey      = "user_id"
    MerchantIDContextKey  = "merchant_id"
    SessionInfoContextKey = "session_info"
    ApiKeyInfoContextKey  = "api_key_info"
)

Commands

# Run application
go run ./cmd/app

# Run all tests
go test ./...

# Validate fx dependency graph
go test -run Test__CreateApp ./internal/app

# Generate swagger docs
swag init -g ./cmd/app/main.go -o ./docs

# Download dependencies
go mod download

Additional Resources

Reference Files

For detailed patterns and techniques, consult:

• references/template-structure.md - Complete file/folder structure with examples
• references/internal-packages.md - Detailed package documentation
• references/fx-patterns.md - Advanced FX DI patterns
• references/layer-patterns.md - Layer rules with code examples

Example Files

Working examples in examples/:

• examples/new-domain-checklist.md - Step-by-step domain creation with copy-paste code