Strangler Fig in Go: Migrating a Monolith Without a Big-Bang Rewrite

Book: Hexagonal Architecture in Go
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You inherit a Go monolith. One repo, forty handlers, one Postgres database, two integrations stitched into the HTTP layer. Someone proposes the rewrite. Three months of design docs, a freeze on new features, a parallel repo nobody uses in production. Six months in, the rewrite is shipped to staging and abandoned because the business needed a checkout fix and there was no team left to do it.

Martin Fowler called the alternative the Strangler Fig. The metaphor comes from a real plant: a fig seed sprouts in the canopy of a host tree, drops roots down the trunk, and over years grows into a hollow lattice. By the time the host tree dies, the fig is structurally complete. There is no day when the tree falls.

You can run the same pattern on a Go monolith. Route by route, integration by integration, the legacy code gets enveloped, redirected, and eventually deleted. Each step is a single PR behind a feature flag. The monolith keeps serving traffic the entire time.

The single-service hex migration reshaped one Go service in place. The strangler fig grows several small hex services out of a monolith. Different problem, different shape.

The seven-step pattern

The seven steps in order:

Identify the seams — HTTP routes, DB tables, external integrations.
Extract shared types into a domain module.
Define ports (interfaces) for each seam.
Wrap the legacy implementation in an adapter (the anti-corruption layer).
Reroute traffic via a thin proxy in front of the monolith.
Run a shadow read against the new service to prove parity.
Cut over with the flag, delete the legacy code path.

Each step is independently shippable. Each step is reversible by flipping a flag. The order matters. Skip the proxy step and you cannot do shadow reads. Skip shadow reads and cutover is a guess.

Step 1: Identify the seams

A seam is a place where the monolith already has a boundary you can lean on. Three kinds matter:

HTTP routes. Every URL pattern is a candidate. /checkout, /orders/{id}, /customers. Find them by reading the router.
Database tables. Tables that only one bounded context reads or writes. payments, coupons, inventory_holds.
External integrations. Anywhere the monolith calls Stripe, S3, an internal vendor adapter. These are already wrapped behind a function call. That function is a seam.

Pick the seam with the highest pain-to-risk ratio. /checkout is usually a good first target: changes there get the most scrutiny, the table set is small, and a regression is recoverable in seconds via the flag.

Make the inventory explicit. A migration.md at the repo root listing every route, every table it touches, and every integration. This is the map you will tick off over the next few months.

Step 2: Extract shared types into a domain module

Create internal/domain (or a separate Go module, domain/, if the new services will live in their own repos). Move the structs your business logic talks about — Order, Item, Coupon, Customer — into it. No json tags. No db tags. No ORM annotations.

// internal/domain/order.go
package domain

import "time"

type OrderStatus string

const (
    OrderPending   OrderStatus = "pending"
    OrderConfirmed OrderStatus = "confirmed"
    OrderCancelled OrderStatus = "cancelled"
)

type Order struct {
    ID         string
    CustomerID string
    Items      []Item
    TotalCents int64
    Status     OrderStatus
    CreatedAt  time.Time
}

type Item struct {
    ProductID  string
    Quantity   int
    PriceCents int64
}

The monolith still uses its old SQL-tagged structs in handlers. That is fine. The domain types are the shared vocabulary the new services will speak. Existing handlers map to and from them at the boundary.

The check that the domain stays clean:

go list -f '{{.Imports}}' ./internal/domain/...
# should be: [time fmt errors context]
# should NOT contain: database/sql net/http encoding/json

Wire that go list check into CI. Catch the leak at PR review and it is a one-line fix. Six months in, it is a week.

Step 3: Define a port per seam

For the /checkout seam, the port is one interface in the domain package:

// internal/domain/checkout.go
package domain

import "context"

type CheckoutRequest struct {
    CustomerID string
    Items      []Item
    CouponCode string
}

type Checkout interface {
    Create(
        ctx context.Context,
        req CheckoutRequest,
    ) (Order, error)
}

The domain now has a contract for what "creating a checkout" means, independent of HTTP, gRPC, or background workers. You can write a fake Checkout for tests in five lines.

Define one port per seam, not one per handler. /orders and /orders/{id} both belong to the same Orders port. Keep ports narrow. Aim for two to four methods. Ten methods is usually a sign you have not found the actual bounded context yet.

Step 4: Wrap the legacy code as an adapter

This is the step that does almost nothing visible. The old monolith handler stays. You wrap it.

// internal/legacy/checkout_adapter.go
package legacy

import (
    "context"

    "yourapp/internal/domain"
    "yourapp/internal/monolith/handlers"
)

type CheckoutAdapter struct {
    mono *handlers.OrderHandler
}

func NewCheckoutAdapter(
    mono *handlers.OrderHandler,
) *CheckoutAdapter {
    return &CheckoutAdapter{mono: mono}
}

func (a *CheckoutAdapter) Create(
    ctx context.Context,
    req domain.CheckoutRequest,
) (domain.Order, error) {
    legacyOrder, err := a.mono.CreateOrderInternal(
        ctx,
        req.CustomerID,
        toLegacyItems(req.Items),
        req.CouponCode,
    )
    if err != nil {
        return domain.Order{}, translate(err)
    }
    return toDomainOrder(legacyOrder), nil
}

The toLegacyItems, toDomainOrder, and translate helpers are pure mapping functions. They live in the same legacy package. Their job is to keep monolith types (handlers.OrderHandler, handlers.LegacyError, and the legacy SQL structs) from leaking out.

This is the anti-corruption layer. The "vendor" in this case is your own monolith. You translate its taxonomy into your domain's taxonomy at one boundary, so the rest of the system never has to care.

Ship this PR. Run the existing test suite. Nothing changes in production yet.

Step 5: Route traffic through a thin proxy

You need a layer that sits in front of the monolith and decides, per request, whether to forward to the monolith handler or to the new service. A reverse proxy in Go is short.

// proxy/checkout.go
package proxy

import (
    "net/http"
    "net/http/httputil"
    "net/url"
)

type Router struct {
    monolith     *httputil.ReverseProxy
    newService   *httputil.ReverseProxy
    useNewSvc    func(*http.Request) bool
}

func New(
    monoURL, newURL string,
    useNewSvc func(*http.Request) bool,
) (*Router, error) {
    mono, err := url.Parse(monoURL)
    if err != nil {
        return nil, err
    }
    svc, err := url.Parse(newURL)
    if err != nil {
        return nil, err
    }
    return &Router{
        monolith:   httputil.NewSingleHostReverseProxy(mono),
        newService: httputil.NewSingleHostReverseProxy(svc),
        useNewSvc:  useNewSvc,
    }, nil
}

The ServeHTTP method picks per request based on the flag function:

func (r *Router) ServeHTTP(
    w http.ResponseWriter,
    req *http.Request,
) {
    if r.useNewSvc(req) {
        r.newService.ServeHTTP(w, req)
        return
    }
    r.monolith.ServeHTTP(w, req)
}

The useNewSvc closure is your feature-flag boundary. Start with func(*http.Request) bool { return false }. All traffic still hits the monolith. The new service exists, listens, but receives nothing. You can deploy it for weeks before sending it a single real request.

When you flip the flag to a 1% rollout, that 1% experiences the new code path. Everyone else is on the monolith. A bad release means flipping back to false and reading logs at human speed.

Step 6: Shadow-read parity check

Before you actually serve user traffic from the new service, prove it produces the same answers as the monolith. The proxy fans out: respond from the monolith, but also call the new service in the background and compare.

// proxy/shadow.go
package proxy

import (
    "bytes"
    "io"
    "log/slog"
    "net/http"
    "net/http/httptest"
)

type Shadow struct {
    primary http.Handler
    shadow  http.Handler
    log     *slog.Logger
}

func NewShadow(
    primary, shadow http.Handler,
    log *slog.Logger,
) *Shadow {
    return &Shadow{primary, shadow, log}
}

ServeHTTP clones the request body, replays the call against the shadow service, and diffs the response without ever blocking the real user on the shadow call. The pattern is: respond fast, shadow async, never let the shadow block the user.

func (s *Shadow) ServeHTTP(
    w http.ResponseWriter,
    req *http.Request,
) {
    body, _ := io.ReadAll(req.Body)
    req.Body = io.NopCloser(bytes.NewReader(body))

    primaryRec := httptest.NewRecorder()
    s.primary.ServeHTTP(primaryRec, req)
    copyResponse(w, primaryRec)

    go func() {
        shadowReq := req.Clone(req.Context())
        shadowReq.Body = io.NopCloser(
            bytes.NewReader(body),
        )
        shadowRec := httptest.NewRecorder()
        s.shadow.ServeHTTP(shadowRec, shadowReq)
        s.diff(primaryRec, shadowRec, req.URL.Path)
    }()
}

The diff helper logs the path, status code mismatches, and body diffs. Point your alerting at it.

Shadow reads only. You do not shadow-write. Two writes against the same database against the same idempotency key will corrupt state. Read endpoints (GET /orders/{id}) are safe to shadow forever. Write endpoints get cut over directly with the flag and rolled back fast if metrics move.

Tolerate non-determinism. Timestamps, database autogenerated IDs, ordering of slices that should be sets. Build a normaliser into diff before you compare. If you cannot normalise, that is a hint the new service has a different contract. Fix the service, not the diff.

Teams that run this pattern often spend two to three weeks in shadow mode before cutover. The bugs that surface tend to be small and load-bearing: timezone-parsing differences, rounding mismatches on edge-case totals, the kind of thing that causes customer-visible errors when you cut over blind.

Step 7: Cut over and delete the legacy path

When the diff has been zero for long enough, flip useNewSvc from a percentage to true for the route. Watch the dashboards for an hour. Watch them for a day. Then come back to the codebase and delete:

The legacy handler in monolith/handlers/order.go.
The legacy adapter in internal/legacy/checkout_adapter.go — its job was to keep the monolith reachable during migration. Once nothing routes there, it is dead code.
The route entry in the monolith's router.
The flag, once it has been true in prod for a release cycle.

go vet ./... and staticcheck will help: anything unimported and unreferenced is a candidate. Do the deletion in its own PR. Reverting "delete dead code" is cheap; reverting "delete dead code AND ship a feature" mid-incident is not.

What you have at the end

After six or seven seams, the monolith has been hollowed out. The router's job is mostly forwarding to small hex services. Each new service has its own domain types, its own ports, its own adapters, and its own deploy. The remaining monolith is small enough that the next migration is the easy one, or you decide to leave it because it is fine.

Pick the seam with the highest pain-to-risk ratio on Monday. Ship the adapter Friday.

If this was useful

The strangler fig pattern, the anti-corruption layer, the port-per-seam approach — they all come from the same playbook. Hexagonal Architecture in Go walks the playbook end to end with tested code: how to define ports that survive vendor swaps, how to write adapters that translate without leaking, and how to migrate a real codebase without breaking the deploy pipeline.

The Complete Guide to Go Programming is the companion — the language fundamentals the architecture book assumes you have.

推荐订阅源

DEV Community