+
The term DDD comes from the book by Eric Evans: “Domain-Driven Design: Tackling +Complexity in the Heart of Software”. +In his book he describes a set of practices that aim to help us build +maintainable, rich, software systems that solve customer’s problems. The book is +560 pages of dense insight, so you’ll pardon me if my summary elides some +details, but in brief he suggests:
+-
+
- Listen very carefully to your domain experts - the people whose job you’re + automating or assisting in software. +
- Learn the jargon that they use, and help them to come up with new jargon, so + that every concept in their mental model is named by a single precise term. +
- Use those terms to model your software; the nouns and verbs of the domain + expert are the classes and methods you should use in modelling. +
- Whenever there is a discrepancy between your shared understanding of the + domain, go and talk to the domain experts again, and then refactor + aggressively. +
This sounds great in theory, but in practice we often find that our business +logic escapes from our model objects; we end up with logic bleeding into +controllers, or into fat “manager” classes. We find that refactoring becomes +difficult: we can’t split a large and important class, because that would +seriously impact the database schema; or we can’t rewrite the internals of an +algorithm because it has become tightly coupled to code that exists for a +different use-case. The good news is that these problems can be avoided, since +they are caused by a lack of organisation in the codebase. In fact, the tools to +solve these problems take up half of the DDD book, but it can be be difficult to +understand how to use them together in the context of a complete system.
+I want to use this series to introduce an architectural style called +Ports and Adapters, +and a design pattern named +Command Handler. +I’ll be explaining the patterns in Python because that’s the language that I use +day-to-day, but the concepts are applicable to any OO language, and can be +massaged to work perfectly in a functional context. There might be a lot more +layering and abstraction than you’re used to, especially if you’re coming from a +Django background or similar, but please bear with me. In exchange for a more +complex system at the outset, we can avoid much of our accidental complexity later.
+The system we’re going to build is an issue management system, for use by a +helpdesk. We’re going to be replacing an existing system, which consists of an +HTML form that sends an email. The emails go into a mailbox, and helpdesk staff +go through the mails triaging problems and picking up problems that they can +solve. Sometimes issues get overlooked for a long time, and the helpdesk team +have invented a complex system of post-it notes and whiteboard layouts to track +work in progress. For a while this system has worked pretty well but, as the +system gets busier, the cracks are beginning to show.
+Our first conversation with the domain expert +“What’s the first step in the process?” you ask, “How do tickets end up in the +mail box?”.
+“Well, the first thing that happens is the user goes to the web page, and they +fill out some details, and report an issue. That sends an email into the issue +log and then we pick issues from the log each morning”.
+“So when a user reports an issue, what’s the minimal set of data that you need +from them?”
+“We need to know who they are, so their name, and email I guess. Uh… and the +problem description. They’re supposed to add a category, but they never do, and +we used to have a priority, but everyone set their issue to EXTREMELY URGENT, so +it was useless.
+“But a category and priority would help you to triage things?”
+“Yes, that would be really helpful if we could get users to set them properly.”
+This gives us our first use case: As a user, I want to be able to report a new +issue.
+Okay, before we get to the code, let’s talk about architecture. The architecture +of a software system is the overall structure - the choice of language, +technology, and design patterns that organise the code and satisfy our +constraints [https://en.wikipedia.org/wiki/Non-functional_requirement]. For our +architecture, we’re going to try and stick with three principles:
+-
+
- We will always define where our use-cases begin and end. We won’t have + business processes that are strewn all over the codebase. +
- We will depend on abstractions + [https://en.wikipedia.org/wiki/Dependency_inversion_principle], and not on + concrete implementations. +
- We will treat glue code as distinct from business logic, and put it in an + appropriate place. +
Firstly we start with the domain model. The domain model encapsulates our shared +understanding of the problem, and uses the terms we agreed with the domain +experts. In keeping with principle #2 we will define abstractions for any +infrastructural or technical concerns and use those in our model. For example, +if we need to send an email, or save an entity to a database, we will do so +through an abstraction that captures our intent. In this series we’ll create a +separate python package for our domain model so that we can be sure it has no +dependencies on the other layers of the system. Maintaining this rule strictly +will make it easier to test and refactor our system, since our domain models +aren’t tangled up with messy details of databases and http calls.
+Around the outside of our domain model we place services. These are stateless +objects that do stuff to the domain. In particular, for this system, our command +handlers are part of the service layer.
+Finally, we have our adapter layer. This layer contains code that drives the +service layer, or provides services to the domain model. For example, our domain +model may have an abstraction for talking to the database, but the adapter layer +provides a concrete implementation. Other adapters might include a Flask API, or +our set of unit tests, or a celery event queue. All of these adapters connect +our application to the outside world.
+In keeping with our first principle, we’re going to define a boundary for this +use case and create our first Command Handler. A command handler is an object +that orchestrates a business process. It does the boring work of fetching the +right objects, and invoking the right methods on them. It’s similar to the +concept of a Controller in an MVC architecture.
+First, we create a Command object.
+class ReportIssueCommand(NamedTuple):
+ reporter_name: str
+ reporter_email: str
+ problem_description: str
+A command object is a small object that represents a state-changing action that +can happen in the system. Commands have no behaviour, they’re pure data +structures. There’s no reason why you have to represent them with classes, since +all they need is a name and a bag of data, but a NamedTuple is a nice compromise +between simplicity and convenience. Commands are instructions from an external +agent (a user, a cron job, another service etc.) and have names in the +imperative tense, for example:
+-
+
- ReportIssue +
- PrepareUploadUri +
- CancelOutstandingOrders +
- RemoveItemFromCart +
- OpenLoginSession +
- PlaceCustomerOrder +
- BeginPaymentProcess +
We should try to avoid the verbs Create, Update, or Delete (and their synonyms) +because those are technical implementations. When we listen to our domain +experts, we often find that there is a better word for the operation we’re +trying to model. If all of your commands are named “CreateIssue”, “UpdateCart”, +“DeleteOrders”, then you’re probably not paying enough attention to the language +that your stakeholders are using.
+The command objects belong to the domain, and they express the API of your +domain. If every state-changing action is performed via a command handler, then +the list of Commands is the complete list of supported operations in your domain +model. This has two major benefits:
+-
+
- If the only way to change state in the system is through a command, then the + list of commands tells me all the things I need to test. There are no other + code paths that can modify data. +
- Because our commands are lightweight, logic-free objects, we can create them + from an HTTP post, or a celery task, or a command line csv reader, or a unit + test. They form a simple and stable API for our system that does not depend + on any implementation details and can be invoked in multiple ways. +
In order to process our new command, we’ll need to create a command handler.
+class ReportIssueCommandHandler:
+ def __init__(self, issue_log):
+ self.issue_log = issue_log
+
+ def __call__(self, cmd):
+ reported_by = IssueReporter(
+ cmd.reporter_name,
+ cmd.reporter_email)
+ issue = Issue(reported_by, cmd.problem_description)
+ self.issue_log.add(issue)
+Command handlers are stateless objects that orchestrate the behaviour of a +system. They are a kind of glue code, and manage the boring work of fetching and +saving objects, and then notifying other parts of the system. In keeping with +principle #3, we keep this in a separate layer. To satisfy principle #1, each +use case is a separate command handler and has a clearly defined beginning and +end. Every command is handled by exactly one command handler.
+In general all command handlers will have the same structure:
+-
+
- Fetch the current state from our persistent storage. +
- Update the current state. +
- Persist the new state. +
- Notify any external systems that our state has changed. +
We will usually avoid if statements, loops, and other such wizardry in our +handlers, and stick to a single possible line of execution. Command handlers are + boring glue code. +Since our command handlers are just glue code, we won’t put any business logic +into them - they shouldn’t be making any business decisions. For example, let’s +skip ahead a little to a new command handler:
+class MarkIssueAsResolvedHandler:
+ def __init__(self, issue_log):
+ self.issue_log = issue_log
+
+ def __call__(self, cmd):
+ issue = self.issue_log.get(cmd.issue_id)
+ # the following line encodes a business rule
+ if (issue.state != IssueStatus.Resolved):
+ issue.mark_as_resolved(cmd.resolution)
+This handler violates our glue-code principle because it encodes a business +rule: “If an issue is already resolved, then it can’t be resolved a second +time”. This rule belongs in our domain model, probably in the mark_as_resolved +method of our Issue object. +I tend to use classes for my command handlers, and to invoke them with the call +magic method, but a function is perfectly valid as a handler, too. The major +reason to prefer a class is that it can make dependency management a little +easier, but the two approaches are completely equivalent. For example, we could +rewrite our ReportIssueHandler like this:
+def ReportIssue(issue_log, cmd):
+ reported_by = IssueReporter(
+ cmd.reporter_name,
+ cmd.reporter_email)
+ issue = Issue(reported_by, cmd.problem_description)
+ issue_log.add(issue)
+If magic methods make you feel queasy, you can define a handler to be a class +that exposes a handle method like this:
+class ReportIssueHandler:
+ def handle(self, cmd):
+ ...
+However you structure them, the important ideas of commands and handlers are:
+-
+
- Commands are logic-free data structures with a name and a bunch of values. +
- They form a stable, simple API that describes what our system can do, and + doesn’t depend on any implementation details. +
- Each command can be handled by exactly one handler. +
- Each command instructs the system to run through one use case. +
- A handler will usually do the following steps: get state, change state, + persist state, notify other parties that state was changed. +
Let’s take a look at the complete system, I’m concatenating all the files into a +single code listing for each of grokking, but in the git repository +[https://github.com/bobthemighty/blog-code-samples/tree/master/ports-and-adapters/01] + I’m splitting the layers of the system into separate packages. In the real +world, I would probably use a single python package for the whole app, but in +other languages - Java, C#, C++ - I would usually have a single binary for each +layer. Splitting the packages up this way makes it easier to understand how the +dependencies work.
+from typing import NamedTuple
+from expects import expect, have_len, equal
+
+# Domain model
+
+class IssueReporter:
+ def __init__(self, name, email):
+ self.name = name
+ self.email = email
+
+
+class Issue:
+ def __init__(self, reporter, description):
+ self.description = description
+ self.reporter = reporter
+
+
+class IssueLog:
+ def add(self, issue):
+ pass
+
+
+class ReportIssueCommand(NamedTuple):
+ reporter_name: str
+ reporter_email: str
+ problem_description: str
+
+
+# Service Layer
+
+class ReportIssueHandler:
+
+ def __init__(self, issue_log):
+ self.issue_log = issue_log
+
+ def __call__(self, cmd):
+ reported_by = IssueReporter(
+ cmd.reporter_name,
+ cmd.reporter_email)
+ issue = Issue(reported_by, cmd.problem_description)
+ self.issue_log.add(issue)
+
+
+# Adapters
+
+class FakeIssueLog(IssueLog):
+
+ def __init__(self):
+ self.issues = []
+
+ def add(self, issue):
+ self.issues.append(issue)
+
+ def get(self, id):
+ return self.issues[id]
+
+ def __len__(self):
+ return len(self.issues)
+
+ def __getitem__(self, idx):
+ return self.issues[idx]
+
+
+email = "bob@example.org"
+name = "bob"
+desc = "My mouse won't move"
+
+
+class When_reporting_an_issue:
+
+ def given_an_empty_issue_log(self):
+ self.issues = FakeIssueLog()
+
+ def because_we_report_a_new_issue(self):
+ handler = ReportIssueHandler(self.issues)
+ cmd = ReportIssueCommand(name, email, desc)
+
+ handler(cmd)
+
+ def the_handler_should_have_created_a_new_issue(self):
+ expect(self.issues).to(have_len(1))
+
+ def it_should_have_recorded_the_issuer(self):
+ expect(self.issues[0].reporter.name).to(equal(name))
+ expect(self.issues[0].reporter.email).to(equal(email))
+
+ def it_should_have_recorded_the_description(self):
+ expect(self.issues[0].description).to(equal(desc))
+There’s not a lot of functionality here, and our issue log has a couple of +problems, firstly there’s no way to see the issues in the log yet, and secondly +we’ll lose all of our data every time we restart the process. We’ll fix the +second of those in the next part +[https://io.made.com/blog/repository-and-unit-of-work-pattern-in-python/].
+
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+