How to Migrate a Java Application to Go

TL;DR

• Bottom line: Migrate service-by-service starting with a low-risk pilot microservice — replace Java class hierarchies with Go structs + interfaces, swap exceptions for explicit error returns, and use goroutines/channels instead of thread pools. Go produces a single static binary with sub-100ms startup vs. 5–10s for Spring Boot.
• Key tool/command: go mod init myproject && go build -o myservice ./cmd/myservice
• Watch out for: Translating Java inheritance hierarchies into Go — Go has no classes or inheritance; use composition via struct embedding and implicit interfaces instead.
• Works with: Go 1.22+ (1.26 current as of May 2026, 1.25 supported), Java 11–25 (source), any build system (Maven/Gradle source, go modules target).

Constraints

• Go has no exceptions — all error handling must use explicit return values; never use panic/recover for control flow.
• Go does not support class inheritance — use struct embedding for composition and implicit interfaces for polymorphism; do not attempt to replicate Java's extends keyword.
• Never introduce circular package dependencies — Go's compiler rejects them. Restructure using interfaces at the consumer side or flatten the package layout.
• Always propagate context.Context as the first parameter in functions that perform I/O — Go has no implicit request-scoped state like Spring's RequestContextHolder.
• Go maps must be initialized before write (make(map[K]V) or literal syntax) — var m map[K]V creates a nil map that panics on assignment.
• Run go vet ./... and go test -race ./... before every deployment — Go's static analysis and race detector catch concurrency bugs that Java's type system does not prevent.

Quick Reference

Decision Tree

START
+-- Is this a monolithic Java application?
|   +-- YES --> Break into service boundaries first, then migrate one service at a time
|   +-- NO (already microservices) v
+-- Does the service have heavy Java framework dependencies (Spring, Hibernate)?
|   +-- YES --> Map framework features to Go stdlib + lightweight libraries (see Quick Reference)
|   +-- NO v
+-- Is the service CPU-bound or I/O-bound?
|   +-- CPU-BOUND --> Go excels here -- goroutines + GOMAXPROCS for parallelism
|   +-- I/O-BOUND --> Use goroutines + channels for concurrent I/O (replaces CompletableFuture)
+-- Does the service use complex ORM patterns (JPA/Hibernate)?
|   +-- YES --> Replace with sqlx or pgx + raw SQL (Go favors explicit queries over magic ORM)
|   +-- NO v
+-- Does the team have Go experience?
|   +-- NO --> Start with a non-critical service as a pilot; invest 2-4 weeks in Go training first [src8]
|   +-- YES v
+-- DEFAULT --> Rewrite service in idiomatic Go: structs for data, interfaces for behavior, error returns for control flow

Decision Logic

Structured if/then rules an agent can apply once it has the user's answers to inputs_needed. Each rule resolves to a concrete recommendation.

If the Java app is a single large monolith with shared in-process state

—> Do not lift-and-shift to one Go binary. First carve service boundaries inside the monolith, then migrate the lowest-coupling service to Go as a pilot. [src5, src8]

If the codebase depends heavily on Spring Boot + JPA/Hibernate + Spring Security

—> Reconsider the migration ROI: map @RestController to net/http (Go 1.22+ routing), JPA to pgx/sqlx with hand-written SQL, and Spring DI to constructor injection — but budget for losing the ORM abstraction layer entirely. [src2, src3]

If concurrency performance was the primary motivation and the workload is I/O-bound

—> Re-evaluate first: Java 25 virtual threads close most of the goroutine gap for I/O-bound work, so the infra savings may not justify a rewrite. Migrate only if startup time, memory footprint, or single-binary deployment also matter. [src4, src8]

If the team has zero production Go experience

—> Run a 2-4 week Go training spike and migrate one non-critical service before committing to the full path; rushing leads to "Java-in-Go" (getter/setter structs, interface-for-everything, panic-as-exception). [src5, src8]

If the service runs in a CPU-limited container (Kubernetes requests/limits)

—> Target Go 1.25+ so GOMAXPROCS auto-respects the Cgroup CPU quota; on older Go, add go.uber.org/automaxprocs or you will hit kernel CPU throttling and tail-latency spikes. [src10]

If the goal is the smallest possible image and fastest cold start (serverless, scale-to-zero)

—> Go is the right target: build with CGO_ENABLED=0 into a FROM scratch image (~10-20MB, sub-100ms start) vs. ~200-400MB JVM images with multi-second startup. [src2, src5]

If the app relies on JVM-only ecosystem libraries (Kafka Streams, Spark, bytecode/reflection frameworks)

—> Keep those components on the JVM and migrate only the stateless request-handling services; Go has no equivalent runtime reflection or bytecode-manipulation power. [src1, src4]

Step-by-Step Guide

1. Initialize Go module and project structure

Create the Go project with a standard layout. Go projects use a flat, simple directory structure compared to Java's deep package hierarchy. [src1]

mkdir myservice && cd myservice
go mod init github.com/yourorg/myservice

# Standard Go project layout
mkdir -p cmd/myservice internal/handler internal/service internal/repository

myservice/
  cmd/myservice/main.go    # Entrypoint (like public static void main)
  internal/handler/         # HTTP handlers (like @RestController)
  internal/service/         # Business logic (like @Service)
  internal/repository/      # Data access (like @Repository)
  go.mod                    # Dependencies (like pom.xml / build.gradle)

Verify: go mod tidy runs without errors.

2. Convert Java classes to Go structs and interfaces

Replace class hierarchies with composition. Define small, focused interfaces (1–3 methods) and let structs satisfy them implicitly. [src1, src3]

// Java: public interface UserRepository { User findById(long id); }
// Go equivalent:
type UserRepository interface {
    FindByID(ctx context.Context, id int64) (*User, error)
}

// Java: public class User { private long id; private String name; }
// Go equivalent:
type User struct {
    ID   int64  `json:"id" db:"id"`
    Name string `json:"name" db:"name"`
}

// Java: public class PostgresUserRepo implements UserRepository { ... }
// Go equivalent (implicit interface satisfaction):
type PostgresUserRepo struct {
    db *sql.DB
}

func (r *PostgresUserRepo) FindByID(ctx context.Context, id int64) (*User, error) {
    var u User
    err := r.db.QueryRowContext(ctx, "SELECT id, name FROM users WHERE id = $1", id).
        Scan(&u.ID, &u.Name)
    if err != nil {
        return nil, fmt.Errorf("find user %d: %w", id, err)
    }
    return &u, nil
}

Verify: go vet ./... passes with no issues.

3. Replace exception handling with error returns

Convert try/catch blocks to Go's explicit error checking pattern. Wrap errors with context using fmt.Errorf("context: %w", err) for stack-trace-like debugging. [src1, src7]

// Go equivalent:
func (s *UserService) GetUser(ctx context.Context, id int64) (*UserDTO, error) {
    user, err := s.repo.FindByID(ctx, id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, fmt.Errorf("user %d not found: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("get user %d: %w", id, err)
    }
    return toDTO(user), nil
}

// Define sentinel errors (like custom exception classes)
var ErrNotFound = errors.New("not found")
var ErrForbidden = errors.New("forbidden")

Verify: go build ./... compiles; error paths are tested with if errors.Is(err, ErrNotFound).

4. Replace Spring DI with constructor injection

Go does not use annotation-based DI containers. Instead, wire dependencies explicitly through constructor functions. This eliminates runtime reflection and makes the dependency graph visible in main(). [src2, src3]

// Go equivalent: explicit constructor injection
type UserService struct {
    repo  UserRepository  // interface, not concrete type
    email EmailSender     // interface for testability
}

func NewUserService(repo UserRepository, email EmailSender) *UserService {
    return &UserService{repo: repo, email: email}
}

// Wire everything in main() -- this IS your DI container
func main() {
    db := connectDB()
    repo := repository.NewPostgresUserRepo(db)
    emailer := email.NewSMTPSender(smtpConfig)
    userSvc := service.NewUserService(repo, emailer)
    handler := handler.NewUserHandler(userSvc)

    mux := http.NewServeMux()
    mux.HandleFunc("GET /users/{id}", handler.GetUser)
    log.Fatal(http.ListenAndServe(":8080", mux))
}

Verify: Application starts and all dependencies are injected. go run ./cmd/myservice starts the server.

5. Convert Java thread pools to goroutines and channels

Replace ExecutorService, CompletableFuture, and synchronized blocks with goroutines and channels. [src1, src4]

// Go equivalent: goroutines with bounded concurrency
func processAll(ctx context.Context, tasks []Task) ([]Result, error) {
    results := make([]Result, len(tasks))
    errCh := make(chan error, 1)
    sem := make(chan struct{}, 10) // max 10 concurrent goroutines

    var wg sync.WaitGroup
    for i, task := range tasks {
        wg.Add(1)
        go func(i int, t Task) {
            defer wg.Done()
            sem <- struct{}{}        // acquire semaphore
            defer func() { <-sem }() // release semaphore

            result, err := process(ctx, t)
            if err != nil {
                select {
                case errCh <- err:
                default:
                }
                return
            }
            results[i] = result
        }(i, task)
    }

    wg.Wait()
    close(errCh)
    if err := <-errCh; err != nil {
        return nil, err
    }
    return results, nil
}

Verify: go test -race ./... passes — the race detector catches concurrent access bugs.

6. Set up HTTP server and middleware

Replace Spring Boot's embedded Tomcat with Go's net/http stdlib or a lightweight router (Chi, Echo). Middleware replaces Spring interceptors and filters. Go 1.22+ includes built-in pattern routing with path parameters, eliminating the need for third-party routers in many cases. [src1, src2]

// Java Spring: @RestController + @GetMapping
// Go equivalent using stdlib (Go 1.22+ pattern routing):
func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
    if err != nil {
        http.Error(w, "invalid id", http.StatusBadRequest)
        return
    }

    user, err := h.svc.GetUser(r.Context(), id)
    if err != nil {
        if errors.Is(err, service.ErrNotFound) {
            http.Error(w, "not found", http.StatusNotFound)
            return
        }
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

// Middleware (replaces Spring Filter/Interceptor)
func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
    })
}

Verify: curl http://localhost:8080/users/1 returns JSON. Server startup is <100ms.

7. Build and deploy the Go binary

Go compiles to a single static binary with no runtime dependencies. This replaces the JVM + JAR deployment model. Go 1.24+ automatically embeds version info from VCS tags into the binary. [src2, src5]

# Build for production (like mvn package -DskipTests)
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o myservice ./cmd/myservice

# Multi-stage Dockerfile (replaces JDK base image)
# FROM golang:1.24-alpine AS builder
# WORKDIR /app
# COPY go.mod go.sum ./
# RUN go mod download
# COPY . .
# RUN CGO_ENABLED=0 go build -o /myservice ./cmd/myservice
#
# FROM scratch               # <-- No OS, no runtime. ~10MB vs ~200MB+ for JVM
# COPY --from=builder /myservice /myservice
# ENTRYPOINT ["/myservice"]

# Compare image sizes:
# Java (Eclipse Temurin): ~200-400MB
# Go (from scratch):     ~10-20MB

Verify: ./myservice runs without JVM installed. Docker image is <20MB. Startup is <100ms.

Code Examples

Go: HTTP service with repository pattern (replaces Spring Boot REST API)

Full script: go-http-service-with-repository-pattern-replaces-s.go (94 lines)

// Input:  A Java Spring Boot @RestController + @Service + @Repository
// Output: Equivalent Go service with same API contract
package main
import (
    "context"
# ... (see full script)

Go: Concurrent worker pool (replaces Java ExecutorService)

Full script: go-concurrent-worker-pool-replaces-java-executorse.go (67 lines)

// Input:  Java ExecutorService with Callable tasks and Future results
// Output: Go worker pool with goroutines and channels
package main
import (
    "context"
# ... (see full script)

Go: Interface-based testing (replaces Mockito)

Full script: go-interface-based-testing-replaces-mockito.go (54 lines)

// Input:  Java unit test with Mockito mocks
// Output: Go test using interface-based test doubles (no framework needed)
package service
import (
    "context"
# ... (see full script)

Anti-Patterns

Wrong: Translating Java class hierarchy to Go with embedding as inheritance

// BAD -- treating embedding as inheritance (it's not)
type Animal struct {
    Name string
}
func (a *Animal) Speak() string { return "..." }

type Dog struct {
    Animal // This is NOT inheritance
}
func (d *Dog) Speak() string { return "Woof" }

// Bug: Animal.Speak() is still accessible and returns "..."
// No polymorphism: []Animal cannot hold Dog values

Correct: Use interfaces for polymorphism

// GOOD -- interfaces for polymorphic behavior
type Speaker interface {
    Speak() string
}

type Dog struct{ Name string }
func (d Dog) Speak() string { return "Woof" }

type Cat struct{ Name string }
func (c Cat) Speak() string { return "Meow" }

// Polymorphism via interface
func greetAll(speakers []Speaker) {
    for _, s := range speakers {
        fmt.Println(s.Speak())
    }
}

Wrong: Using panic/recover as try/catch

// BAD -- using panic for control flow (Java exception habit)
func findUser(id int64) *User {
    user, err := db.FindByID(id)
    if err != nil {
        panic(fmt.Sprintf("user not found: %d", id)) // Don't do this
    }
    return user
}

func handler(w http.ResponseWriter, r *http.Request) {
    defer func() {
        if r := recover(); r != nil {
            http.Error(w, "internal error", 500) // Catching panics like exceptions
        }
    }()
    user := findUser(42)
    json.NewEncoder(w).Encode(user)
}

Correct: Return errors explicitly

// GOOD -- explicit error returns (idiomatic Go)
func findUser(ctx context.Context, id int64) (*User, error) {
    user, err := db.FindByID(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("find user %d: %w", id, err)
    }
    return user, nil
}

func handler(w http.ResponseWriter, r *http.Request) {
    user, err := findUser(r.Context(), 42)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            http.Error(w, "not found", 404)
            return
        }
        http.Error(w, "internal error", 500)
        return
    }
    json.NewEncoder(w).Encode(user)
}

Wrong: Creating Java-style getter/setter methods

// BAD -- Java-style boilerplate (not idiomatic Go)
type User struct {
    name  string
    email string
}

func (u *User) GetName() string     { return u.name }
func (u *User) SetName(n string)    { u.name = n }
func (u *User) GetEmail() string    { return u.email }
func (u *User) SetEmail(e string)   { u.email = e }

Correct: Use exported fields directly

// GOOD -- exported fields, no getters/setters needed
type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// Only add methods when validation or side effects are needed:
func (u *User) SetEmail(email string) error {
    if !strings.Contains(email, "@") {
        return errors.New("invalid email")
    }
    u.Email = email
    return nil
}

Wrong: Over-using interfaces (Java interface-for-everything habit)

// BAD -- interface for a single concrete implementation
type UserServiceInterface interface {
    GetUser(ctx context.Context, id int64) (*User, error)
    CreateUser(ctx context.Context, u *User) error
    DeleteUser(ctx context.Context, id int64) error
}

type UserServiceImpl struct { /* fields */ }
// Unnecessary abstraction when only one implementation exists

Correct: Define interfaces at the consumer, not the provider

// GOOD -- define interfaces where they are used (consumer side)
// In the handler package:
type UserGetter interface {
    GetUser(ctx context.Context, id int64) (*User, error)
}

// The handler only depends on the methods it actually calls
type UserHandler struct {
    users UserGetter // Narrow interface, easy to test
}

// The concrete service satisfies this interface implicitly
// No need for a separate "UserServiceInterface"

Wrong: Ignoring context.Context (Java has no equivalent)

// BAD -- no context propagation (Java habit of ignoring cancellation)
func fetchData(url string) ([]byte, error) {
    resp, err := http.Get(url) // No timeout, no cancellation
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    return io.ReadAll(resp.Body)
}

Correct: Thread context through all function calls

// GOOD -- context for cancellation, timeouts, and request-scoped values
func fetchData(ctx context.Context, url string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, err
    }
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("fetch %s: %w", url, err)
    }
    defer resp.Body.Close()
    return io.ReadAll(resp.Body)
}

// Caller sets timeout:
// ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
// defer cancel()
// data, err := fetchData(ctx, "https://api.example.com/data")

Common Pitfalls

• Nil pointer panics from uninitialized maps: In Java, new HashMap<>() is safe. In Go, var m map[string]int creates a nil map that panics on write. Fix: Always initialize maps: m := make(map[string]int) or m := map[string]int{}. [src4]
• Goroutine leaks from missing channel consumers: Launching goroutines that write to unbuffered channels with no reader causes them to hang forever. Fix: Always ensure channels are read from, or use buffered channels. Use context.Context for cancellation. [src1]
• Circular import errors from Java-style package structure: Java allows circular package dependencies; Go does not. Fix: Restructure into a flat package layout or use interfaces to break cycles. [src3]
• Ignoring go vet and staticcheck warnings: Java developers rely on IDE warnings. Go has powerful static analysis tools that catch real bugs. Fix: Run go vet ./... and staticcheck ./... in CI. [src1]
• Using init() functions for complex setup: Java developers try to replicate @PostConstruct with Go's init(). This creates hidden dependencies and makes testing hard. Fix: Use explicit initialization in main() and pass dependencies through constructors. [src3]
• Assuming Go generics work like Java's: Go added generics in 1.18, but they are simpler. No wildcards (? extends T), no type erasure. Go 1.24 adds generic type aliases; Go 1.25 removes the core types concept. Fix: Use generics sparingly for data structures; prefer interfaces for behavioral abstraction. [src4]
• Forgetting to close resources without defer: Java's try-with-resources auto-closes. In Go, you must explicitly call Close(). Fix: Use defer resource.Close() immediately after successful open. Check the error from Close() on write operations. [src7]
• Not using context.Context in APIs: Java has no direct equivalent; Go passes context explicitly as the first parameter of every function that does I/O. Fix: Accept ctx context.Context as the first parameter in all service and repository methods. [src1]
• Deploying Go in containers without adjusting GOMAXPROCS: Before Go 1.25, the Go runtime ignored Cgroup CPU limits, setting GOMAXPROCS to the host's CPU count even in constrained containers — causing kernel CPU throttling (~100ms stalls) and tail-latency spikes. Fix: Upgrade to Go 1.25+ which sets GOMAXPROCS = min(CPU_limit, cores) and re-checks periodically; on older Go use go.uber.org/automaxprocs. [src8, src10]

Diagnostic Commands

# Initialize a new Go project
go mod init github.com/yourorg/myservice

# Download dependencies (like mvn dependency:resolve)
go mod tidy

# Build and check for compilation errors
go build ./...

# Run all tests with race detector enabled
go test -race -v ./...

# Run static analysis (catches bugs go build misses)
go vet ./...

# Check test coverage (like JaCoCo)
go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out

# Format all code (like google-java-format but enforced)
gofmt -w .

# Profile CPU/memory (like JFR/VisualVM)
go test -bench=. -cpuprofile=cpu.out -memprofile=mem.out ./...
go tool pprof cpu.out

# Cross-compile for Linux (no JVM needed on target)
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o myservice ./cmd/myservice

# Track tool dependencies in go.mod (Go 1.24+)
go get -tool golang.org/x/tools/cmd/stringer

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Go has no exceptions — all error handling is explicit via return values. This increases verbosity but makes error paths visible. Do not fight this pattern; embrace if err != nil.
• Go interfaces are satisfied implicitly. You never write implements. This is powerful but can be confusing for Java developers who expect explicit contracts.
• Go has no method overloading and no default parameter values. Use functional options pattern (WithTimeout(5*time.Second)) or config structs instead.
• Go modules replaced GOPATH in 2019. Always use go mod init for new projects. Never set GOPATH for new development.
• Memory management differs: Go has a garbage collector but no JVM tuning knobs. If you need predictable latency, profile with pprof and reduce allocations.
• Java's null maps roughly to Go's nil, but Go's zero values are type-specific (0 for int, "" for string, nil for pointers/slices/maps). A nil slice is valid and usable (length 0), but a nil map panics on write.
• Java 25's virtual threads and structured concurrency significantly narrow Go's concurrency advantage for I/O-bound workloads. Evaluate whether the migration is still justified if concurrency performance was the primary motivation. [src4, src8]
• Go 1.24's Swiss Table maps and Go 1.26's Green Tea garbage collector (default, 10–40% GC overhead reduction) keep Go competitive for latency-sensitive services. [src9]
• Container deployments: Go 1.25+ makes GOMAXPROCS container-aware by default, so a Go service no longer over-schedules threads against a Cgroup CPU limit. On Go <1.25 you must add go.uber.org/automaxprocs. [src10]
• The Dockerfile in step 7 references golang:1.24-alpine; bump the builder image to the current golang:1.26-alpine (or your pinned minor) to inherit the default Green Tea GC and container-aware GOMAXPROCS.