- 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 wrote the architecture doc. The team agreed in the meeting. The PR description says "follows hexagonal." Six months later, you open internal/domain/order.go and the import block reads database/sql, net/http, and github.com/aws/aws-sdk-go-v2/service/s3. Nobody noticed when those crept in. They rode in on a Friday afternoon merge, past two senior reviewers running on coffee.
Architecture rules that live only in your head do not survive the second quarter of a service's life. The fix is to encode the rule the same way you encode any other invariant: as a check that fails the build.
This post walks through three ways to do that for the hexagonal dependency rule (domain imports nothing from adapter/... and nothing transport-shaped from the standard library). Pick whichever fits your stack.
The rule, written down
In a hexagonal Go service, the dependency arrows point inward. Adapters know about the domain. The domain knows about ports (its own interfaces). Nothing in the domain imports anything that is database-shaped, transport-shaped, or vendor-shaped.
Concretely, for a project laid out like this:
internal/
domain/ # business logic, port interfaces
adapter/
postgres/ # implements ports
http/ # inbound transport
port/ # optional alias for domain interfaces
cmd/
server/ # main(), the composition root
The forbidden imports inside internal/domain/... are roughly:
-
database/sqland its driver subpackage -
net/http,net/rpc -
encoding/json,encoding/xml(arguable: DTOs live in adapters) - Anything under
internal/adapter/... - Most third-party paths:
github.com/...,gitlab.com/...,cloud.google.com/...
That list is your CI contract. Now you need a robot to read it.
Option 1: a 40-line bash check using go list
Start with the cheapest thing that works. The Go toolchain already knows what every package imports. go list will print it.
#!/usr/bin/env bash
# scripts/check-domain-imports.sh
set -euo pipefail
DOMAIN_PKG="./internal/domain/..."
FORBIDDEN=(
"database/sql"
"net/http"
"net/rpc"
"github.com/"
"gitlab.com/"
"cloud.google.com/"
"internal/adapter/"
)
The script asks go list for the transitive closure of every package under the domain, then greps for anything on the forbidden list:
IMPORTS=$(go list -deps -f '{{.ImportPath}}' \
"$DOMAIN_PKG" | sort -u)
FAILED=0
for pat in "${FORBIDDEN[@]}"; do
hits=$(echo "$IMPORTS" | grep -F "$pat" || true)
if [ -n "$hits" ]; then
echo "FORBIDDEN import in domain: ${pat}"
echo "$hits" | sed 's/^/ /'
FAILED=1
fi
done
if [ "$FAILED" -ne 0 ]; then
echo "domain dependency rule violated"
exit 1
fi
echo "domain imports are clean"
Two pieces are doing the work. go list -deps walks the transitive closure and emits one line per package in it, so a domain package that imports a helper that imports database/sql still gets caught. grep -F matches each forbidden pattern as a substring against those lines, which is why internal/adapter/ works regardless of your module path: the actual go list output looks like github.com/acme/orders/internal/adapter/postgres, and the substring is right there in the middle.
Wire it into your pipeline. GitHub Actions:
- name: domain dependency rule
run: ./scripts/check-domain-imports.sh
Forty lines of bash, zero new dependencies, runs in well under a second on a normal repo. It is also brittle: a typo in the forbidden list silently passes, and you cannot describe layered relationships ("port may import domain but not the other way around"). For one boundary on one team, that is fine. For a real architecture, you want something with structure.
Option 2: go-arch-lint for the layered rule set
go-arch-lint (MIT-licensed, by Vadim Kulibaba — fe3dback on GitHub) is the dedicated tool for this. You describe your components and the allowed dependency edges in a YAML file; the linter walks your import graph and yells when an edge is missing from the allowlist. Verified against the project's v1.14.0 syntax docs, the v3 config for the layout above looks like this:
version: 3
components:
domain:
in: internal/domain/**
port:
in: internal/port/**
adapter:
in: internal/adapter/**
cmd:
in: cmd/server/**
commonComponents:
- port
deps:
domain:
mayDependOn:
- port
adapter:
mayDependOn:
- domain
- port
cmd:
mayDependOn:
- domain
- adapter
- port
No workdir: here. The project's own canonical config uses workdir: internal, but that resolves every in: path relative to the workdir, and v3 does not let you escape it with ../. Writing globs from the repo root (internal/domain/**, cmd/server/**) keeps the config flat and lets cmd sit alongside internal without contortions.
Read it as a graph. domain only points at port. adapter points inward at domain. cmd is the composition root and is allowed to see everyone. There is no edge from domain to adapter, so any new import that crosses that line is a violation.
Run it locally first. Pin the version rather than @latest so CI does not silently pick up a breaking release:
go install github.com/fe3dback/go-arch-lint@v1.14.0
go-arch-lint check --project-path .
Then add it to CI:
- name: install go-arch-lint
run: go install github.com/fe3dback/go-arch-lint@v1.14.0
- name: arch lint
run: go-arch-lint check --project-path .
The win over the bash script: the rule reads like architecture instead of like a regex. A new engineer reading .go-arch-lint.yml sees the layering at a glance. Adding an application tier between port and domain is one new edge in the YAML, not a new clause in a shell loop.
One caveat. go-arch-lint reasons about your packages, not raw stdlib paths. If you specifically want to ban database/sql from anywhere in the domain — even when it sneaks in via a helper that lives inside the domain component — pair go-arch-lint with the bash check above. They cover different angles.
Option 3: a custom analyzer with golang.org/x/tools/go/analysis
When you need rules that are uniquely yours — "no imports from domain/... to adapter/..., with the file and line of the offending import in the error message, integrated into go vet and your editor" — write a tiny analyzer. Verified against the analysis package docs and the singlechecker docs, the whole thing fits in fifty lines.
The full file:
// cmd/hexlint/main.go
package main
import (
"strings"
"golang.org/x/tools/go/analysis"
"golang.org/x/tools/go/analysis/singlechecker"
)
var Analyzer = &analysis.Analyzer{
Name: "hexlint",
Doc: "domain may not import adapter",
Run: run,
}
func main() { singlechecker.Main(Analyzer) }
func run(pass *analysis.Pass) (interface{}, error) {
pkg := pass.Pkg.Path()
if !strings.Contains(pkg, "/internal/domain") {
return nil, nil
}
for _, file := range pass.Files {
for _, imp := range file.Imports {
path := strings.Trim(imp.Path.Value, `"`)
if isForbidden(path) {
pass.Reportf(
imp.Pos(),
"domain imports forbidden package %q",
path,
)
}
}
}
return nil, nil
}
func isForbidden(path string) bool {
switch {
case strings.Contains(path, "/internal/adapter/"):
return true
case path == "database/sql",
path == "net/http",
path == "encoding/json":
return true
}
return false
}
pass.Pkg.Path() tells you which package is being analyzed. pass.Pkg.Imports() gives you what it imports. For each import that crosses the forbidden boundary, pass.Reportf carries the position of the offending import spec so editors and CI both highlight the right line.
Build and run it like any other Go program:
go build -o bin/hexlint ./cmd/hexlint
./bin/hexlint ./internal/domain/...
Output on a violating file (one diagnostic per line, the standard go vet format):
internal/domain/order.go:5:2: domain imports forbidden package "database/sql"
Editors that already understand go vet output will surface it inline. Drop it into CI as a separate step or wire it into a golangci-lint custom rule and it runs on every PR.
You pay for it with a binary to maintain. In return the error messages talk about your architecture, not about regex patterns.
Pick one and ship it today
If you only ship one of these, ship the bash version. Forty lines of script, one CI step, and the dependency rule stops being a vibe. You can layer go-arch-lint on top later when your boundary count grows past one. You can write a custom analyzer when you need editor-level signal.
The shape that does not work is the one most teams have right now: an architecture diagram in Confluence, a pair of senior engineers trusted to spot violations in review. And a domain package that quietly accumulates database/sql imports because the grep nobody runs would have caught them.
Make the grep run. Make it block the merge.
If this was useful
The boundary tooling is one chapter; the harder question is what your domain actually looks like once those imports are gone — what counts as a port, where DTOs live, how transactions cross the line. Hexagonal Architecture in Go walks through that end-to-end with real services, not toy examples. The companion Complete Guide to Go Programming covers the language fundamentals the architecture rests on.
If you build Go services with Claude Code or similar agents, Hermes IDE is built for that workflow.
Top comments (0)