new-feature-go

new-feature-go

Do not open any file for editing until all 6 steps are completed.

---

Step 1 — Define the surface

Write the surface in plain text first:

Feature name: credits
Public types: *Service (concrete), Repository (interface, lives next to Service)
Methods: Charge(ctx, userID, amount, idem) (string, error)
         Confirm(ctx, holdID) error
         Refund(ctx, holdID) error
Errors: ErrInsufficientFunds (sentinel), *ValidationError (typed)
Single-writer for: Repository.Hold — only Service.Charge calls it

If the public surface needs more than 5-6 methods, the package is doing too much — split it (Principle E2).

---

Step 2 — Pick the package location (Principle E1, E2)

Scope	Location
Public library others import via go.mod	pkg/<name>/
Private to this service	internal/<name>/ (default)
HTTP wiring / handlers	internal/server/
Cross-cutting helpers (genuine ones)	internal/<purpose>/ (e.g. internal/httpclient)
Binary entry point	cmd/<binary>/main.go

Forbidden package names: utils, helpers, common, shared, lib, misc. Pick a name that says what the package does.

---

Step 3 — Build bottom-up

1. Errors          → internal/<name>/errors.go (sentinels + typed)
2. Repository iface → internal/<name>/repository.go (smallest set of methods)
3. Repository impl → internal/<name>/repository.go (MemoryRepo for tests, SQLRepo for prod)
4. Service struct  → internal/<name>/service.go (concrete, accepts Repository)
5. Service tests   → internal/<name>/service_test.go (table-driven, t.Run)
6. Handler         → internal/server/handlers.go (defines tiny consumer interface)
7. Wiring          → cmd/api/main.go (constructor injection)

Critical rules during build:

• Repository interface lives next to the Service that uses it — this is Go's hexagonal idiom (Principle E3).
• Service constructors return *Service (concrete). Handlers accept the smallest interface they need (Principle F1).
• context.Context is the first parameter of every I/O method (Principle F2).
• Errors are returned, never panic'd. Wrap with %w (Principle F3).
• If integrating an external HTTP API, get its client from httpclient.Get("<provider>") — never use http.DefaultClient (Principle F4).