
## Red, Green, Refactor
Test-Driven Development (TDD) is the practice of writing a failing unit test before writing the code to make the test pass, then cleaning up your code. This is the "red, green, refactor" cycle.
[![](/images/posts/TDD-Red-Green-Refactor.png)](/images/posts/TDD-Red-Green-Refactor.png)

It helps with clarity of thought, increases flow, and results in modular designs that are maintainable. You can probably tell I'm a fan. It's one of the practices that has helped me become a better software engineer over the years. While there are a lot of resources out there to learn about TDD, most of them gloss over an important aspect that makes it much more effective: it matters _what_ you try to test.

## Test the Behavior
For TDD to be effective it's important to test the _behavior_ of a component instead of its internal implementation details. This allows changing the component's internal logic without changing its tests. If the component's interface to other components in the system does not change and it can be used the same way as before, then the tests should not need to change either. This allows each individual component of the system to be enhanced, fixed, refactored, rebuilt using a different technology, or even completely replaced with minimal changes to the unit tests.

If the tests are tightly coupled to the internal implementation of a component, then it makes it difficult to modify the component without also modifying the tests. By focusing on only testing the behavior of a component, the unit tests should not be touched at all when changing its internal implementation. Instead, the tests become an important tool to verify that the internal change has not broken the component's behavior.

## Component Interfaces
Whenever we build a system, be it large or small, we should break it down into components that each have a unique responsibility. This modularity provides a lot of benefits like easier restructuring, simplicity, maintainability, testability, reducing the cognitive load of software engineers, and more. By identifying the components, we're also defining the boundaries between them and the interfaces they use to communicate with each other.

For each component we should strive to make it easy to change the internal implementation of the component, but we should make it a bit harder to change the interfaces between them. These interfaces are the components' API contracts. The hard part is figuring out the granularity of the components and their responsibility. This comes with experience and depends on many factors. There are many schools of thought on how to break down a system and identify its components (e.g. domain-driven design, event storming, event modeling, clean architecture, etc.), but I generally recommend designing it out visually and running through a few of the most important user scenarios. If you find the current design difficult and complicated, try a different one and keep iterating until you find one that works well.

With some practice, you'll get better at identifying reasonable component boundaries.

## Example Repository Implementation
One component boundary I find particularly useful encapsulates access to persistent data using the repository pattern. When building a feature that requires storing and retrieving data, it's usually beneficial to isolate the details of the database technology from the application logic. A repository's single responsibility is to manage the persistent data for an application (or a portion of it).

Let's build a simple repository in Go that shows the difference between the bad implementation-driven vs the good behavior-driven approaches to writing tests. We'll create a repository that saves and retrieves users. Each user only has a name, and just for simplicity we'll "persist" the data in-memory using a map, but you can imagine a DB engine, file system, or object store instead.

Both approaches are shown below:
- [Implementation-driven approach to testing](#implementation-driven-approach-to-testing) (Don't do it like this!)
- [Behavior-driven approach to testing](#behavior-driven-approach-to-testing) (Do it like this, instead!)

Here's the code from these examples if you want to compare the results side-by-side: [github.com/benjohns1/tdd-and-testing-behavior](https://github.com/benjohns1/tdd-and-testing-behavior)

### Implementation-driven approach to testing
_**Don't do it like this!**_

Here's what a user looks like:

<Code language="go" heading="File: user.go">
{`package app

type User struct {
	Name string
}
`}
</Code>

And here's a stub user repo to start with:
<Code language="go" heading="File: repo/users.go">
{`package repo

type Users struct{}
`}
</Code>

#### Save a User
Let's start with saving a user in the repo. We want a Save() method that accepts a user and returns a possible error. We'll write a test for a repo method Save() that we haven't written yet, so it will fail to compile initially.

##### Test: store a user by name to an empty map
Here's our first failing test, setup with a common table-driven test structure that I find useful:

###### Red Step 1
<Code language="go" heading="File: repo/users_test.go">
{`package repo

import (
	app "github.com/benjohns1/tdd-and-testing-behavior/implementation-driven"
	"reflect"
	"testing"
)

func TestUser_Save(t *testing.T) {
	type args struct {
		user app.User
	}
	tests := []struct {
		name    string
		repo    Users
		args    args
		want    Users
		wantErr error
	}{
		{
			name: "store a user by name to an empty map",
			args: args{
				user: app.User{Name: "Ender"},
			},
			want: Users{
				map[string]app.User{
					"Ender": {Name: "Ender"},
				},
			},
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			err := tt.repo.Save(tt.args.user)
			if !reflect.DeepEqual(err, tt.wantErr) {
				t.Errorf("Save() error = %v, wantErr %v", err, tt.wantErr)
				return
			}
			if !reflect.DeepEqual(tt.repo, tt.want) {
				t.Errorf("Save() = %+v, want %+v", tt.repo, tt.want)
			}
		})
	}
}
`}
</Code>

This test will fail to compile, so let's write the code to make it pass:
###### Green Step 2
<Code language="go" heading="File: repo/users.go">
{`package repo

import app "github.com/benjohns1/tdd-and-testing-behavior/implementation-driven"

type Users struct {
	users map[string]app.User
}

func (u *Users) Save(user app.User) error {
	u.users = map[string]app.User{
		user.Name: user,
	}
	return nil
}
`}
</Code>

Alright, our test passes!

###### Refactor Step 3
The next step is to refactor our code and clean it up, but the code is so simple at this point let's move on to the next test cycle.

##### Test: store a new user by name to a map that already has a user

###### Red Step 1
<Code language="go" heading="File: repo/users_test.go (partial)">
{`// ...
		{
			name: "store a new user by name to a map that already has a user",
			repo: Users{
				map[string]app.User{
					"Ender": {Name: "Ender"},
				},
			},
			args: args{
				user: app.User{Name: "Valentine"},
			},
			want: Users{
				map[string]app.User{
					"Ender":     {Name: "Ender"},
					"Valentine": {Name: "Valentine"},
				},
			},
		},
// ...
`}
</Code>

This test will fail because of our overly-simplistic implementation from the first test, so let's fix that:
###### Green Step 2
<Code language="go" heading="File: repo/users.go (partial)">
{`func (u *Users) Save(user app.User) error {
	if u.users == nil {
		u.users = map[string]app.User{
			user.Name: user,
		}
	} else {
		u.users[user.Name] = user
	}
	return nil
}
`}
</Code>

This makes our test pass, but now we have a bit of cruft in our logic so let's simplify it:

###### Refactor Step 3
<Code language="go" heading="File: repo/users.go (partial)">
{`func (u *Users) Save(user app.User) error {
	if u.users == nil {
		u.users = make(map[string]app.User, 1)
	}
	u.users[user.Name] = user
	return nil
}
`}
</Code>
And our test is still passing!

##### Test: return an error if the user's name already exists
If a user already exists in our repo with the same name, we want an error to be returned so let's write a test for that:

###### Red Step 1
<Code language="go" heading="File: repo/users_test.go (partial)">
{`// ...
		{
			name: "return an error if the user's name already exists",
			repo: Users{
				map[string]app.User{
					"Peter": {Name: "Peter"},
				},
			},
			args: args{
				user: app.User{Name: "Peter"},
			},
			want: Users{
				map[string]app.User{
					"Peter": {Name: "Peter"},
				},
			},
			wantErr: fmt.Errorf("user name \\\"Peter\\\" already exists"),
		},
// ...
`}
</Code>

###### Green Step 2
<Code language="go" heading="File: repo/users.go (partial)">
{`func (u *Users) Save(user app.User) error {
	if _, exists := u.users[user.Name]; exists {
		return fmt.Errorf("user name \\\"Peter\\\" already exists")
	}
	if u.users == nil {
		u.users = make(map[string]app.User, 1)
	}
	u.users[user.Name] = user
	return nil
}
`}
</Code>

Notice the naive hard-coded error message? It's the simplest code that makes our test pass, but we want to clean that up in the refactor step:

###### Refactor Step 3
<Code language="go" heading="File: repo/users.go (partial)">
{`func (u *Users) Save(user app.User) error {
	if _, exists := u.users[user.Name]; exists {
		return fmt.Errorf("user name %q already exists", user.Name)
	}
	if u.users == nil {
		u.users = make(map[string]app.User, 1)
	}
	u.users[user.Name] = user
	return nil
}
`}
</Code>

Here's [the code for this approach](https://github.com/benjohns1/tdd-and-testing-behavior/tree/main/implementation-driven)

#### Is there a better way?
At this point, we've only written tests and functionality around saving a 
user. We could continue on to build out the functionality to retrieve users taking
 the same approach. It's great that we're using the basic TDD red, green, refactor cycle, but 
first think about what would happen if we needed to change the implementation. Could we add a user ID field index? Or upgrade to a persistent DB instead of in-memory? In either of these scenarios we'd need to _completely_ rewrite all of these tests because they are tightly coupled to the internal implementation of the user repo.

I want to show you a better way.

### Behavior-driven approach to testing
Let's start off fresh with our basic user and repo stub:

<Code language="go" heading="File: user.go">
{`package app

type User struct {
	Name string
}
`}
</Code>

<Code language="go" heading="File: repo/users.go">
{`package repo

type Users struct{}
`}
</Code>

#### Save a User
Just like before, let's start with saving a user in the repo. But instead of thinking in terms of the steps that the repo will need to take to accomplish this, think about how we want the repo to behave when it is used. How does this change our perspective of the Save() method? Well, what behavior do we want from the repo when we save a user? After we save a user, we should then be able to get it back! If we think of it this way, then it doesn't matter _how_ the repo stores the data. It only matters that if we save it, we can then get the same data back.

Let's use TDD to write our first behavioral test.

##### Spec: Should save a user to an empty repo
When writing this first test, we need to spend a bit more time thinking about the interface to get a user back out of the repo, too. In this example we're going to use a GetAll() function that returns a slice of all the users in the repo. We could also retrieve a single user by name, or some other way that aligns with the other use-cases.

###### Red Step 1
Notice the package name is repo_test instead of just repo. We want to test the repo's _interface_ so we only want to access its publicly exported methods. Go allows appending _test to the package name to enforce this.
<Code language="go" heading="File: repo/users_test.go">
{`package repo_test

import (
	app "github.com/benjohns1/tdd-and-testing-behavior/behavior-driven"
	"github.com/benjohns1/tdd-and-testing-behavior/behavior-driven/repo"
	"reflect"
	"testing"
)

func TestUser_Save(t *testing.T) {
	type args struct {
		user app.User
	}
	tests := []struct {
		name      string
		repo      repo.Users
		args      args
		wantErr   error
		wantUsers []app.User
	}{
		{
			name: "should save a user to an empty repo",
			args: args{
				user: app.User{Name: "Ender"},
			},
			wantUsers: []app.User{{Name: "Ender"}},
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			err := tt.repo.Save(tt.args.user)
			if !reflect.DeepEqual(err, tt.wantErr) {
				t.Errorf("Save() error = %v, wantErr %v", err, tt.wantErr)
				return
			}
			got, err := tt.repo.GetAll()
			if err != nil {
				t.Fatal(err)
			}
			if !reflect.DeepEqual(got, tt.wantUsers) {
				t.Errorf("After Save(), GetAll() = %+v, wantUsers %+v", got, tt.wantUsers)
			}
		})
	}
}
`}
</Code>

###### Green Step 2
To make this test pass, we need both a Save() and GetAll() method. Remember, we're just writing the bare minimum code to make the test pass in this step!

<Code language="go" heading="File: repo/users.go">
{`package repo

import (
	app "github.com/benjohns1/tdd-and-testing-behavior/behavior-driven"
)

type Users struct{}

func (u *Users) Save(user app.User) error {
	return nil
}

func (u *Users) GetAll() ([]app.User, error) {
	return []app.User{{Name: "Ender"}}, nil
}
`}
</Code>

###### Refactor Step 3
Now we refactor our naive code into little better solution. And we have our test to verify it is still correct:

<Code language="go" heading="File: repo/users.go (partial)">
{`type Users struct {
	user app.User
}

func (u *Users) Save(user app.User) error {
	u.user = user
	return nil
}

func (u *Users) GetAll() ([]app.User, error) {
	return []app.User{u.user}, nil
}
`}
</Code>

##### Spec: Should save a user to a repo that already has a user in it

###### Red Step 1
<Code language="go" heading="File: repo/users_test.go (partial)">
{`// ...
		{
			name: "should save a user to a repo that already has a user in it",
			repo: func() repo.Users {
				r := repo.Users{}
				if err := r.Save(app.User{
					Name: "Ender",
				}); err != nil {
					t.Fatal(err)
				}
				return r
			}(),
			args: args{
				user: app.User{Name: "Valentine"},
			},
			wantUsers: []app.User{
				{Name: "Ender"},
				{Name: "Valentine"},
			},
		},
// ...
`}
</Code>

###### Green Step 2
<Code language="go" heading="File: repo/users.go (partial)">
{`type Users struct {
	users []app.User
}

func (u *Users) Save(user app.User) error {
	u.users = append(u.users, user)
	return nil
}

func (u *Users) GetAll() ([]app.User, error) {
	return u.users, nil
}
`}
</Code>

###### Refactor Step 3
Let's make our repo encapsulation a bit better by not allowing mutation of the repo's internal slice:

<Code language="go" heading="File: repo/users.go (partial)">
{`func (u *Users) GetAll() ([]app.User, error) {
	out := make([]app.User, 0, len(u.users))
	for _, user := range u.users {
		out = append(out, user)
	}
	return out, nil
}
`}
</Code>


##### Spec: Should fail if a user's name already exists

###### Red Step 1
<Code language="go" heading="File: repo/users_test.go (partial)">
{`// ...
		{
			name: "should fail if a user's name already exists",
			repo: func() repo.Users {
				r := repo.Users{}
				if err := r.Save(app.User{
					Name: "Peter",
				}); err != nil {
					t.Fatal(err)
				}
				return r
			}(),
			args: args{
				user: app.User{Name: "Peter"},
			},
			wantUsers: []app.User{{Name: "Peter"}},
			wantErr:   fmt.Errorf("user name \\\"Peter\\\" already exists"),
		},
// ...
`}
</Code>

###### Green Step 2
<Code language="go" heading="File: repo/users.go (partial)">
{`func (u *Users) Save(user app.User) error {
	for _, current := range u.users {
		if current.Name == user.Name {
			return fmt.Errorf("user name \\\"Peter\\\" already exists")
		}
	}
	u.users = append(u.users, user)
	return nil
}
`}
</Code>

###### Refactor Step 3
Clean up the naive error message:

<Code language="go" heading="File: repo/users.go (partial)">
{`func (u *Users) Save(user app.User) error {
	for _, current := range u.users {
		if current.Name == user.Name {
			return fmt.Errorf("user name %q already exists", user.Name)
		}
	}
	u.users = append(u.users, user)
	return nil
}
`}
</Code>

Here's [the code for this approach](https://github.com/benjohns1/tdd-and-testing-behavior/tree/main/behavior-driven)

## Conclusion
Take a look at your implementation using the behavior-driven approach. For the same amount of effort, we've also implemented retrieving users from the repo, too. Now let's ask the same questions we did earlier: Could we add a user ID field index? Or upgrade to a persistent DB instead of in-memory? Both of these scenarios could be accomplished without modifying our existing tests (apart from maybe some test setup to implement a real DB backend).

Our behavior tests are much more robust, and they're validating what we really care about: the behavior of the repo. If the interface changes we _want_ the tests to break because that means we've changed the repo's behavior. If we need to refactor the internals of the repo, we can use our tests to be confident that we haven't broken any existing use-cases.

TDD is an incredibly useful practice but only if you are testing behavior!


The importance of testing behavior when using test-driven development

TDD and Testing Behavior


In this fifth and final part of the Go middleware tutorial series, we'll use what we've learned to create a more structured API example that includes basic request logging, authorization, and response formatting.  
  
Middleware will help simplify our API code and promote the [single responsibility principle](https://en.wikipedia.org/wiki/Single_responsibility_principle).

Part 5 - API Middleware Example
-------------------------------

The code for this tutorial can be found here: [https://github.com/benjohns1/go-middleware-example/tree/master/apiexample](https://github.com/benjohns1/go-middleware-example/tree/master/apiexample)  

### API Example Code

Rather than building up the code from scratch as in previous tutorials, we're going to start with the completed code and discuss each component. The project is structured as follows:

*   [businessdomain/](https://github.com/benjohns1/go-middleware-example/tree/master/apiexample/businessdomain) - contains all business logic, separately from infrastructure
    *   [businesslogic.go](https://github.com/benjohns1/go-middleware-example/blob/master/apiexample/businessdomain/businesslogic.go) - example logic
*   [middleware/](https://github.com/benjohns1/go-middleware-example/tree/master/apiexample/middleware) - contains all API middleware infrastructure
    *   [auth.go](https://github.com/benjohns1/go-middleware-example/blob/master/apiexample/middleware/auth.go) - middleware to handle authentication
    *   [chain.go](https://github.com/benjohns1/go-middleware-example/blob/master/apiexample/middleware/chain.go) - middleware chain helpers
    *   [logger.go](https://github.com/benjohns1/go-middleware-example/blob/master/apiexample/middleware/logger.go) - middleware to handle API logging
*   [main.go](https://github.com/benjohns1/go-middleware-example/blob/master/apiexample/main.go) - entry point

### Business Logic

This is where the meat and potatoes of the application reside. All the logical rules that the business, client, or user expects from the system should be driven from here without depending on implementation details such as HTTP, DB technology, etc. It's a great idea to write your business logic as decoupled as possible from infrastructure concerns, as has been recommended time and time again with architectural patterns like [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html), Hexagonal Architecture, and Onion Architecture.

businessdomain/businesslogic.go:
<Gist src="https://gist.github.com/benjohns1/71e377bada15692099442b12b661a1a9.js"/>

In this example, we're not actually _doing_ anything except returning a static struct, but notice that this package does not depend on anything related to the API delivery mechanism or database; it could easily be reused for a terminal or GUI application, for example.

### Middleware Chain

Now for the API infrastructure: this is where the recursive chain style of middleware is implemented as described in [Part 2](/posts/20190209-go-middleware-part-2) of this series. This could be replaced by any of the variants we've discussed or by one of the many router/mux packages available.

middleware/chain.go:
<Gist src="https://gist.github.com/benjohns1/a7072db1ee68d2ad064db408eb062e40.js"/>

The Factory type defines a valid function that can be chained as middleware.

### Logging Middleware

Similar to what we've shown in previous examples, this file contains HTTP request logging middleware.

middleware/logger.go:
<Gist src="https://gist.github.com/benjohns1/16f2518c45c4e01cea780e8458b03fb9.js"/>

The Logger function is of type Factory so it can be used directly as a middleware function. We're also implementing a custom WriteHeader function to capture the status code as described in [Part 4](/posts/20190224-go-middleware-part-4).

### Authorization Middleware

This middleware provides two strategies for authorization:

1.  Random Auth - randomly reject or accept a request (example purposes only!)
2.  Public Auth - always authorized

middleware/auth.go:
<Gist src="https://gist.github.com/benjohns1/be823fcd5737890cd8e29a45c87136e6.js"/>

The Auth function accepts an auth strategy function as a parameter to determine whether the user is authorized, and returns a Factory function that can be chained as middleware.

### Putting It All Together

Each of the previous files contain a specific and unique responsibility, and our business logic has no dependency on the API delivery mechanism or infrastructure. Let's put it all together into one informative (but... probably useless) API!

main.go:
<Gist src="https://gist.github.com/benjohns1/035fa81fd9768c05e5ec925f837ee5ed.js"/>

Our main function creates two routes, each using a different auth strategy:

1.  [localhost:8080/api/v1/random/](localhost:8080/api/v1/random/)
2.  [localhost:8080/api/v1/public/](localhost:8080/api/v1/public/)

The requestHandler function calls the business logic and transforms the return value into an appropriate HTTP response. Notice again that the business logic knows nothing about the transport mechanism; the final data format and transport type is handled here. This could be extended to allow additional data formats and more complex transformation steps using the middleware techniques we've just learned.  
  
This concludes the Go Middleware series. Now go forth a conqueror and win great API victories!  
  

[Go Middleware - Part 4](/posts/20190224-go-middleware-part-4)


In this fifth and final part of the Go middleware tutorial series, we'll use what we've learned to create a more structured API example...

Go Middleware - Part 5


In this fourth part of the Go middleware tutorial series, we'll discuss passing custom state along the request chain. This provides the flexibility to pass data from one middleware handler to another one somewhere else in the chain.  

Part 4 - Custom State Middleware Example
----------------------------------------

We want to be able to pass custom data from one middleware function to another, but without breaking encapsulation or modularity. We also want to be very explicit and type-safe about the data that is being passed so it is easy to maintain.  
  
The code for this tutorial can be found here: [https://github.com/benjohns1/go-middleware-example/blob/master/customstate/main.go](https://github.com/benjohns1/go-middleware-example/blob/master/customstate/main.go)

### Step 1 - Simple Server

We'll create a simple server that uses the recursive middleware approach from [part 2](/posts/20190209-go-middleware-part-2) with a few modifications:  

main.go:
<Gist src="https://gist.github.com/benjohns1/ec5f243af7c72c6be9e3d9dbc1d5ced1.js"/>

This code should be familiar but for a couple slight differences:  

1.  In main() we're passing in a function literal (i.e. anonymous or lambda function) to the businessLogic function that randomly returns true or false. This is just for brevity and is not all that relevant.
2.  In businessLogic() we're explicitly setting a success or failure HTTP status code, depending on whether the decider function returns true or false.

Wouldn't it be nice to be able to log that status code in our logger middleware? But take a look at the http.ResponseWriter interface; there's no way to retrieve its value after its been set!  

### Step 2 - Implement http.ResponseWriter

Here's an example of where Go's interfaces really shine. We can define a new struct type to contain the data that we need to keep track of, and as long as we implement the http.ResponseWriter interface, our struct can be passed through _any_ middleware handler without issue (even through handlers that don't know or care about our custom data):  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/67878e5bdf2aed233ee8cf78dea205d3.js"/>


The logResponseWriter type stores the original http.ResponseWriter sent to the logger function and passes through all of the required interface function calls. It extends the standard functionality by storing the status code in an easily-accessible parameter when the WriteHeader interface method is called.  
  
The logger function creates our custom struct and passes it into the next middleware handler in the chain (which is fine because the struct implements the http.ResponseWriter interface). It then accesses the status parameter for logging after the subsequent handlers have run. Notice that we didn't touch a single line of our business logic to implement this, because we leveraged the http.ResponseWriter interface's existing WriteHeader function.  

### Step 3 - Custom Data

You might notice that this only works well for the status code in particular (or for any data that is passed to an existing http.ResponseWriter interface method). So how do we pass additional custom data?  

[![](/images/posts/customize-all-the-things.jpg)](/images/posts/customize-all-the-things.jpg)

In order to do this, both middleware handlers need to be aware of some sort of interface for getting/setting the data. In this example we'll modify our business logic so that it is aware of the logResponseWriter struct, but you can imagine decoupling this further using additional interfaces.  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/f4cab6ed6428f14feaeb311062ffec01.js"/>

We've added a new field "extra" to store our custom string data. The logger function logs this string after the request is complete.  
  
The businessLogic function does a bit of work to check if the custom interface is implemented. It uses a type assertion to check whether a logResponseWriter was passed in as the http.ResponseWriter, and if so it has type-safe access to the "extra" field.  
  
You can extend this approach to pass any type of custom data up and down the middleware chain. This has a lot of benefit over using, say, a [context](https://golang.org/pkg/context/) to store values on the response writer object, because it clearly defines type-safe fields in an explicit struct, making the code much more readable and less error-prone. However, keep in mind that this approach is still more complicated than simply passing parameters into functions, so only use it when needed.  
  
In the final [part 5](/posts/20190317-go-middleware-part-5) of this series, we'll look at a slightly more realistic and structured example of a JSON API that uses the middleware approaches we've discussed.  

### Final Server Code

main.go:
<Gist src="https://gist.github.com/benjohns1/f329429b730f2abd7f72067036e08353.js"/>

[Go Middleware - Part 3](/posts/20190215-go-middleware-part-3)

[Go Middleware - Part 5](/posts/20190317-go-middleware-part-5)


In this fourth part of the Go middleware tutorial series, we'll discuss passing custom state along the request chain.

Go Middleware - Part 4


In this third part of the Go middleware tutorial series, we'll quickly look at a common variant on the recursive middleware implementation from [part 2](/posts/20190209-go-middleware-part-2).  

Part 3 - Final Handler Middleware Example
-----------------------------------------

[![](/images/posts/samuel-zeller-379406-unsplash.jpg)](/images/posts/samuel-zeller-379406-unsplash.jpg)

Photo by [Samuel Zeller](https://unsplash.com/photos/oBb-Y26PJgg?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)

This variant separates the idea of middleware from the final handler that processes the request's business logic. This means that each middleware chain can have any number of middleware handler functions, but only a single final handler runs at the end of the chain. This allows the final handler to not need to accept a "next" handler, keeping our business logic a bit cleaner.  
  
The code for this tutorial can be found here:  
[https://github.com/benjohns1/go-middleware-example/blob/master/finalhandler/main.go](https://github.com/benjohns1/go-middleware-example/blob/master/finalhandler/main.go)  

### Step 1 - Modified Chain Functions

An additional parameter can simply be added to the chain functions:  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/0e74d47c067d9e8845745f1731abadd0.js"/>

We're passing in a new http.HandlerFunc as the first parameter and using it as the final function in the chain (instead of an empty function as we were previously).  

### Step 2 - Simplified Business Logic

Then we pass our handler in as the first parameter in the chain (rather than the last) and remove the extra closure from the businessLogic function so that it just supplies an http handlerFunc and doesn't need to call next():  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/66e7e099b9a93b887c03bcd9c36b0627.js"/>

This keeps our primary request business logic clean, and with the handler function as the first parameter it's easier to read in a long list of routes.  
  
In Part 4 we'll look at passing custom state up and down the request chain in a type-safe way.

### Final Server Code

main.go:
<Gist src="https://gist.github.com/benjohns1/afd9adbde74aca973fac732c7fd82180.js"/>

[Go Middleware - Part 2](/posts/20190209-go-middleware-part-2)

[Go Middleware - Part 4](/posts/20190224-go-middleware-part-4)


In this third part of the Go middleware tutorial series, we'll quickly look at a common variant on the recursive middleware implementation from part 2.

Go Middleware - Part 3


In this second part of the Go middleware tutorial series, we'll cover a recursive approach that provides a couple benefits beyond the simple loop chain example from [part 1](/posts/20190206-go-middleware-part-1), including:  

1.  the ability to _wrap_ around the next handler in the chain (i.e. add logic before and after the subsequent handlers are applied)
2.  the ability to short-circuit the request chain in any middleware handler (e.g. if authentication fails)

Part 2 - Recursive Chain Middleware Example
-------------------------------------------

[![](/images/posts/szabo-viktor-1154603-unsplash.jpg)](/images/posts/szabo-viktor-1154603-unsplash.jpg)

Photo by [Szabo Viktor](https://unsplash.com/photos/XDNiTGp3bKM?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)

The code for this tutorial can be found here:  
[https://github.com/benjohns1/go-middleware-example/blob/master/recursivechain/main.go](https://github.com/benjohns1/go-middleware-example/blob/master/recursivechain/main.go)  

### Step 1 - Simple Server

Just as we did in part 1, let's start with a simple working HTTP server:  

main.go:
<Gist src="https://gist.github.com/benjohns1/deb30888549c60751eb73cb9b60d5544.js"/>

Run the server:
```
go run main.go
```

Test in a browser:
```
localhost:8080/api/v1
```  
Notice the businessLogic function returns a closure around the actual http handler, so we can pass in an all-important config value "12345" when the server is started.  

### Step 2 - Recursive Chain

Rather than use a simple loop that calls handlers one after another like we did in part 1, instead we're going to pass the second handler as a parameter to the first handler, pass the third handler as a parameter to the second handler, and so on:
```
firstHandler(secondHandler(thirdHandler(fourthHandler())))
```  
Each handler will then be responsible for calling (or not!) the next one in the chain. We can do better than a bunch of eye-bleeding nested functions and use recursion:  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/3d2473a03e122eabac17665f38341f4f.js"/>

The middlewareFunc type describes the new type of middleware function we need to pass into the chain function. It accepts the next handler in the chain and returns the current handler, which wraps the next handler (this should make more sense in a bit).  
The chain function just provides the nice variadic parameter syntax and converts the final handler function into the http.Handler interface that the http router accepts.  
The recurseChain function does the actual work of sending the next handler as a parameter to the current one recursively, up until there aren't any more handlers, and it finally returns an empty function to complete the chain.  
  
To use this chain function, modify the businessLogic to:  

1.  wrap the http handler in a new closure that passes-in the next handler
2.  and call the next handler where appropriate

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/03bf8ef76a2a5acbfcde7c8a206a5076.js"/>

Now our businessLogic function accepts the same config parameter, but it returns the middlewareFunc type function that chain() accepts. This middlewareFunc accepts the next handler in the chain as a parameter and returns the actual handler function that processes the request. The actual handler function has access to the outer config and handler parameters via closures; it can call next(w, r) to continue to the next handler in the chain. In this case next(w, r) just calls the empty function returned from the last iteration of recurseChain.  

### Step 3 - Wrap and Short-Circuit

Okay, thanks a lot, now we've just made things more complicated! Wait, wait, we should [KISS](https://en.wikipedia.org/wiki/KISS_principle). We're adding complexity because it gives us the ability to actually wrap our nested handlers in functionality like this:  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/7b8ed952520dad541f1dfc52209fa50f.js"/>

and short-circuit the request chain like this:  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/7673cbf8750ea8d6d107f43f0c91132c.js"/>

The logger middleware prints an entry before _and_ after all subsequent handlers run. The shortCircuitLogic randomly decides not to call any of the subsequent handlers in the chain by returning without calling the next function.  
  
As you can see this provides a lot of flexibility with our middleware, while still keeping each function decoupled from the others.  
  
In Part 3 we'll look at a common variant of this approach that doesn't require the final handler function to call an empty handler.  

### Final Server Code

main.go:
<Gist src="https://gist.github.com/benjohns1/0f6430b1ca1bef824247fea04d00ee4d.js"/>

[Go Middleware - Part 1](/posts/20190206-go-middleware-part-1)

[Go Middleware - Part 3](/posts/20190215-go-middleware-part-3)


In this second part of the Go middleware tutorial series, we'll cover a recursive approach that provides a couple benefits beyond the simple loop chain example from part 1.

Go Middleware - Part 2


This is the first in a series of simple tutorials explaining the usage of HTTP middleware in Go.  
  
Middleware is useful for injecting logic before and after a request handler, without needing to modify the business logic of the handler itself. For instance, you can use the middleware pattern to log some basic information about every request sent to the server, then apply some standard authentication for those requests that need it, and finally apply the appropriate handler to run the actual business logic.  
  
In this context middleware is a specific case of the [decorator pattern](https://en.wikipedia.org/wiki/Decorator_pattern); it is typically used to cleanly add logic to a web request handled by a server. Middleware can be chained to wrap multiple pieces of functionality around a single request (e.g. logging, authentication, authorization, request/response encoding, error handling). Historically, the term "[middleware](https://en.wikipedia.org/wiki/Middleware)" has been used in SOA and enterprise architectures to cover any type of software that facilitates communication between two other systems (e.g. Service Bus), but is being used more frequently to refer to a logical layer _within_ a single service.  
  
This pattern helps encapsulate logic to adhere to the [Single responsibility principle](https://en.wikipedia.org/wiki/Single_responsibility_principle) for [SOLID](https://en.wikipedia.org/wiki/SOLID) design and [Clean Architecture](http://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html).

Part 1 - Loop Chain Middleware Example
--------------------------------------

[![](/images/posts/mike-alonzo-3347-unsplash.jpg)](/images/posts/mike-alonzo-3347-unsplash.jpg)

Photo by [Mike Alonzo](https://unsplash.com/@mikezo?utm_medium=referral&utm_campaign=photographer-credit&utm_content=creditBadge)

  
The code for this tutorial can be found here:  
[https://github.com/benjohns1/go-middleware-example/blob/master/loopchain/main.go](https://github.com/benjohns1/go-middleware-example/blob/master/loopchain/main.go)  
  
This simple approach uses a range loop to apply each middleware function in order. Technically, this isn't really the "middleware" pattern, but it serves the same purpose and provides a great introduction. We will build upon this simple approach with a more useful implementation in Part 2.  

### Step 1 - A Simple HTTP Server

First let's create a main func to start a simple server:  

main.go:
<Gist src="https://gist.github.com/benjohns1/f1bd0325e47a8879d54b5cb11967f29f.js"/>

We're using the standard http library to handle the "/api/v1" route with our aptly-named businessLogic function. You can run the server with:
```
go run main.go
```
and go to [localhost:8080/api/v1](http://localhost:8080/api/v1) in your browser to see this in action.  
  
One thing to note is that we're wrapping the function that handles the actual http request in a closure (the businessLogic function) so that we can inject some setup values into the handler when the server starts. The first injected value is just a static string, but the second value is a func that is run whenever a request is invoked. Try hitting the endpoint multiple times to see the pseudo-random numbers from runTimeFunc. This isn't important for this particular example, but is being shown now because closures are key to more advanced middleware implementations.  

### Step 2 - Adding Middleware

Now let's create a logging function that will log some generic information about a request:

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/b6aff6e71adefbe127452ea2143d5ef0.js"/>

How do we add this to our route handler in a way that can be reused? This is where the usefulness of middleware comes in! We can write a new function that will chain these handlers together and return a final handler that wraps all of this nicely and neatly for the route:  

main.go (partial):
<Gist src="https://gist.github.com/benjohns1/d9b238f9da534ae24a4c0d94d6c146e1.js"/>

The chain function takes any number of http.HandlerFunc functions and returns a new http.Handler that runs all of them in order. We can create and add as many middleware function handlers as we want to this chain:  
```
http.Handle("/api/v1", chain(logger, moreMiddleware, evenMoreMiddleware, businessLogic("99999", runTimeFunc)))
```
  
These handlers are completely decoupled from each other and can easily be applied to multiple routes in various configurations.  
  
[Part 2](/posts/20190209-go-middleware-part-2) will cover a slightly more advanced implementation approach using recursive functions that allow applying logic before _and_ after the subsequent handler as well as short-circuiting the request chain.  

### Final Server Code

main.go:
<Gist src="https://gist.github.com/benjohns1/9e423f4c5462cb1742af050574632e6f.js"/>

[Go Middleware - Part 2](/posts/20190209-go-middleware-part-2)


This is the first in a series of simple tutorials explaining the usage of HTTP middleware in Go.