Common Mistakes

Plumego is intentionally simple —
but that simplicity makes certain mistakes very easy to make,
especially for teams coming from more opinionated frameworks.

This page documents the most common missteps,
why they happen,
and how to avoid them before they harden into architecture.

Mistake 1: Treating Plumego Like Gin / Echo

What It Looks Like

• Putting business logic directly in handlers
• Using Context as a data bus
• Writing “fat handlers”
• Assuming the framework will “handle things later”

Why It Happens

Most Go web frameworks encourage this style,
especially early in a project.

Plumego does not.

Why This Is a Problem

• Handlers become untestable
• Business logic is tied to HTTP
• Refactoring becomes expensive
• Reuse outside HTTP becomes impossible

What to Do Instead

• Keep handlers thin
• Move logic into usecases
• Treat handlers as translation layers only

If a handler feels “smart”, it is probably doing too much.

Mistake 2: Overusing Context

What It Looks Like

• Storing domain entities in Context
• Using Context as a request-scoped container
• Passing Context deep into domain logic

Why This Is a Problem

• Hidden dependencies
• Increased coupling
• Hard-to-track data flow
• Context becomes a second DI container

What to Do Instead

• Store only request metadata in Context
• Pass explicit parameters to usecases
• Keep domain logic Context-free

Context is not a dependency carrier.

Mistake 3: Reintroducing Global State

What It Looks Like

• Global config variables
• Global service singletons
• Hidden package-level initialization
• init()-driven wiring

Why This Is a Problem

• Breaks test isolation
• Hides dependencies
• Makes replacement hard
• Undermines Plumego’s core guarantees

What to Do Instead

• Load config at startup
• Inject dependencies explicitly
• Keep wiring visible in main or composition roots

If you cannot see a dependency being passed,
it is probably global.

Mistake 4: Building a “Mini Framework” on Top of Plumego

What It Looks Like

• Custom auto-registration
• Reflection-based wiring
• Convention-heavy wrappers
• Hidden lifecycle hooks

Why This Is a Problem

• Recreates the very problems Plumego avoids
• Makes debugging harder
• Locks the team into undocumented behavior

What to Do Instead

• Use Plumego primitives directly
• Prefer repetition over indirection
• Accept explicit wiring as a cost worth paying

Frameworks on top of frameworks age badly.

Mistake 5: Adding Abstractions Too Early

What It Looks Like

• Interfaces everywhere “just in case”
• Generic repositories before real needs
• Premature service boundaries
• Over-layered architecture in tiny systems

Why This Is a Problem

• Increased complexity
• Lower signal-to-noise ratio
• Harder onboarding
• Slower iteration

What to Do Instead

• Start concrete
• Abstract only when replacement is needed
• Let real pressure justify interfaces

Plumego supports abstraction — it does not require it.

Mistake 6: Hiding Errors

What It Looks Like

• Swallowing errors in middleware
• Logging without surfacing failures
• Returning “safe” responses automatically
• Treating errors as implementation details

Why This Is a Problem

• Failures become invisible
• Debugging becomes guesswork
• Clients receive misleading responses

What to Do Instead

• Handle errors explicitly
• Translate errors at boundaries
• Treat errors as part of the contract

Silence is not resilience.

Mistake 7: Treating Middleware as Business Logic

What It Looks Like

• Domain rules in middleware
• Authorization decisions spread across middleware
• Side effects hidden before handlers

Why This Is a Problem

• Execution order becomes fragile
• Business rules become implicit
• Testing becomes difficult

What to Do Instead

• Use middleware for cross-cutting concerns only
• Keep business rules in usecases
• Make domain decisions explicit

Middleware is about how, not what.

Mistake 8: Over-Optimizing Early

What It Looks Like

• Premature performance tuning
• Custom routers without evidence
• Allocation micro-optimizations everywhere
• Complex concurrency models “just in case”

Why This Is a Problem

• Adds complexity without benefit
• Obscures intent
• Makes correctness harder to reason about

What to Do Instead

• Measure first
• Optimize when proven necessary
• Keep the simple path obvious

Clarity is the best optimization.

Mistake 9: Expecting the Framework to “Save You”

What It Looks Like

• Expecting Plumego to enforce architecture
• Looking for guardrails instead of discipline
• Assuming the framework prevents misuse

Why This Is a Problem

Plumego assumes responsible engineers.

It does not protect you from bad decisions
by hiding them.

What to Do Instead

• Embrace responsibility
• Use documentation as constraints
• Let discipline replace magic

Plumego gives you control — not safety rails.

Mistake 10: Ignoring the Documentation Hierarchy

What It Looks Like

• Skipping Concepts and Architecture
• Treating Reference as a tutorial
• Using patterns without understanding constraints

Why This Is a Problem

• Misaligned mental models
• Incorrect assumptions
• Frustration with “missing features”

What to Do Instead

• Read in order
• Understand why before how
• Treat Reference as law, not guidance

Plumego is simple, not shallow.

A Final Reminder

Most mistakes stem from one root cause:

Trying to make Plumego behave like something it is not.

Plumego is not:

• A productivity-first framework
• A safety-net framework
• A convention-driven framework

It is an explicit control framework.

Summary

Common mistakes with Plumego are not accidental —
they come from familiar habits.

Avoiding them requires:

• Patience
• Discipline
• Willingness to be explicit

If you avoid these mistakes early,
Plumego will remain a calm and reliable foundation for years.

Related FAQ Pages

• Why Is Plumego So Explicit?
• Plumego vs Gin
• When Not to Use Plumego
• Is Plumego Suitable for Small Projects?

Frameworks do not fail on day one —
they fail slowly, through small compromises.

This page exists to stop those compromises early.