The transport layer is typically responsible for serializing and deserializing data across a network, translating requests, responses, and errors for the business layer, and routing network requests to the business layer. This makes it easy to reuse the business layer across various network protocols, enforces separation of concerns, and improves testability of your application.

I’m being intentionally vague about what happens in the business layer, as that is highly specific to the application you are building and can have its own separate patterns or architecture. However, for transport layer abstraction to work the business layer must consistently use:

• Clearly defined request objects
• Clearly defined response objects
• Well-scoped error types

A Simple HTTP Service

source code

To illustrate the usefulness of transport layer abstraction, we will use a common example of updating a user in a database. Let’s start by implementing an extremely simplified HTTP endpoint in Go using the echo framework.

package main

import (
	"net/http"

	"github.com/labstack/echo/v4"
)

type User struct {
	ID        string `param:"id"`
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
}

func main() {
	userDB := make(map[string]*User)
	e := echo.New()
	e.PUT("/users/:id", updateUser(userDB))
	e.Logger.Fatal(e.Start(":8080"))
}

func updateUser(userDB map[string]*User) echo.HandlerFunc {
	return func(c echo.Context) error {
		var user User
		err := c.Bind(&user)
		if err != nil {
			return c.NoContent(http.StatusBadRequest)
		}
		dbUser, ok := userDB[user.ID]
		if !ok {
			return c.NoContent(http.StatusNotFound)
		}

		dbUser.FirstName = user.FirstName
		dbUser.LastName = user.LastName

		return c.JSON(http.StatusOK, dbUser)
	}
}

Now that we have built out the service let’s add some tests.

package main
...
func TestUpdateUser(t *testing.T) {

	t.Run("should update user when user exists", func(t *testing.T) {

		mockDB := map[string]*User{
			"test_user_id": &User{
				ID:        "test_user_id",
				FirstName: "Test",
				LastName:  "User",
			},
		}
		userJSON := `{"first_name":"UpdatedTest", "last_name":"UpdatedUser"}`

		e := echo.New()
		req := httptest.NewRequest(http.MethodPut, "/", strings.NewReader(userJSON))
		req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)
		rec := httptest.NewRecorder()
		c := e.NewContext(req, rec)
		c.SetPath("/users/:id")
		c.SetParamNames("id")
		c.SetParamValues("test_user_id")
		h := updateUser(mockDB)

		if assert.NoError(t, h(c)) {
			assert.Equal(t, http.StatusOK, rec.Code)
			var response User
			if !assert.NoError(t, json.Unmarshal(rec.Body.Bytes(), &response)) {
				t.FailNow()
			}
			assert.Equal(t, mockDB["test_user_id"], &response)
			assert.Equal(t, "UpdatedTest", mockDB["test_user_id"].FirstName)
			assert.Equal(t, "UpdatedUser", mockDB["test_user_id"].LastName)
		}
	})

	t.Run("should return 404 when user not found", func(t *testing.T) {

		mockDB := map[string]*User{
			"test_user_id": &User{
				ID:        "test_user_id",
				FirstName: "Test",
				LastName:  "User",
			},
		}
		userJSON := `{"first_name":"UpdatedTest", "last_name":"UpdatedUser"}`

		e := echo.New()
		req := httptest.NewRequest(http.MethodPut, "/", strings.NewReader(userJSON))
		req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)
		rec := httptest.NewRecorder()
		c := e.NewContext(req, rec)
		c.SetPath("/users/:id")
		c.SetParamNames("id")
		c.SetParamValues("bad_user_id")
		h := updateUser(mockDB)

		if assert.NoError(t, h(c)) {
			assert.Equal(t, http.StatusNotFound, rec.Code)
		}
	})

	t.Run("should return 400 when request is invalid", func(t *testing.T) {

		mockDB := map[string]*User{
			"test_user_id": &User{
				ID:        "test_user_id",
				FirstName: "Test",
				LastName:  "User",
			},
		}
		userJSON := `{"first_name":"UpdatedTest", "last_name":300}`

		e := echo.New()
		req := httptest.NewRequest(http.MethodPut, "/", strings.NewReader(userJSON))
		req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)
		rec := httptest.NewRecorder()
		c := e.NewContext(req, rec)
		c.SetPath("/users/:id")
		c.SetParamNames("id")
		c.SetParamValues("bad_user_id")
		h := updateUser(mockDB)

		if assert.NoError(t, h(c)) {
			assert.Equal(t, http.StatusBadRequest, rec.Code)
		}
	})
}

We now have a working and tested service that allows clients to update users. Unfortunately, requirements have changed and now we need to also expose a GRPC service for updating users. Now we have to:

• Re-implement the update logic in the gRPC server
• Recreate tests for the new server
• Risk having divergent behavior between the gRPC service and the HTTP service.

What if we wanted to accept updates from a queue like AWS SQS? Let’s implement another handler that listens to an SQS queue and reimplement the update logic there.

There is also something subtle about the test we already wrote. We are testing both the business logic and the transport layer logic for each test case. Notice the tags on the user struct? What if we wanted to use XML instead of JSON? We would have to update the tags on the user struct. There is also the logic around the ID being a path param instead of a apart of the request body. These are all things that only matter to the transport layer. Most projects start off simple, but it’s not uncommon for requirements or an application’s context to change.

Here’s how the architecture evolves when you decouple the transport layer from the business logic:

Abstracting the Transport Layer

source code

The current service example works, but it’s hard to change how the service runs because our business logic is tightly coupled to HTTP. If we ever need or want to change how clients interact with the service we have to duplicate both the business logic and the error handling for any new protocols, and re-test both the protocol layer and the business logic. If we instead abstract the transport layer we can minimize the changes needed to the service to support new protocols.

By decoupling the business layer from the transport layer you enable:

• A single source of truth for business logic
• Reusable and isolated components for business logic
• Protocol-specific handlers that focus only on mapping requests, responses, and errors from the business layer to the transport layer

Let’s look at how to refactor our current example.

package main
...
func main() {
	userDB := make(map[string]*users.User)
	usersService := users.Service{
		DB: userDB,
	}

	httpService := transport.NewHTTPServer(&transport.HTTPConfig{
		Port:         8080,
		UsersService: usersService,
	})

	httpService.Start()
}

Application Errors

Define shared application error types that are mapped to protocol-level errors by the transport layer.

package errors
...
var (
	ErrNotFound   = errors.New("not found")
	ErrBadRequest = errors.New("bad request")
)

Users Business Layer

package users
...
type UpdateUserRequest struct {
	ID        string
	FirstName string
	LastName  string
}

type UpdateUserResponse struct {
	ID        string
	FirstName string
	LastName  string
}

type Service struct {
	DB map[string]*User
}

func (s *Service) UpdateUser(request UpdateUserRequest) (UpdateUserResponse, error) {
	user, ok := s.DB[request.ID]
	if !ok {
		return UpdateUserResponse{}, fmt.Errorf("unable to find user in db: %w", appErr.ErrNotFound)
	}

	if request.FirstName != "" {
		user.FirstName = request.FirstName
	}

	if request.LastName != "" {
		user.LastName = request.LastName
	}

	return UpdateUserResponse{
		ID:        user.ID,
		FirstName: user.FirstName,
		LastName:  user.LastName,
	}, nil
}

This is pure business logic: no HTTP, no network serialization, no JSON binding, no error mapping.

Transport Layer

package transport
...
type HTTPServer struct {
	e    *echo.Echo
	port int
}

func NewHTTPServer(config *HTTPConfig) *HTTPServer {
	e := echo.New()
	registerHTTPRoutes(e, config.UsersService)
	return &HTTPServer{
		e:    e,
		port: config.Port,
	}
}

func (server *HTTPServer) Start() {
	server.e.Logger.Fatal(server.e.Start(fmt.Sprintf(":%d", server.port)))
}

func registerHTTPRoutes(e *echo.Echo, usersService users.Service) {
	e.PUT("/users/:id", updateUser(usersService))
}

type updateUserRequest struct {
	ID        string `param:"id"`
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
}

type updateUserResponse struct {
	ID        string `json:"id"`
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
}

func updateUser(usersService users.Service) echo.HandlerFunc {
	return func(c echo.Context) error {
		var request updateUserRequest
		err := c.Bind(&request)
		if err != nil {
			return c.NoContent(http.StatusBadRequest)
		}

		resp, err := usersService.UpdateUser(users.UpdateUserRequest{
			ID:        request.ID,
			FirstName: request.FirstName,
			LastName:  request.LastName,
		})

		if err != nil {
			return c.NoContent(MapErrorToHTTPStatus(err))
		}
		return c.JSON(http.StatusOK, updateUserResponse{
			ID:        resp.ID,
			FirstName: resp.FirstName,
			LastName:  resp.LastName,
		})
	}
}

func MapErrorToHTTPStatus(err error) int {
	switch {
	case errors.Is(err, appErr.ErrNotFound):
		return http.StatusNotFound
	case errors.Is(err, appErr.ErrBadRequest):
		return http.StatusNotFound
	}
	return http.StatusInternalServerError
}

This layer handles routing, JSON decoding, and error mapping. The business logic doesn’t know or care that it’s being called from HTTP.

If you wanted to expose this over gRPC, you’d just implement another transport layer using the same users.Service interface.

Each transport acts like a plug-in, wiring into the same business logic core.

Adding support for SQS

The same principles apply if you’re receiving data from a message queue like Amazon SQS. Here’s an example that uses a dedicated request object and reuses the exact same business logic. This separation allows each transport to decode, validate, and forward requests independently, keeping business logic untouched.

package transport
...
type updateUserSQSRequest struct {
	ID        string `json:"id"`
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
}

type SQSServer struct {
...
}

func (s *SQSServer) Start(ctx context.Context) {
	for {
		output, err := s.Client.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
			QueueUrl:            &s.QueueURL,
			MaxNumberOfMessages: 1,
			WaitTimeSeconds:     10,
		})

		for _, msg := range output.Messages {
			var req updateUserSQSRequest
			if err := json.Unmarshal([]byte(*msg.Body), &req); err != nil {
				log.Printf("failed to unmarshal SQS message: %v", err)
				continue
			}

			resp, err := s.UsersService.UpdateUser(users.UpdateUserRequest{
				ID:        req.ID,
				FirstName: req.FirstName,
				LastName:  req.LastName,
			})
			if err != nil {
				log.Printf("unable to update user: %v", err)
				continue
			}

			log.Printf("updated user from SQS: %+v", resp)
			_, err = s.Client.DeleteMessage(ctx, &sqs.DeleteMessageInput{
				QueueUrl:      &s.QueueURL,
				ReceiptHandle: msg.ReceiptHandle,
			})
		}

		time.Sleep(s.PollInterval)
	}
}

Why This Matters

Yes, this adds boilerplate and might seem like overengineering for simple services, but this abstraction makes the service significantly easier to change and test.

• Want to validate first names? Just update the service logic.
• Want to expose gRPC? Add a gRPC handler that uses the same service.
• Want to restrict HTTP to only update first names? Change only the HTTP handler.

You no longer have to rewrite logic, and you’re removing the coupling between the network and your application.

Final Thoughts

Most services start off small and focused, but business requirements change frequently. Abstracting away the transport layer from business logic helps keep your services maintainable, testable, and extensible. You don’t have to account for every requirement up front, but you make it significantly easier to accommodate changes later. This also gives structure to your applications and makes you intentional about how you build out services.

Overview

I learn most efficiently when giving and receiving reviews and it seems to stick better than just reading or hearing advice passively. I see them as a way for me to help better others, help better myself, and help better the software that I build.

I have also learned that code reviews are should not be primarily used to catch bugs, that’s just a side effect. Code reviews are effective as a learning and teaching tool. They help elevate the ability of the people you build software with. The constant feedback cycle of doing and receiving code reviews is a useful tool for increasing software quality and readability. When doing code reviews you know someone else needs to understand your code and this helps emphasize clear and expressive code.

Receiving Reviews

Review your code first

Before asking someone else to do a code review, review it yourself. I usually do this in the actual CR tool. This is an easy way to catch small things that you miss when heads down coding.

Assign someone specific

If there isn’t a specific owner then often times code reviews get delayed. It’s not that others shouldn’t look at it, but you want someone to be responsible for it. This prevents the bystander effect.

Be kind to your reviewer

Give as much context as possible

Usually team members are familiar enough with your work that they have context already, but you can’t make that assumption. The intent of the change should be clear. This is easily done by making sure the description in the CR is accurate and updated. If there are diagrams or design docs related to the change, link them in the CR. Make sure the description in the issue tracker is up to date and link that in the CR.

Try to keep reviews small

This is one of the hardest things for me, but try to break changes into digestible pieces. If I see a review that is thousands of lines long and touches tens of files I dread it. I try to be conscious of that feeling when asking others to review my code. If a change does become large, break it up into smaller components and review each of those individually.

Doing Reviews

Be Quick

Often times when someone asks you for a code review they become blocked on you completing the review to finish work. There is usually a tree of dependencies waiting for each review and getting them done quickly helps the entire team.

I recommend setting aside time for code reviews in 2 ways:

1. Check for assigned code reviews before standup.
2. Check for assigned code reviews after submitting one myself.

When I do see a code review that I am responsible for I ensure that I look at it before I start any new tasks with one exception: large reviews. If a code review is large and will take longer than 15 - 20 minutes then block out time to look at it later that day.

With this approach I usually have a 24hr or less turn around for code reviews. This also give me something productive to do between waiting for my own reviews or starting a new task.

Gain Context

When reviewing code you are likely to have some context around the change already. If you do not have context already be sure you understand what the change does and why. The goal here is to ensure that you know what you are reviewing and the scope of the change.

If you were involved in the design or conception of a particular feature this step is fast. I start by looking at the ticket or merge request description to get the big picture. Next I will look at the commit messages. These are often smaller than a change description, but helps to understand the scope of a change. If I still don’t have enough context then I reach out to the requester and ask for clarification.

Automate the boring things

A huge time sink in code reviews is feedback that should be caught with a linter or formatter. It’s common to see comments like “This variable should be final”. This is low hanging fruit and should be caught before a code review starts. Teams should standardize on a style guide and use common linters to analyze code before it is reviewed. If there is something in a code review that seems like it should be caught with a linter then you should update the linter. This prevents noise in a code review that can cost time and increase cognitive load.

Start with the tests

Once I understand the scope and intent of a change I start by looking at the tests. This usually gives me examples of typical call patterns and implementation expectations. I can also usually tease out assumptions and identify system boundaries based on mocked classes.

Watch the boundaries

When looking at a CR I ask myself two questions:

1. Are we changing data coming into the system?
2. Are we changing data going out of the system?

If the answer to any of these are yes I tend to look at things on these boundaries more intently. A short list of things I think about at the boundaries of a system include:

1. Backwards compatibility
2. API design
3. Dependency coupling.

There is a lot of opportunity at boundaries to introduce errors and changes at boundaries can have a large blast radius.

Darin’s Law: Cover your A.S.S.

When dealing with large scale systems there is a lot that can go wrong. At Amazon I worked with a principal engineer who distilled this down to 3 topics: Availability, Security, and Support. While doing code reviews I always keep those things in mind.

To ensure you are covering your A.S.S it use useful to ask your self:

1. Can this change cause failure in your service or a dependency?
2. Is this change doing anything that can impact customer data?
3. Will I be able to diagnose issues with this change later?
4. Will I be able to easily update this code path later?

Summary

Code review is a useful tool for helping improve both software quality and technical acumen. The code review process is fun and has been a key component of my growth as an engineer. When requesting code reviews remember to be kind to your reviewer, you want to make the process of getting feedback as painless as possible. While reviewing code pay attention to your boundaries, and don’t forget: Cover your A.S.S. in code reviews.