DEV Community: Sam Hall

Backend Software Architecture Demystified ✨

Sam Hall — Wed, 13 Jul 2022 21:16:48 +0000

Introduction

Have you heard of any of these software architectures? : Ports and adapters, clean architecture, layered application, onion architecture, hexagonal, N-tiered, so on and so forth. Have you ever stared at one of these diagrams and thought “Yeah that sense, but how do I do it code?” I have as well, and I think it is a sentiment (at least in my experience) that many people share.

That’s why today we are demystifying software architecture (the backend part at least) down to a few basic principles and techniques. My goal is by the end of this article you’ll hopefully see that all of these architectures are essentially the same, and to paraphrase Bruce Lee “The only style is no style”.

Dedicated business logic layer

The foundational building block in all of these architectures is a dedicated business logic layer. So let us start there.

What is business logic? It’s is the brains behind your application that fulfills use cases. What is a use case? Well its the thing you are trying to do. For example if we have a social media application, we might want to have the ability to “like” a post. So somewhere in our code we could have a function called likePost or something like that.

Riffing on this likePost example, what are some requirements for this? We probably need to store some object (lets call it PostLike ) and link it back to the Post object. This would allow us to denote that the post has in fact been liked. PostLike should probably also include who liked the post. Maybe we’d like to know when the Post was liked. What happens if the Post doesn’t exist? Should we verify that before creating this PostLike object? Do other parts of the application need to be notified that someone liked a post?

Some of these are explicitly required while some are implicitly required so that we save our ass so things don’t go sideways. In either case we can write tests for these things and ensure that our use cases behave in the manor we expect. These are the business rules.

Notice that thus far I haven’t mentioned SQL, DynamoDb, RabbitMQ, REST, GraphQL, or any other technology for that matter. At this level we simply do not care. We are most concerned with “what” the behavior of the use case is, not “how” its going to happen. The business logic layer helps us drive behaviors and technology solutions do not fit within that category.

Still, we are going to need to figure that part out if we are going to do anything useful with the business rules. This is a perfect segue into the next principle/technique.

Dependency inversion

If you are familiar with SOLID design principles, this is “D” part in the acronym and its states that

High level modules should not depend on low level modules;
both should depend on abstractions. Abstractions should not depend on
details. Details should depend upon abstractions.

While it is the official and accurate definition, in my opinion the language is much too complicated. It sounds scary. So what does dependency inversion actually mean?

All it means is that instead of calling another function or method directly, you pass it in as an argument instead. So if you are working with classes in an object oriented language you would typically pass in some dependency through the constructor. If you are working with a language that supports first class functions, you would pass in a function as an argument to create a higher order function.

Recall in the previous section that the business rules are looking to answer “what” not “how”, so one caveat is that these function signatures that we are passing in need to be agnostic of the underlying implementation. For example lets say we need to persist our PostLike to some data store. We might do this with a function called save that takes in a PostLike object and returns the same object once it have been successfully persisted. Underneath the hood it could be writing to a Postgres database or maybe even the file system.

The benefit of passing in these dependencies is that it effectively decouples the business rules from any specific technology(aka loose coupling). Said differently this is the glue that holds everything together with the business rules. And its what allows us to tune the “what” and the “how” separately. We can change one without effecting the other.

Show me the code

Okay now that we’ve gotten the high-level stuff out of the way, lets dive into an example so we can see what this looks like in practice. We’ll layout the code for our likePost use case and discuss on the other side.

interface PostLike {
  accountId: string;
  postId: string;
  timestamp: number;
}

type DoesPostExist = (postId: string) => Promise<boolean>;
type Save<T> = (entity: T) => Promise<T>;
type PublishEvent<T> = (event: T) => Promise<void>;

const likePost = async ({
  accountId,
  postId,
  doesPostExist,
  save,
  publishPostLikedEvent,
}: {
  accountId: string;
  postId: string;
  doesPostExist: DoesPostExist;
  save: Save<PostLike>;
  publishPostLikedEvent: PublishEvent<PostLike>;
}): Promise<{ result: PostLike }> => {
  const postExists = await doesPostExist(postId);
  if (!postExists) {
    throw new Error('cannot like post that does not exist...');
  }

  const result = await save({ accountId, postId, timestamp: Date.now() });

  await publishPostLikedEvent(result);

  return { result };
};

Okay so here we are! We have our likePost function that takes in an accountId and a postId so that we can say that the account liked the post. In addition we have a couple of functions that we have passed in to help us flush out our use case. The doesPostExist function (presumably supplied by the domain that handles Posts) will let us know if the supplied postId is valid or not. We have a save function that will handle the persistence of the PostLike and finally a publishPostLikedEvent function that will notify stuff downstream that this has happened.

We defined types for these functions but we did not define implementations. With our implementations of these functions (shown off camera) we are free to choose whatever technologies we’d like. For example we could write an implementation for publishPostLikedEvent that uses SQS , SNS , or RabbitMQ.

A good rule of thumb is if a function returns a Promise just pass it in. Your unit tests will also thank you.

Diagram it

Despite what shape its presented in (hexagon, concentric circles, or boxes), the concept is the same. On the outside we have technology concerns and in the middle we have the actual business rules. For simplicity’s sake, lets look at a layered application diagram (the boxes) that fits with likePost example above.

Everything above the business rules is usually some sort of facade or way to access the business rules. For example we could write a REST api, GraphQL , or even a CLI . Sometimes you’ll see this referred to as the I/O layer.

Below the business rules are other potential layers driven by the business rules. We may need persistence, we may need to talk to another micro-service, third-party api, or what have you, and we may also need to publish an event to let other parts of the system know whats going on.

These are fluid and can change on a case-by-case basis.

Recap

The foundational pieces of software architectures are the behaviors that make up use cases.
We can isolate these behaviors in a dedicated business logic layer.
Dependency inversion is used to glue everything(layers) together.
Using these techniques together separates “what” from “how” and allows the system to evolve naturally.
Most popular software architectures work to achieve this although there are nuances between them.

Because of styles people are separated. Research your own experience, absorb what is useful, reject what is useless, add what is essentially your own. -- Bruce Lee

Thanks for reading!

There and back again: Refactoring OO to FP

Sam Hall — Mon, 13 Jun 2022 20:57:55 +0000

Functional programming(FP) seems to be completely in vogue these days. While I do think FP has many benefits, I often have a hard time with what sometimes seems to me a dogmatic comparison that FP is superior than object oriented (OO) programming.

Contrary to popular belief, I think that OO and FP are closer together than they might appear. At least this seems to be particularly true if the OO code is written with SOLID design principles in mind.

In this article we are going to exploring a refactoring from SOLID object oriented(OO) code to a more functional programming (FP) style using Typescript. In addition to the “how-to” aspect, we’ll look at each refactoring from a testability perspective. I find it is a good gauge of code quality. If its easy to test, there is a high probability that there is not a bunch of funky state or hidden dependencies.

Without further ado…. lets refactor!

For this example we will use a very very simplified bank account example. We’ll have an Account domain object and our use case is opening a new account.

interface Account {
  id: string;
  name: string;
  accountStatus: 'OPEN' | 'CLOSED';
}

interface AccountDao {
  save: (account: Account) => Promise<Account>;
}

class AccountService {
  constructor(readonly accountDao: AccountDao) {}

  public async openAccount({
    id = uuid(),
    name,
  }: {
    id?: string;
    name: string;
  }) {
    const account: Account = { id, name, accountStatus: 'OPEN' };

    return this.accountDao.save(account);
  }
}

As you can see in this example, this is pretty typical SOLID code. We have some stateless service class that contains the business rules for our use case, and we hold a dependency on our data layer to be able to persist our account information. This is easily testable since we can inject a fake implementation using an in-memory database or mock.

In our first refactoring to FP, we need to actually make this a function. And as they say, “a closure is a poor man’s object”. So lets turn this into a functional closure.

export const accountService = (accountDao: AccountDao) => {
  const openAccount = ({
    id = uuid(),
    name,
  }: {
    id?: string;
    name: string;
  }) => {
    const account: Account = {
      id,
      name,
      accountStatus: 'OPEN',
    };

    return accountDao.save(account);
  };

  return { openAccount };
};

Are we functional yet? Not quite. We could still potentially keep private state in this iteration, so lets remove the closure and bring in a higher-order function.

export const openAccount = ({
  id = uuid(),
  name,
  saveAccount,
}: {
  id?: string;
  name: string;
  saveAccount: AccountDao['save'];
}) => {
  const account: Account = {
    id,
    name,
    accountStatus: 'OPEN',
  };

  return saveAccount(account);
};

Hey this is pretty cool, we are passing in the dependency directly to the function, we factored out ability to keep state in the closure and its testable all the same. Its feels like an interface with one method and a built in constructor. I digg it.

Still, there is work to do. Can we factor out the dependency all together? First we can take the creating of the account object and extract it to its own function.

export const createAccount = ({
  id = uuid(),
  name,
}: {
  id?: string;
  name: string;
}): Account => ({
  id,
  name,
  accountStatus: 'OPEN',
});

Notice that the createAccount function is now pure. And instead of depending on the interface, we can just write our saveAccount function implementation directly.

export const saveAccount = async (
  account: Account
): Promise<Account> => {
  await fs.promises.writeFile(
    '/accounts-store/accounts.txt',
    JSON.stringify(account)
  );

  return account;
};

Lastly we can compose the two to satisfy our use case.

export const openAccount = ({
  id = uuid(),
  name,
}: {
  id?: string;
  name: string;
}): Promise<Account> => saveAccount(createAccount({ id, name }));

But wait, how is this testable!? We are unable to inject our fake dao into the function. The answer here is that we do not unit test the composition. Instead we unit test the pure parts which is very straight forward. In order to test the entire composition, we would need an integration test (a true testament to the name).

In the end, maybe the goal is not the decision of OO or FP, but more so of stateless programming with clear responsibilities and limited coupling.

Like most things in life, its not all black and white. Notice that all these refactorings were viable from the start. Each is stateless, testable, and has clear responsibilities! The main difference here is dependency management by using dependency inversion or dependency rejection.

I think I'd like to conclude that maybe the balance lies somewhere in the middle. Personally, I have a preference towards the higher order function refactoring. It seems to have the best of both worlds in that it:

Avoids the spaghetti that can come along with classes and closures
Doesn’t make things so fine grained that its hard to keep track of (functional composition)

Maybe we can invent a new paradigm called FOOP? Thanks for reading!

TDD Part 2: What is a Unit Test?

Sam Hall — Fri, 22 Jan 2021 16:16:30 +0000

Introduction

In part 1 of the series, I shared my personal experience with TDD and how my practice with it has evolved.

Before we dive too deep into it let's first answer what is a test, how to set up a test, and what defines some good characteristics of a unit test.

What is a Unit Test? 🤔

What is a unit test? For this, I like Elliotte Rusty Harrold's definition:

"A Unit Test is a piece of code that verifies that a known, fixed input produces a known fixed output."

Okay now that we got that out of the way, what the hell do we do now!? I think this is probably best explained by the commonly known acronym AAA - no not the people you call when your car breaks down on the side of the road, what we are talking about here is Arrange Act Assert aka Given When Then.

First, we need to arrange our known input. Then we feed that input into our method under test. Finally, we verify that the code did what we expected. Here are a couple of example tests of a calculator that takes an input of comma-separated strings.

it('return 0 if the input is empty', () => {
  const emptyInput = ''; // arrange

  const result = calculator.add(emptyInput); // act

  assert.equal(result, 0) //assert
});

This is simple enough that we can do this in one-line but under more complex circumstances (or if you are new to this) it is very helpful to break it out in this manner.

it('return input if there is only one number', () => {
  assert.equal(calculator.add('2'), 2)
});

it('return sum of two numbers', () => {
  assert.equal(calculator.add('1,2'), 3)
});

FIRST Principles 🥇

Although this is a very simple example, let's take a second to make a few observations about these tests.

They are fast, there are no external dependencies. I'm not reading from the file system or database (we will cover this soon). This is good because I want to keep my feedback loop as tight as possible and I can keep running the tests between every change.
They are isolated. I am only testing one thing in each test. If one of those breaks, I know exactly what broke and where to look.
They are repeatable. It doesn't matter which order I run these in, what environment, they will always produce the same result.
They are self-validating. I do not have to check manually if one of these failed. I will know on the run if something broke.
They are thorough (at least somewhat here). Ideally you want to test your edge cases, error cases, and happy path. You need to know how you are going to handle everything.

These are known as the FIRST principles of unit testing. Sometimes I feel that these are almost self-evident once you start writing tests, but I think it bears repeating and bolsters the definition of a unit test.

Wrapping Up

Alright, that's lightweight stuff, what about functions and methods that don't return anything? What about if I need to talk to a database? You still haven't shown how to actually do test-driven development.

Whoah.... cool the jets we will get there I promise.

In the next article, we will start actually doing some TDD with an awesome way to learn and practice TDD - Code Katas.

Thank you for reading and stay tuned! 🙏

TDD Part 1: Why Should I?

Sam Hall — Fri, 18 Dec 2020 16:24:00 +0000

Introduction

In the first part of this series I want to share my personal experience with test-driven development(TDD), how I got there, and how it makes the development process much simpler with an end result of higher quality code.

Bad Tests 👎

I once worked on a project using a micro-services architecture that had a contractual obligation for 80% code coverage. Before this most of us had not written unit tests, let alone practiced TDD.

In the beginning, I developed the way I normally did at the time, that is slam out a bunch of code, run the application, wonder why it wasn't working, run the debugger, fix the bug, rinse and repeat(also known as bug driven development).

I would write the unit tests after I finished the code. Sometimes I would even create another task to do this work under after I had already committed the production code(no bueno). It was deeply frustrating and oftentimes took longer to write the tests than it did the feature (the tests were also garbage).

Starting to Write Better Tests 🌱

As the system grew and more services were added, it became increasingly more difficult to develop this way. Running the entire system in a local environment was not always feasible and the feedback loop was far too long to do anything efficiently.

As my frustration grew I started looking at how to write better unit tests and how to write testable code. I read Clean Code which is closely related but not quite directed at TDD, discovered the SOLID design principles, and absorbed as much as I could from the internet.

So I started writing a little bit of code and then I would write the unit tests at the same time. This kept my code clean, and I could develop entire features without ever firing up the application. The tests were all of the feedback I needed and then I could verify that the system was running as expected less frequently. The issues that did occur where usually plumbing related or not understanding the problem correctly.

Going full TDD 💡

I then came across this talk by Elliotte Rusty Harold, and one of the audience members basically described how I developed and asked why he should write his tests first. Rusty's response was to the effect of 'so you are writing a little code, writing a little test, writing a little code, etc... I'm just asking that you cut out the first step and write a little test, write a little code.'

A light bulb went off and that's what I started doing. Before I wrote any code, I wrote a test first. Suddenly writing complex features became not only easy but fun! I knew what the system had to do, so I would write down a list of tests, and one by one I would write the test, then write the code that made it pass. This let me build up the feature in tiny baby steps and I got immediate feedback, kept the code simple and clean, and gave me confidence in the code that I had not experienced in any other way.

Conclusion 🔚

There are many other benefits to TDD documented elsewhere, but I wanted to explain my evolution of how I got there and how it affected me practically.

I would say that writing the tests as you write the code gives you about 80% of the benefits but going full TDD will take all unneeded complexity out of the design and leaves you with higher quality than you might have had otherwise.

The bottom line is, is that it makes coding easier and with the added bonus that your code will be by default high quality.

Throughout the rest of this series, I'll be going over the basic anatomy of tests, test doubles (mocks), how to write tests for legacy code, and how to practice TDD.

I hope you'll join me!

P.S. If you are wondering why there is a surgeon washing his hands as the cover image. Robert C. Martin(aka Uncle Bob) describes the technical discipline of TDD as akin to the ritual of a surgeon meticulously washing his/her hands or double-entry bookkeeping in accounting. Sometimes seemingly arbitrary but highly effective.