9.5 KiB
template
A Go project template for PoC, hobby projects, and small publishable packages.
Clone it, rename the module, run make init, and you're coding.
Demonstrates idiomatic Go patterns: stdlib-only dependencies, consumer-defined interfaces,
manual fakes for testing, and a clean go.mod that stays free of dev tool noise —
so packages extracted from this template can be published without module graph pollution.
Features
| Area | Tool | Purpose |
|---|---|---|
| Language | Go 1.25 | Modules, toolchain directive |
| Logging | standard log/slog |
Structured JSON/text logging + WithField extension |
| Config | standard flag |
CLI flags with defaults, no config files |
| Linting | golangci-lint | Aggregated linters, one config file |
| Security | gosec + govulncheck | SAST + dependency vulnerability scan |
| Tests | standard testing |
Table-driven tests, manual fakes, no third-party test framework |
| Git hooks | custom pre-push | gofmt + go vet + golangci-lint + gosec on every push |
| Tool versions | tools.versions + go run |
Pinned versions without polluting go.mod |
| Dev environment | devcontainer | Reproducible VSCode / GitHub Codespaces setup |
| IDE | VSCode | Launch configs, tasks, recommended settings |
Getting started
Prerequisites
- Go 1.25+
- Git
- (Optional) VSCode + Go extension
- (Optional) Docker for devcontainer
1. Clone and rename
git clone https://gitea.djmil.dev/go/template my-project
cd my-project
# Interactive rename — updates module path, config, devcontainer, and docs:
./rename.sh
2. Init (run once)
make init # fetches deps, configures git hooks
make tools # (optional) install tool binaries to GOPATH/bin for IDE integration
3. Build and run
make build # compiles to ./bin/app
make run # go run with default flags
Daily workflow
make test # run all tests
make test-race # … with race detector
make lint # go vet + golangci-lint
make lint-fix # go fix + golangci-lint auto-fix
make security # gosec + govulncheck
make release # list tags, or run full checks then tag+push (make release VERSION=v0.1.0)
Keyboard shortcut (VSCode):
Ctrl+Shift+B→ build,Ctrl+Shift+T→ test.
Project structure
.
├── cmd/
│ └── app/
│ └── main.go # Composition root (thin — just wiring)
├── internal/
│ ├── config/ # flag-based config (config.Load)
│ ├── logger/ # slog wrapper with WithField / WithFields
│ └── greeter/ # Example domain package (replace with yours)
├── .devcontainer/ # VSCode / Codespaces container definition
├── .githooks/ # pre-push hook (installed by `make setup`)
├── .vscode/ # launch, tasks, editor settings
├── pkg/
│ └── result/ # Example publishable package (Result/Expect types)
│ ├── doc.go # package-level godoc
│ ├── result.go # implementation
│ └── example_test.go # runnable examples (shown on pkg.go.dev)
├── tools.versions # Pinned tool versions (Makefile + hook source this)
├── .golangci.yml # Linter configuration
└── Makefile # All development commands
Configuration
All configuration is via CLI flags with sensible defaults:
./bin/app -help
-env string environment: dev | staging | prod (default "dev")
-log-level string log level: debug | info | warn | error (default "info")
-name string greeter name (default "Gopher")
-port int listen port (default 8080)
Override at runtime:
./bin/app -port 9090 -env prod -log-level warn
Logging
The logger wrapper adds WithField and WithFields for ergonomic context chaining
on top of the standard log/slog package:
log.WithField("request_id", rid).
WithField("user", uid).
Info("handling request")
log.WithFields(map[string]any{
"component": "greeter",
"name": name,
}).Debug("generating greeting")
In production (app.env != dev) the output is JSON (slog.NewJSONHandler).
In development, logger.NewDevelopment() uses the human-friendly text handler.
Testing
Tests use the standard testing package. Concrete types are returned from
constructors — consumers (including tests) define their own minimal interfaces
and satisfy them with manual fakes. No code generation required.
// Interface declared in the consumer (or _test.go), not in greeter package.
type greeter interface {
Greet(name string) result.Expect[string]
}
type fakeGreeter struct {
greetFn func(name string) result.Expect[string]
}
func (f *fakeGreeter) Greet(name string) result.Expect[string] {
return f.greetFn(name)
}
func TestSomething(t *testing.T) {
fake := &fakeGreeter{
greetFn: func(name string) result.Expect[string] {
return result.Ok("Hello, " + name + "!")
},
}
// pass fake to the system under test
}
pkg/result — happy-path error handling
pkg/result is a small publishable package that demonstrates the pattern of
keeping go.mod clean. It provides Expect[T], a generic type that holds
either a success value or an error.
The idea: deep call stacks write for the happy path, unwrapping results with
Expect or Must (which panic on failure). A single defer result.Catch(&err)
at the entry point recovers those panics and returns them as a normal Go error,
with the stack trace captured at the original failure site.
// Wrap any (value, error) function:
data := result.Of(os.ReadFile("config.json")).Expect("read config")
// Or construct explicitly:
func parsePort(s string) result.Expect[int] {
n, err := strconv.Atoi(s)
if err != nil {
return result.Fail[int](fmt.Errorf("parsePort: %w", err))
}
return result.Ok(n)
}
// Entry point catches panics from the whole call stack:
func run() (err error) {
defer result.Catch(&err)
port := parsePort(cfg.Port).Expect("load config")
_ = port // happy path continues …
return nil
}
Catch only intercepts error panics produced by this package. Real runtime
panics (nil-pointer dereferences, etc.) are re-panicked so bugs are never
silently swallowed.
At boundaries where you need to re-join normal Go code:
port, err := parsePort("443").Unwrap() // back to (T, error)
See pkg/result/example_test.go for the
full set of runnable examples.
Git hooks
The pre-push hook runs gofmt + go vet + golangci-lint + gosec against the
full codebase before every git push. Running on push (not commit) keeps the
inner commit loop fast while still blocking bad code from reaching the remote.
govulncheck is intentionally excluded (it makes network calls and can be
slow). Run it manually with make security.
To skip the hook in an emergency:
git push --no-verify
Tool version management
Tool versions are pinned in tools.versions — a plain KEY=value file that
both the Makefile and the pre-push hook source directly.
Why not tools.go + go.mod?
The conventional //go:build tools approach adds development tools (linters,
scanners, debuggers) as entries in go.mod. This is fine for applications, but
it's a problem when the repo is intended to publish reusable packages: consumers
who go get your package see those tool dependencies in the module graph, even
though they are never compiled into the binary. Keeping go.mod clean makes the
module honest — it declares only what the package code actually needs.
Instead, go run tool@version is used in Makefile targets and the pre-push
hook. Go caches downloaded tools in the module cache, so after the first run
there is no extra download cost.
To update a tool, edit the version in tools.versions:
GOLANGCI_LINT_VERSION=v1.64.8 ← change this
Both make lint and the pre-push hook pick up the new version automatically.
Run make tools if you also want the updated binary installed to GOPATH/bin
(e.g. for IDE integration or direct CLI use).
Releasing
make release # list all existing tags
make release VERSION=v0.1.0 # run full checks, then tag and push
The release target validates the version format (semver vX.Y.Z), ensures the
working tree is clean, and runs make test-race lint security before tagging.
The tag is only created and pushed if every check passes.
Devcontainer
Open this repo in VSCode and choose "Reopen in Container" — the Go
toolchain is installed automatically. Run make init to configure git hooks,
then make tools to install linter/scanner binaries to GOPATH/bin.
Works with GitHub Codespaces out of the box.