DEV Community: Matthias Friedrich

Part 7: Testing with Confidence: Mocking and Recap

Matthias Friedrich — Sat, 16 May 2026 00:42:11 +0000

The Role of Mocks in Unit Testing

In the previous parts of this series, we focused on building and validating complex dependency graphs for production environments. However, a robust architecture is only half the battle; ensuring that individual components behave correctly in isolation is equally critical.

Unit testing in Go often relies on Mock Objects. Mocks allow you to replace real service implementations with controlled placeholders that simulate specific behaviors, return predetermined values, or record how they were called. This isolation is essential for testing edge cases—like network failures or database errors—without setting up expensive infrastructure.

In this final part of our series, we explore how the Parsley CLI simplifies mock generation and how you can use these mocks to write highly expressive tests.

1. Generating Mocks with Parsley CLI

Manually writing mock implementations for every interface in your project is tedious and error-prone. Parsley addresses this by providing a dedicated generate mocks command.

Step 1: Interface Annotation

To enable mock generation, add a //go:generate directive to your interface definition.

package features

//go:generate parsley-cli generate mocks

type DataService interface {
    FetchData(id string) (string, error)
}

Step 2: Code Generation

When you run go generate ./..., the Parsley CLI scans for the directive and generates a mock.g.go file. This file contains a mock struct (e.g., dataServiceMock) that implements your interface and provides hooks for behavior configuration.

2. Configuring and Verifying Mocks

The generated mocks are designed to be used as drop-in replacements in your test suites. They use a "function-override" pattern that keeps your tests clean and readable.

Practical Example: Testing with Mocks

Suppose we want to test a service that depends on our DataService. We can use the generated NewDataServiceMock() to simulate a successful data fetch.

func TestService_Process(t *testing.T) {
    // 1. Arrange: Initialize the mock and define its behavior
    mock := NewDataServiceMock()
    mock.FetchDataFunc = func(id string) (string, error) {
        return "mock-data", nil
    }

    // 2. Act: Pass the mock to the component under test
    service := NewMyService(mock)
    err := service.Execute("123")

    // 3. Assert: Verify expectations
    assert.NoError(t, err)

    // Verify that FetchData was called exactly once with argument "123"
    assert.True(t, mock.Verify(FunctionFetchData, 
        features.TimesOnce(), 
        features.Exact("123")))
}

Assertion Helpers

Parsley provides built-in helpers to verify method invocations:

Counter Helpers: TimesOnce(), TimesNever(), TimesExactly(n).
Argument Matchers: Exact(val), IsAny().

This approach allows you to assert not just that a method was called, but that it was called with the correct parameters, providing much deeper confidence in your component interactions.

3. Decoupling Code Generation from DI Runtime

A key design philosophy of Parsley is flexibility. While the Validator and Resolver are powerful for runtime dependency injection, the CLI tools—like proxy and mock generation—can be used independently.

You can leverage Parsley's mock generation to simplify testing even if you prefer manual dependency wiring in your production code. This makes it a versatile addition to any Go developer's toolkit, regardless of their choice of DI framework.

Series Recap: Mastering Dependency Injection

We have reached the end of our journey. Over eight articles, we have transformed a basic Go application into a modular, validated, and testable system.

The Case for Dependency Injection in Go: Established the theoretical foundation and addressed common misconceptions.
Introduction and Quick Start: Explored the core concepts of IoC and set up our first registry.
Service Registration Fundamentals: Learned how to register constructors and pre-existing instances.
Understanding Lifetimes and Scopes: Mastered Transient, Scoped, and Singleton behaviors.
Advanced Registration Patterns: Organized our code using Modules, Factory Functions, and Named Services.
Mastering Dependency Resolution: Dived into Lazy Proxies, Service Lists, and Dynamic Overrides.
Ensuring Reliability: Validation and Proxies: Caught configuration errors early and separated cross-cutting concerns.
Testing with Confidence: (This article) Simplified isolation testing with generated mocks.

Join the Community

Parsley is an open-source project driven by the community. If you found this series helpful, there are several ways you can support the project:

Leave a Star: If you use Parsley or appreciate the design, head over to the GitHub repository and leave a star. It helps other developers discover the library.
Spread the Word: Share your experience with Parsley on social media or with your team.
Contribute: Whether it's reporting a bug, improving the documentation, or proposing a new feature, your contributions are always welcome.

Thank you for following along with this series. I hope Parsley helps you build cleaner, more maintainable Go applications!

Next Steps

Try generating a mock for one of your interfaces today.
Explore the Mocking Made Easy documentation for advanced verification patterns.

Part 6: Ensuring Reliability - Validation and Proxies with Parsley

Matthias Friedrich — Sat, 16 May 2026 00:35:03 +0000

The Challenge of Complexity

As your dependency graph grows, so does the risk of subtle configuration errors. A missing registration or a circular dependency might remain hidden during development, only to manifest as a runtime failure in production. Furthermore, as you add cross-cutting concerns like logging, metrics, or auditing, your core business logic often becomes cluttered with boilerplate code that has nothing to do with the actual domain.

In our previous article, Part 5: Mastering Dependency Resolution in Go with Parsley, we explored advanced ways to resolve services. In this sixth part, we shift our focus to Reliability and Maintainability. We will learn how to use Parsley's Validator to catch configuration issues before your application starts and how to use Generated Proxies to cleanly separate cross-cutting concerns from your business logic.

1. The Validator: Catching Errors Early

The Parsley Validator is a specialized service designed to inspect your ServiceRegistry and identify structural flaws in your dependency graph. It specifically targets two common pitfalls: Missing Dependencies and Circular Dependencies.

Missing Dependencies

A missing dependency occurs when a service's constructor requires another service that hasn't been registered. Without validation, Parsley will attempt to resolve the dependency at runtime and fail, potentially causing a panic if not handled gracefully.

Circular Dependencies

A circular dependency happens when two or more services depend on each other (e.g., A needs B, and B needs A). This creates an infinite loop during resolution, leading to a stack overflow. While Parsley's resolver has runtime checks for this, the Validator provides much better error messaging and allows you to catch the loop during startup or even in a unit test.

Practical Example: Validating at Startup

The best practice is to run the validator immediately after completing your service registrations in main.go.

func main() {
    registry := registration.NewServiceRegistry()

    // ... Register your services and modules ...
    registry.RegisterModule(userModule)
    registry.RegisterModule(orderModule)

    // Validate the complete registry
    registryValidator := registration.NewServiceRegistrationsValidator()
    if err := registryValidator.Validate(registry); err != nil {
        // Fail fast: prevent the application from starting with a broken graph
        log.Fatalf("Service registration failed: %v", err)
    }

    // Proceed to create the resolver
    resolver := resolving.NewResolver(registry)
    // ...
}

Note: For large projects, consider writing a unit test that calls Validate(registry) on your production modules. This ensures that every pull request is checked for dependency integrity before it even reaches the CI environment.

2. Generated Proxies: Intercepting Method Calls

Separation of Concerns is a fundamental principle of clean architecture. However, implementing features like logging or performance tracing often requires modifying every service method, leading to "code rot."

Parsley addresses this through Generated Proxies and Method Interceptors.

The Architecture of Interception

By using the Parsley CLI, you can generate a "Proxy" for any interface. This proxy implements the same interface as your service but wraps the actual implementation. It provides hooks that allow MethodInterceptor services to execute logic before (Enter), after (Exit), or when an error occurs (OnError) during a method call.

Step 1: Annotating and Generating

To enable proxy generation, add the //go:generate annotation to your interface definition.

//go:generate parsley-cli generate proxy
type Greeter interface {
    SayHello(name string)
}

Running go generate ./... will invoke the parsley-cli and produce a greeter.proxy.g.go file containing the GreeterProxy interface and its implementation.

Step 2: Implementing an Interceptor

An interceptor is a standard Go service that implements the features.MethodInterceptor interface.

type loggingInterceptor struct {
    features.InterceptorBase
}

func (l *loggingInterceptor) Enter(_ any, methodName string, params []features.ParameterInfo) {
    log.Printf("Entering method: %s with params: %v", methodName, params)
}

func (l *loggingInterceptor) Exit(_ any, methodName string, results []features.ReturnValueInfo) {
    log.Printf("Exiting method: %s", methodName)
}

Step 3: Wiring it Together

You register the actual implementation, the generated proxy, and the list of interceptors in your registry.

registry.Register(NewGreeter, types.LifetimeTransient)
registry.Register(NewGreeterProxyImpl, types.LifetimeTransient)

// Enable list resolution for interceptors
features.RegisterList[features.MethodInterceptor](registry)
registry.Register(newLoggingInterceptor, types.LifetimeSingleton)

When you resolve GreeterProxy, Parsley injects the real Greeter and all registered interceptors into the proxy. Your business logic remains untouched, yet it is now fully instrumented with logging.

Operational Considerations

Performance of Proxies

Generated proxies use reflection-based parameter mapping to provide context to interceptors. While highly optimized, this does introduce a small overhead compared to direct method calls. For high-frequency, low-latency hot paths, evaluate if the benefits of separation outweigh the performance cost.

Validator in CI/CD

Running the validator is idempotent and fast. It is highly recommended to include a "sanity check" test in your CI pipeline that initializes your production ServiceRegistry and runs the Validator. This prevents "silent" failures where an application builds successfully but fails to start due to a missing environment-specific registration.

Tradeoffs and Limitations

Binary Size: Generating proxies for every service in a large application will increase your binary size. Only generate proxies for services where cross-cutting concerns are actually needed.
Complexity of Interceptors: Interceptors have access to method parameters as any types. While flexible, this requires careful handling (and potentially type assertions) if you need to inspect specific values, which can lead to less type-safe code if overused.

Summary

Reliability isn't just about writing bug-free code; it's about building systems that are easy to verify and maintain.

The Validator provides a safety net, ensuring your dependency graph is sound before your application handles its first request.
Generated Proxies allow you to implement powerful, reusable cross-cutting concerns without polluting your core domain logic.

In the next part of this series, we will dive into Effective Mocking for Testing, where we show how the Parsley CLI can simplify your unit testing workflow by generating sophisticated mocks.

Next Steps

Install the Parsley CLI: go install github.com/matzefriedrich/parsley/cmd/parsley-cli
Add a Validator call to your application's startup sequence.
Explore the Validating Service Registrations documentation for more details.

Part 5: Mastering Dependency Resolution in Go with Parsley

Matthias Friedrich — Sat, 16 May 2026 00:27:58 +0000

Navigating Complex Dependency Graphs

As applications evolve, so does the complexity of their dependency graphs. A simple "register and resolve" pattern is often sufficient for small projects, but production-grade systems frequently encounter scenarios that require more granular control over the resolution process.

You might have a service that is expensive to initialize and only needed in rare edge cases. You might need to aggregate results from multiple implementations of the same interface. Or perhaps you need to override a specific dependency at runtime for a specialized task.

In this fifth part of our series, we dive into Advanced Dependency Resolution Techniques. Building on our knowledge of Part 4: Advanced Registration Patterns in Go with Parsley, we will explore how Parsley handles lazy loading, service lists, and manual dependency provision.

1. Lazy Proxies: Deferring Heavy Initialization

In a standard DI container, resolving a service usually triggers the activation of its entire dependency tree. For resource-intensive services—such as those establishing multiple network connections or performing heavy disk I/O—this can lead to unnecessary overhead if the service isn't actually used during a specific execution path.

Parsley solves this with Lazy Proxies.

How it Works

A lazy proxy acts as a lightweight placeholder. When you resolve a lazy service, Parsley returns a features.Lazy[T] instance instead of the actual service. The real service is only activated when you explicitly call its Value(ctx) method.

// Register a service with a lazy proxy
features.RegisterLazy[Greeter](registry, NewGreeter, types.LifetimeTransient)

// Resolve the proxy
lazy, _ := resolving.ResolveRequiredService[features.Lazy[Greeter]](ctx, resolver)

// The actual NewGreeter constructor is only called here:
greeter := lazy.Value(ctx)
greeter.SayHello("John")

Once activated, the proxy caches the instance. Subsequent calls to Value() return the same object, ensuring consistent behavior while optimizing resource usage.

2. Service Lists: Managing Multiple Implementations

In modular architectures, it is common to have multiple implementations of a single interface. Examples include:

A data aggregator that fetches from multiple storage backends.
A validation pipeline that runs several independent checks.
A plugin system where different modules contribute to a core process.

While you can resolve these services individually by name (as seen in Part 4), Parsley's RegisterList[T] provides a more ergonomic way to inject all implementations as a single slice.

Practical Example: The Aggregator Pattern

Suppose we have multiple DataService implementations. We can group them into a list and inject them into an aggregator.

func main() {
    registry := registration.NewServiceRegistry()

    // Register individual implementations
    registry.Register(NewLocalDataService, types.LifetimeTransient)
    registry.Register(NewRemoteDataService, types.LifetimeTransient)

    // Group all DataService registrations into a list
    features.RegisterList[DataService](registry)

    // Register the aggregator that expects a []DataService slice
    registry.Register(newAggregator, types.LifetimeTransient)

    // ...
}

type aggregator struct {
    services []DataService
}

func newAggregator(services []DataService) *aggregator {
    return &aggregator{services: services}
}

By using RegisterList, the aggregator is automatically provided with every registered implementation of DataService. This allows you to add new implementations to your application without modifying the aggregator's code—a perfect example of the Open-Closed Principle.

3. Dynamic Overrides with `ResolveWithOptions`

Sometimes, you need to provide a specific instance to the resolver that wasn't registered in the container, or you want to temporarily override a registered dependency for a single resolution call. This is particularly useful for passing runtime configurations or injecting mock objects during testing.

The ResolveWithOptions method allows you to pass "hints" to the resolver via the WithInstance option.

// Create a specific transport instance at runtime
customTransport := &http.Transport{ ... }

// Resolve a client, but force it to use our custom transport instance
resolveType := types.MakeServiceType[*Client]()
instance, _ := resolver.ResolveWithOptions(ctx, resolveType, 
    resolving.WithInstance[*http.Transport](customTransport))

client := instance.(*Client)

This technique ensures that the resolved Client uses the provided customTransport, even if a different transport was previously registered in the ServiceRegistry.

Operational Considerations

Performance vs. Complexity

Lazy proxies improve startup time and reduce memory footprint for unused services. However, they add a layer of indirection. Use them for truly "heavy" services rather than every dependency.

Slice Injection and Order

When using RegisterList, the order of services in the slice typically matches the order of registration. If your application logic depends on a specific order (e.g., a middleware chain), ensure your registration sequence reflects this.

Tradeoffs and Limitations

Lazy Proxy Indirection: Every access to the service through a lazy proxy involves a call to Value(ctx). While the overhead is minimal after activation, it is a non-zero cost compared to direct injection.
Type Safety in Options: ResolveWithOptions returns an any type, requiring a runtime type assertion. Additionally, WithInstance must match the exact type expected by the constructor. If a constructor expects an interface and you provide a concrete pointer, the resolution may fail if the types are not perfectly aligned with Parsley's internal reflection.
Service List Exclusivity: RegisterList is primarily designed for injecting all implementations. If you only need a subset of implementations, you should continue using Named Services or custom factory functions.

Summary

Advanced resolution techniques provide the flexibility needed to handle the realities of production software.

Lazy Proxies defer resource consumption until necessary.
Service Lists enable powerful aggregation and plugin patterns.
Dynamic Overrides give you precise control over dependency injection at runtime.

In the next part of this series, we will look at Reliability and Validation, exploring how Parsley's built-in validator can catch configuration errors before your application even starts.

Next Steps

Identify a resource-intensive service in your app and experiment with RegisterLazy.
Use RegisterList to implement a simple plugin or strategy pattern.
Check the Service Lists documentation for more advanced use cases.

Part 4: Advanced Registration Patterns in Go with Parsley

Matthias Friedrich — Sat, 16 May 2026 00:19:03 +0000

Scaling Beyond Simple Registrations

In the previous parts of this series, we explored the basics of service registration and the critical role of lifetimes and scopes. As your Go application grows from a handful of services to dozens or even hundreds, managing all registrations in a single main.go function becomes impractical. It leads to "god files" that are difficult to navigate and maintain.

Furthermore, real-world applications often require more than just static wiring. You might need to:

Group related services into logical, reusable units.
Pass runtime configuration parameters to services during initialization.
Manage multiple implementations of the same interface (e.g., different storage backends).

In this article, we will explore Advanced Registration Patterns in Parsley that address these challenges: Modules, Factory Functions, and Named Services.

1. Service Modules: Organizing for Growth

Parsley Modules provide a structured way to group related service registrations. Instead of cluttering your entry point, you can encapsulate the registration logic for a specific feature or package within a module function.

Architecture: The Module Pattern

A Parsley module is simply a function that accepts a types.ServiceRegistry and returns an error. This approach allows you to keep implementation types private while exposing only the interfaces and the registration module.

func greeterModule(registry types.ServiceRegistry) error {
    // Register related services here
    registry.Register(NewGreeter, types.LifetimeTransient)
    return nil
}

Practical Example: Registering a Module

You integrate a module into your registry using the RegisterModule method.

package main

import (
    "github.com/matzefriedrich/parsley/pkg/registration"
    "github.com/matzefriedrich/parsley/pkg/types"
)

func main() {
    registry := registration.NewServiceRegistry()

    // Group registrations into a logical unit
    registry.RegisterModule(userModule)
    registry.RegisterModule(orderModule)

    // ...
}

Conditional Registration

Parsley also supports RegisterModuleIf, allowing you to enable or disable entire sets of services based on environment variables or configuration flags—ideal for feature flagging or environment-specific mocks.

// Register the DebugModule only in development
_ = registry.RegisterModuleIf(os.Getenv("ENV") == "dev", DebugModule)

2. Factory Functions: Dynamic Configuration

Standard constructor functions are excellent for static dependency wiring. However, sometimes you need to inject values that aren't known until registration time, such as a specific API endpoint or a localized salutation.

The Pattern: Functions Returning Constructors

In Parsley, a "Factory Function" is a pattern where you create a function that returns a constructor. This allows you to "bake in" configuration values via closures.

func NewGreeterFactory(salutation string) func() Greeter {
    return func() Greeter {
        return &greeter{salutation: salutation}
    }
}

Registration and Usage

When you register the result of this factory, Parsley treats the returned anonymous function as the actual service constructor.

// Register the greeter with a specific salutation
_ = registration.RegisterTransient(registry, NewGreeterFactory("Hi"))

3. Named Services: Managing Multiple Implementations

A common architectural requirement is having multiple implementations of the same interface coexist. For example, you might have a DataService that reads from a local cache and another that fetches from a remote API.

Registering Named Services

You can associate a unique name with each implementation using RegisterNamed. This allows you to specify different implementations and even different lifetimes for each.

_ = features.RegisterNamed[DataService](ctx, registry,
    registration.NamedServiceRegistration("remote", 
        NewRemoteDataService, 
        types.LifetimeTransient),
    registration.NamedServiceRegistration("local", 
        NewLocalDataService, 
        types.LifetimeTransient))

Resolving via Service Factory

To resolve a specific named implementation, Parsley provides a powerful "Service Factory" resolution pattern. You resolve a function that takes a string (the name) and returns the service.

// Resolve the factory function
factory, _ := resolving.ResolveRequiredService[func(string) (DataService, error)](scope, resolver)

// Request the specific implementation by name
remoteService, _ := factory("remote")
localService, _ := factory("local")

Note: Implementation types registered with names are also automatically available as a list. We will explore Service Lists in detail in the next part of this series.

Operational Considerations

Encapsulation and Security

By using modules, you can keep implementation structs unexported in your packages. This enforces the use of interfaces and prevents developers from bypassing the DI container to instantiate services manually, leading to a more consistent architecture.

Separation of Concerns

Advanced registration patterns help separate your Application Logic from your Wiring Logic. Your services remain clean and unaware of how they are being registered or grouped, making them more portable and easier to test in isolation.

Tradeoffs and Limitations

Complexity: While named services and factory functions offer great flexibility, they can make the dependency graph harder to visualize. Use them sparingly for clear use cases rather than as a default for every service.
Type Safety: When resolving via the service factory func(string) (T, error), passing an incorrect name string will only be caught at runtime. Ensure you have proper error handling or use constants for service names.

Summary

Advanced registration patterns transform Parsley from a simple DI container into a robust tool for managing complex application architectures. Modules provide organization, factory functions enable dynamic configuration, and named services offer the flexibility to manage multiple implementations of the same contract.

In the next part of this series, we will explore Dependency Resolution Techniques, where we dive into lazy loading, resolving lists of services, and providing manual dependencies during resolution.

Next Steps

Implement a module in your current project to group related services.
Try using a factory function to inject a configuration value into a service.
Explore the Register Module documentation for more advanced examples.

Part 3: Mastering Lifetimes and Scopes in Go with Parsley

Matthias Friedrich — Sat, 16 May 2026 00:10:22 +0000

Managing State and Lifecycle in Distributed Systems

In modern Go backend development, managing the lifecycle of a service is as critical as its implementation. For instance, a database connection pool should ideally be shared across the entire application to minimize overhead and maintain connection limits. Conversely, an authentication context or a request-specific logger should only exist for the duration of a single HTTP request to avoid state leakage between users.

In the previous article, Part 2: Mastering Service Registration in Go with Parsley, we discussed how to register services using constructors and pre-existing instances. However, registration is only half the story. The other half is determining when these services are created and how long they persist.

Without a structured dependency injection container, developers often end up passing context.Context everywhere or manually managing global variables—both of which increase complexity and hinder testability. Parsley addresses this by providing explicit control over service lifetimes.

Recap: Singleton vs. Registered Instance

In Part 2, we saw two ways to achieve singleton behavior, but they differ in one key aspect: Activation Timing.

Registered Instance (RegisterInstance): This is an eager singleton. You create the object yourself before registration. Parsley simply stores and provides the pre-existing instance. This is useful for third-party clients or legacy objects.
Singleton Registration (RegisterSingleton): This is a lazy singleton. You provide a constructor function, and Parsley only calls it the first time the service is requested.

Note: Lazy initialization is generally preferred. It reduces application startup time and ensures that heavy services are only created if they are actually needed by the current execution path.

The Three Pillars of Parsley Lifetimes

Parsley provides three distinct lifetime behaviors to manage your services effectively:

Transient: A new instance is created every time the service is requested. This is ideal for lightweight, stateless objects where you want to ensure a clean state for every consumer.
Scoped: A single instance is created and reused within a specific scope. In a web server, this usually corresponds to a single HTTP request.
Singleton: A single instance is created once and shared throughout the entire application for the lifetime of the resolver.

Architecture: The Role of Scoped Context

The Scoped lifetime is the backbone of request-based architectures. It ensures that all dependencies within a single request—such as a database transaction, a user service, and an audit logger—share the same instance of a request-specific resource.

Parsley manages this by attaching instances to a context.Context. When you create a new scope using resolving.NewScopedContext(ctx), Parsley creates a specialized context that acts as a container for that specific lifecycle.

Practical Example: Observing Service Activation

To demonstrate how lifetimes affect your application, let's create a Greeter service and observe how many times it is instantiated under different scopes.

1. Define the Service

type Greeter interface {
    SayHello(name string)
}

type greeter struct {
    id string
}

func (g *greeter) SayHello(name string) {
    fmt.Printf("Hello, %s! (Instance ID: %s)\n", name, g.id)
}

func NewGreeter() Greeter {
    g := &greeter{}
    // Use the pointer address as a simple unique ID
    g.id = fmt.Sprintf("%p", g)
    fmt.Printf("New Greeter instance activated: %s\n", g.id)
    return g
}

2. Resolve with Scopes

In the following example, we register the Greeter as Scoped. We then resolve it multiple times within two different scopes.

package main

import (
    "context"
    "fmt"
    "github.com/matzefriedrich/parsley/pkg/registration"
    "github.com/matzefriedrich/parsley/pkg/resolving"
)

func main() {
    registry := registration.NewServiceRegistry()

    // Register the constructor with a Scoped lifetime
    _ = registration.RegisterScoped(registry, NewGreeter)

    resolver := resolving.NewResolver(registry)
    ctx := context.Background()

    // --- Scope A ---
    fmt.Println("--- Starting Scope A ---")
    scopeA := resolving.NewScopedContext(ctx)
    g1, _ := resolving.ResolveRequiredService[Greeter](scopeA, resolver)
    g1.SayHello("Alice")

    g2, _ := resolving.ResolveRequiredService[Greeter](scopeA, resolver)
    g2.SayHello("Bob")

    // --- Scope B ---
    fmt.Println("\n--- Starting Scope B ---")
    scopeB := resolving.NewScopedContext(ctx)
    g3, _ := resolving.ResolveRequiredService[Greeter](scopeB, resolver)
    g3.SayHello("Charlie")
}

Output Analysis:

--- Starting Scope A ---
New Greeter instance activated: 0xc0000120a8
Hello, Alice! (Instance ID: 0xc0000120a8)
Hello, Bob! (Instance ID: 0xc0000120a8)

--- Starting Scope B ---
New Greeter instance activated: 0xc0000120b0
Hello, Charlie! (Instance ID: 0xc0000120b0)

Within Scope A, the instance is reused for both "Alice" and "Bob". When we switch to Scope B, Parsley detects a new context and activates a fresh instance.

Operational Considerations

When to Use Transient?

Use transient for services that carry no internal state or are cheap to create. This prevents accidental state leakage between different parts of your application and is the safest default if you are unsure.

When to Use Scoped?

Scoped is the "sweet spot" for backend services. Use it for anything that should be consistent across a single request but isolated from other requests:

Database transactions
Request-specific loggers with correlation IDs
User identity providers

When to Use Singleton?

Use singletons for heavy resources that should persist for the life of the process. Examples include database connection pools (*sql.DB), configuration managers, and external API clients that manage their own internal connection pooling.

Tradeoffs and Limitations

While automated lifetime management reduces boilerplate, it introduces specific engineering responsibilities:

Context Hygiene: You must ensure that resolving.NewScopedContext is called at the correct entry points (e.g., in a middleware). If you inadvertently use the root context for all resolutions, your scoped services will effectively behave as singletons.
Memory Management: Singletons stay in memory until the Resolver is destroyed. Be cautious about registering large objects as singletons if they are only needed occasionally.
Thread Safety: Singleton and Scoped services might be accessed by multiple goroutines concurrently (especially in high-concurrency web servers). Ensure your implementations are thread-safe.

Summary

Understanding lifetimes and scopes is essential for building scalable Go applications. By leveraging Transient, Scoped, and Singleton behaviors, you can ensure that your services are created at the right time and shared only when appropriate, leading to cleaner code and more predictable resource usage.

In the next part of this series, we will explore Advanced Registration Patterns, where we discuss how to organize your services into modules and use custom factory functions.

Next Steps

Explore the Lifetime Scopes documentation for more details.
Review your application's main.go and determine which services could benefit from a Scoped lifetime.

Part 2: Mastering Service Registration in Go with Parsley

Matthias Friedrich — Sat, 16 May 2026 00:01:43 +0000

The Challenge of Scalable Service Wiring

In the previous article, Part 1: Mastering Dependency Injection in Go: A Quick Start Guide, we explored how Parsley simplifies the instantiation of services. However, as an application grows, the dependency graph becomes more intricate. You no longer just have standalone services; you have services that depend on database pools, configuration providers, and external API clients.

Manually wiring these dependencies in a factory function is error-prone. If a constructor requires five different dependencies, you must ensure each is correctly initialized and passed in the right order. Furthermore, handling errors during this initialization often leads to nested if statements that clutter your startup logic.

Introducing Parsley’s Registration System

Parsley’s registration system is designed to handle this complexity by leveraging Go’s reflection capabilities. Instead of you calling the constructor, you tell Parsley about the constructor. Parsley then takes responsibility for resolving the arguments and invoking the function.

This approach centers around two primary registration methods:

Constructor Functions: For services that Parsley should instantiate.
Pre-existing Instances: For objects already created outside the container.

Architecture: How Parsley Sees Your Services

When you register a function, Parsley inspects its signature at runtime. It identifies the return type as the service being provided and the input parameters as the required dependencies.

Constructor Function Signatures

Parsley supports several idiomatic Go patterns for constructors:

Standard: func(...) T
Error-aware: func(...) (T, error) — Parsley propagates the error during resolution if the constructor fails.
Context-aware: func(context.Context, ...) (T, error) — Useful for accessing the resolution context or handling initialization timeouts.

Note: When using context.Context, it must be the first parameter in the function signature.

Practical Example: Wiring a Data Layer

Let's look at a realistic scenario where a UserService depends on a Repository.

1. Define the Components

We define the contracts as interfaces. This allows us to swap implementations (e.g., switching from a SQL database to a mock for testing) without changing the business logic.

type Repository interface {
    FindUser(id int) (*User, error)
}

type UserService interface {
    GetProfile(id int) (*Profile, error)
}

type userService struct {
    repo Repository
}

func NewUserService(repo Repository) UserService {
    return &userService{repo: repo}
}

2. Registering the Services

You register these services with the ServiceRegistry. Parsley automatically detects that NewUserService requires an implementation of Repository and will resolve it before calling the constructor.

package main

import (
    "github.com/matzefriedrich/parsley/pkg/registration"
)

func main() {
    registry := registration.NewServiceRegistry()

    // Register the repository implementation (assuming NewSqlRepository exists)
    _ = registration.RegisterTransient(registry, NewSqlRepository)

    // Register the service; Parsley resolves the repository automatically
    _ = registration.RegisterTransient(registry, NewUserService)

    // ... continue with resolving and using services ...
}

Registering Pre-existing Instances

There are cases where you cannot use a simple constructor function. For example, when you have a third-party client that requires complex configuration or a legacy object that is already initialized elsewhere. A common use case is registering a database connection pool that was initialized at application startup.

For these scenarios, Parsley provides the RegisterInstance method.

// Register a pre-configured *sql.DB instance as a singleton
db, _ := sql.Open("postgres", connStr)
_ = registration.RegisterInstance[*sql.DB](registry, db)

Warning: Any service registered via RegisterInstance is treated as a Singleton. The same instance is reused throughout the application, maintaining its state and consistency.

We will revisit this database example in a later part of this series when we discuss Factory Functions, which provide a more flexible way to handle complex initializations within the container.

Operational Considerations

Interface-Driven Design

Parsley works most effectively when you register services against interfaces. This promotes decoupling and makes your application easier to test. While you can register concrete types, doing so ties your components to specific implementations.

Error Handling

Parsley encourages explicit error handling. If a constructor returns an error, Parsley will catch it during the resolution process and return it to the caller. This ensures that your application doesn't start with partially initialized or broken services.

Validation

To build confidence in your configuration, Parsley includes built-in validation for service registrations. This feature helps prevent runtime errors caused by missing dependencies or circular references by verifying the entire dependency graph during startup.

Summary

Understanding service registration is the first step toward mastering Parsley. By using constructor functions, you delegate the complexity of dependency wiring to the framework. For more complex integration needs, manual instance registration provides a reliable escape hatch.

In the next part of this series, we will explore Understanding Lifetimes and Scopes, where we discuss how to manage the lifecycle of your services effectively.

Next Steps

Explore the Parsley Documentation for more advanced registration techniques.
Review the Registration Concepts Example in the official docs repository.

Part 1: Mastering Dependency Injection in Go: A Quick Start Guide

Matthias Friedrich — Fri, 15 May 2026 23:50:41 +0000

The Challenge of Manual Dependency Management in Go

In our introductory article, Part 0: The Case for Dependency Injection in Go, we discussed why managing dependencies manually becomes a significant burden as Go applications grow.

While this approach is transparent and easy to trace, it presents several challenges as the dependency graph deepens:

Boilerplate overhead: You often find yourself writing extensive setup code in main.go to instantiate and wire dozens of services.
Lifetime management complexity: Ensuring that a database pool is a singleton while a request logger is scoped to a specific transaction requires careful manual tracking.
Refactoring friction: Adding a new dependency to a low-level service requires updating every intermediate factory function in the chain.

You may have evaluated tools like google/wire for compile-time generation or uber-go/dig for runtime reflection-based injection. Parsley provides a balanced, reflection-based alternative designed to bridge the gap between simple configuration and automated service activation.

Introduction to Parsley

Parsley is a reflection-based dependency injection package for Go, hosted on GitHub, that implements the Inversion of Control (IoC) principle. It allows you to define how your services should be created and let the framework handle the wiring and lifetime management.

Unlike code-generation tools that can clutter your workspace, Parsley works at runtime, providing flexibility without requiring additional build steps. It is particularly well-suited for developers transitioning from ecosystems like C# (.NET) or Java (Spring) who value a clear, registry-based approach to DI.

Architectural Overview

Parsley centers around two primary concepts:

The Service Registry: A container where you define service mappings, constructor functions, and lifetime behaviors.
The Resolver: The component that traverses the dependency graph and instantiates services as needed.

Parsley supports three distinct lifetime behaviors:

Singleton: A single instance is created and shared across the entire application.
Scoped: An instance is created once per scope (e.g., per HTTP request).
Transient: A new instance is created every time the service is requested.

Practical Example: A Simple Greeter

To see Parsley in action, let's build a simple application that greets the user.

1. Define the Abstraction

We start by defining a Greeter interface. This follows the Go practice of defining contracts at the consumer level (or close to it) to enable decoupling.

type Greeter interface {
    Greet(name string) string
}

2. Implement the Service

We implement a concrete greeter type. The struct can remain unexported because it will be instantiated via a constructor function that returns the exported interface.

type greeter struct{}

func (s *greeter) Greet(name string) string {
    return fmt.Sprintf("Hello, %s!", name)
}

func NewGreeter() Greeter {
    return &greeter{}
}

3. Register and Resolve the Service

The following example demonstrates how to set up the registry, register the service as transient, and resolve it using the resolving package.

package main

import (
    "context"
    "fmt"

    "github.com/matzefriedrich/parsley/pkg/registration"
    "github.com/matzefriedrich/parsley/pkg/resolving"
)

func main() {
    // Initialize the registry
    registry := registration.NewServiceRegistry()

    // Register the constructor function
    _ = registration.RegisterTransient(registry, NewGreeter)

    // Create a resolver and a scope
    resolver := resolving.NewResolver(registry)
    ctx := context.Background()
    scope := resolving.NewScopedContext(ctx)

    // Resolve the Greeter service
    greeterService, err := resolving.ResolveRequiredService[Greeter](scope, resolver)
    if err != nil {
        panic(err)
    }

    fmt.Println(greeterService.Greet("Parsley"))
}

Operational Considerations

When adopting a reflection-based DI container like Parsley, keep the following operational concerns in mind:

Error Handling: Parsley encourages explicit error handling. While the registry functions return errors, you should also ensure your constructor functions return errors if they can fail during initialization.
Startup Performance: Reflection has a minor performance cost at startup. For most backend applications, this is negligible compared to database connections or network initialization, but it should be measured in latency-sensitive environments.
Context Management: Always use NewScopedContext to ensure that scoped services are properly tracked and disposed of if they implement any cleanup logic.

Tradeoffs and Limitations

Parsley is designed for simplicity and ease of use, but it involves tradeoffs common to reflection-based DI:

Runtime vs. Compile-time: Unlike wire, Parsley cannot catch missing dependencies at compile-time. You should use Parsley's built-in validation features (which we will cover in a later part of this series) during your CI/CD process or application startup.
Reflection: While Go's reflection is efficient, it is still slower than direct instantiation. Parsley optimizes this by caching resolution plans, but the very first resolution of a type will incur a small overhead.

Summary

Parsley offers a robust way to implement Inversion of Control in Go applications without the complexity of code generation. By leveraging constructor functions and automated lifetime management, it reduces boilerplate and allows developers to focus on business logic rather than wiring.

In the next part of this series, we will dive deeper into Service Registration Fundamentals, exploring how to register preexisting instances and handle more complex constructor signatures.

Next Steps

Explore the Parsley Documentation on GitHub.
Experiment with different lifetimes (Singleton vs. Scoped) in your own projects.

Part 0: The Case for Dependency Injection in Go

Matthias Friedrich — Fri, 15 May 2026 23:39:25 +0000

The Simplicity of Go

Go is celebrated for its simplicity. We value explicit code over "magic," composition over complex inheritance hierarchies, and the ability to understand a program by tracing its execution path from main(). This philosophy is precisely why Dependency Injection (DI) is often a controversial topic in the Go community.

Many Go developers associate DI with the heavy, reflection-heavy frameworks found in Java or C#. They fear that introducing a DI container will obscure the application's logic, making it harder to debug and maintain.

However, as applications grow from small microservices into complex production systems, manual dependency management becomes a burden. In this introductory "Part 0" of this series, we will examine the case for DI in Go and establish why a lightweight container like Parsley might be the right choice for your next project.

1. The Problem: The "Dependency Hell" of Manual Wiring

In a small Go application, manual wiring is straightforward. You create your database connection, pass it to your repository, pass the repository to your service, and finally pass the service to your HTTP handler.

func main() {
  db := sql.Open(...)
  repository := postgres.NewUserRepository(db)  
  userService := users.NewUserService(repository) 
  requestHandler := api.NewUserHandler(userService)

  http.ListenAndServe(":8080", requestHandler)
}

This is explicit and clear. However, consider what happens when:

Your service now requires a logger, a metrics client, and an email provider.
You have 50 different handlers, each requiring a different subset of 20 shared services.
You need to manage different service lifetimes (e.g., a shared cache vs. a per-request transaction).

Suddenly, your main() function or initialization logic becomes a massive "wiring" section. Adding a single dependency to a low-level service requires updating every intermediate constructor in the chain. This is tight coupling in its most tedious form.

2. DI is a Pattern, Not Just a Library

It is important to distinguish between Dependency Injection (the pattern) and DI Containers (the tool).

The Pattern: Passing dependencies into a struct rather than having the struct create them itself. This is idiomatic Go and essential for testability.
The Container: A tool that automates the process of creating and injecting those dependencies.

Parsley is a DI container, but it is built specifically for the Go ecosystem. It doesn't use XML configuration or runtime "magic" that hides the control flow. Instead, it provides a Service Registry where you define how to create your services using standard Go constructor functions.

3. Bridging the Gap: How Parsley Respects Go Idioms

When transitioning from languages like C# or Java, developers expect the container to do everything. In Go, we want to maintain control. Parsley balances these needs by focusing on:

Explicitness: You explicitly register every service. There is no "auto-discovery" that scans your packages and guesses what you need.
Type Safety: Parsley uses Go's type system to ensure that the dependencies provided match the dependencies requested.
Minimal Abstraction: You continue to write standard Go constructors. Parsley simply orchestrates their execution.

4. The Engineering Tradeoffs

Choosing to use a DI container is an engineering decision with real tradeoffs.

Advantages

Decoupling: Services no longer need to know how to construct their dependencies.
Testability: Swapping a real database for a mock becomes trivial because the service only cares about the interface it receives.
Lifecycle Management: Containers handle the complexities of Singleton vs. Transient services, ensuring resources are shared or recreated as needed.

Non-Goals & Limitations

Startup Overhead: Parsley performs type checking and dependency graph construction at startup. While extremely fast, it is a cost not present in manual wiring.
Learning Curve: Developers need to understand concepts like service lifetimes and scopes.

Summary

Dependency Injection isn't about making Go look like Java. It's about managing complexity so you can focus on writing business logic instead of boilerplate wiring code. By using a tool that aligns with Go's values, you can build systems that are both highly modular and easy to understand.

In the next part, Part 1: Mastering Dependency Injection in Go: A Quick Start Guide, we will get our hands dirty and see how to set up your first Parsley registry.

Next Steps

Evaluate your current project: How many lines of code are dedicated purely to manual dependency wiring?
Read more about the Inversion of Control (IoC) principle in the official Parsley documentation.

DEV Community: Matthias Friedrich

Part 7: Testing with Confidence: Mocking and Recap

The Role of Mocks in Unit Testing

1. Generating Mocks with Parsley CLI

Step 1: Interface Annotation

Step 2: Code Generation

2. Configuring and Verifying Mocks

Practical Example: Testing with Mocks

Assertion Helpers

3. Decoupling Code Generation from DI Runtime

Series Recap: Mastering Dependency Injection

Join the Community

Next Steps

Part 6: Ensuring Reliability - Validation and Proxies with Parsley

The Challenge of Complexity

1. The Validator: Catching Errors Early

Missing Dependencies

Circular Dependencies

Practical Example: Validating at Startup

2. Generated Proxies: Intercepting Method Calls

The Architecture of Interception

Step 1: Annotating and Generating

Step 2: Implementing an Interceptor

Step 3: Wiring it Together

Operational Considerations

Performance of Proxies

Validator in CI/CD

Tradeoffs and Limitations

Summary

Next Steps

Part 5: Mastering Dependency Resolution in Go with Parsley

Navigating Complex Dependency Graphs

1. Lazy Proxies: Deferring Heavy Initialization

How it Works

2. Service Lists: Managing Multiple Implementations

Practical Example: The Aggregator Pattern

3. Dynamic Overrides with ResolveWithOptions

Operational Considerations

Performance vs. Complexity

Slice Injection and Order

Tradeoffs and Limitations

Summary

Next Steps

Part 4: Advanced Registration Patterns in Go with Parsley

Scaling Beyond Simple Registrations

1. Service Modules: Organizing for Growth

Architecture: The Module Pattern

Practical Example: Registering a Module

Conditional Registration

2. Factory Functions: Dynamic Configuration

The Pattern: Functions Returning Constructors

Registration and Usage

3. Named Services: Managing Multiple Implementations

Registering Named Services

Resolving via Service Factory

Operational Considerations

Encapsulation and Security

Separation of Concerns

Tradeoffs and Limitations

Summary

Next Steps

Part 3: Mastering Lifetimes and Scopes in Go with Parsley

Managing State and Lifecycle in Distributed Systems

Recap: Singleton vs. Registered Instance

The Three Pillars of Parsley Lifetimes

Architecture: The Role of Scoped Context

Practical Example: Observing Service Activation

1. Define the Service

2. Resolve with Scopes

Operational Considerations

When to Use Transient?

When to Use Scoped?

When to Use Singleton?

Tradeoffs and Limitations

Summary

Next Steps

Part 2: Mastering Service Registration in Go with Parsley

The Challenge of Scalable Service Wiring

Introducing Parsley’s Registration System

Architecture: How Parsley Sees Your Services

3. Dynamic Overrides with `ResolveWithOptions`