gin-lambda-api-service-patterns

Gin + Lambda Dual-Runtime API Service

A common shape for a Go API service targeting serverless deployment: one Gin engine, wired to two different runtimes depending on environment — a plain http.Server for local development, and a Lambda/API-Gateway adapter (e.g. github.com/apex/gateway or github.com/aws/aws-lambda-go's httpadapter) for the deployed path. The two paths share the same route handlers but are genuinely different code, not the same server started two ways — this skill is about the places that difference actually matters.

The dual entrypoint

func main() {
    router := setupRouter()

    if os.Getenv("APP_ENV") == "production" {
        // Serverless path: no listener, no graceful-shutdown signal handling —
        // the Lambda runtime owns the process lifecycle.
        log.Fatal(gateway.ListenAndServe(port, router))
    } else {
        // Local dev path: a real listener, real graceful shutdown.
        srv := &http.Server{Addr: ":" + port, Handler: router}
        go func() {
            if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
                log.Fatal(err)
            }
        }()
        waitForShutdownSignal(srv)
    }
}

Treat these as two genuinely different runtime paths, not one server started two ways: the Lambda-adapter path typically has no graceful shutdown or OS signal handling (the platform owns process lifecycle, cold starts and freezes replace long-running-process concerns), while the local path does. A change to shutdown behavior, connection draining, or long-lived background goroutines needs to be reasoned about separately for each path — testing only the local path can miss a change that behaves differently once actually deployed as a function.

Build and deploy shape

A Lambda-target Go service is typically built as a static cross-compiled binary and zipped, not built as a container image:

GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o ./bootstrap ./cmd
zip main.zip bootstrap
aws lambda update-function-code --function-name <fn> --zip-file fileb://./main.zip