Migrate to Onion Architecture

To give us a better set of guardrails for application architecture, we can
migrate to Onion Architecture[0].

We can utilise jMolecules to provide a means to describe this more clearly, as
well as using the jMolecules ArchUnit rules to enforce the layout of the
project.

To migrate to the architecture, we must:

- move anything related to underlying domain model into a `@DomainModelRing`
  annotated package
- move anything related to the underlying domain model's business logic into
  the `@DomainServiceRing` annotated package
- move anything else application related into the `@ApplicationServiceRing`
- move our `Application` class into the `@ApplicationServiceRing`, but leave it
  as a top level class to retain Spring Boot's autoconfiguration and to avoid
  us requiring integration tests to use `@ContextConfiguration` to autoconfigure,
  or to specify the `scanBasePackages`. Note that this does however tie the
  infrastructure ring to Spring Boot.
- move the models generated by JSON Schema definitions, used for the HTTP
  layer, into our Infrastructure ring, as it's purely Infrastructure related
- don't enforce the Arch Unit test `requireFinalFields` on our generated HTTP
  layer models, as they're needed to be mutable for Jackson to (de)serialise
- provide the `ApiStorage` as a Domain interface, which will have an implementation
  that provides the underlying storage mechanism. We will later introduce a
  `Provider` that the `ApiService` can interact with, rather than this.
- provide the `ApiService` as an Application interface, as there is no business
  logic in it

We can also add additional ArchUnit rules to enforce the separation between
ring:

- ensure Spring isn't used in the domain ring, as it's entirely separate
  business logic from the current DI/HTTP/REST/etc framework in use
- ensure only `WebMvcTest`/`MockMvc` is used in the Infrastructure ring,
  against our HTTP endpoints
- ensure our `SpringBootApplication` is only created in the `Application` ring

[0]: https://herbertograca.com/2017/09/21/onion-architecture/

Co-authored-by: Bethan Palmer <[email protected]>

Author: jamietanna

adr/0006-onion-architecture.md

@@ -0,0 +1,34 @@
+---
+creation_date: 2022-01-28
+decision_date: 2022-02-08
+status: accepted
+---
+# Use of Onion Architecture in Spring Boot
+
+## Context
+
+As a means to better structure the project, enforcing consistency of our underlying data structures and project's implementation, we want to enforce a common code architecture.
+
+[jMolecules](https://github.com/xmolecules/jmolecules) is a Java library that can do this for us, both with rules, and a common language for describing the architecture, and currently supports:
+
+- Layered Architecture
+- Onion Architecture
+- Domain Driven Design (DDD)
+
+Using this, and [ArchUnit](https://www.archunit.org/) rules, we can enforce the right architecture style of our application.
+
+## Decision
+
+We have decided to migrate to Onion Architecture, as the most straightforward of the options to get started with.
+
+## Consequences
+
+- We are more considered with the approach of our software architecture, leading to pure Domain objects and logic being separated from the Spring Boot implementation.
+- This leads us to being more easily able to split the domain logic out into a separate module/library, allowing for others to consume the core business rules without requiring the use of the Spring Boot application
+- This will provide a little increase in overhead of development while we get used to developing in this style, slowing us down a little
+- It may also introduce overhead for people who are coming to read this as a reference implementation.
+
+## See also
+
+- https://herbertograca.com/2017/09/21/onion-architecture/
+- https://herbertograca.com/2017/08/03/layered-architecture/ (in particular the anti-pattern which we encountered when trialing it)

examples/java/spring-boot/build.gradle

@@ -12,6 +12,7 @@ apply plugin: 'jsonschema2pojo'
 
 dependencies {
   implementation 'org.apache.logging.log4j:log4j-layout-template-json'
+  implementation 'org.jmolecules:jmolecules-onion-architecture:1.4.0'
   implementation 'org.springframework.boot:spring-boot-starter-log4j2'
   implementation 'org.springframework.boot:spring-boot-starter-web'
   implementation 'org.springframework.boot:spring-boot-starter-actuator'
@@ -20,6 +21,7 @@ dependencies {
   testImplementation 'com.github.valfirst:slf4j-test:2.5.0'
   testImplementation 'com.tngtech.archunit:archunit:0.22.0'
   testImplementation 'com.tngtech.archunit:archunit-junit5:0.22.0'
+  testImplementation 'org.jmolecules.integrations:jmolecules-archunit:0.8.0'
   testImplementation 'org.springframework.boot:spring-boot-starter-test'
   testImplementation 'io.rest-assured:json-schema-validator:4.5.0'
 }
@@ -34,7 +36,7 @@ processTestResources.finalizedBy copySchemas
 jsonSchema2Pojo {
   source = files(fileTree(dir: '../../../schemas/v1alpha', include: ['*.json']))
   targetDirectory = file("${project.buildDir}/generated-sources/js2p")
-  targetPackage = "uk.gov.api.models.metadata.v1alpha"
+  targetPackage = "uk.gov.api.springboot.infrastructure.models.metadata.v1alpha"
 }
 
 bootJar {

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/Application.java

@@ -1,8 +1,10 @@
 package uk.gov.api.springboot;
 
+import org.jmolecules.architecture.onion.classical.ApplicationServiceRing;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
+@ApplicationServiceRing
 @SpringBootApplication
 public class Application {
 

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/application/package-info.java

@@ -0,0 +1,11 @@
+/**
+ * The Application (Service) Ring is for only application-specific configuration, such as Spring
+ * Boot, or Spring Dependency Injection, as well as any logic that is implementation-specific
+ * plumbing that makes use of the Domain layer through delegation to an {@link
+ * org.jmolecules.architecture.onion.classical.DomainServiceRing} service and by using {@link
+ * org.jmolecules.architecture.onion.classical.DomainModelRing} models.
+ */
+@ApplicationServiceRing
+package uk.gov.api.springboot.application;
+
+import org.jmolecules.architecture.onion.classical.ApplicationServiceRing;

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/application/services/ApiService.java

@@ -0,0 +1,20 @@
+package uk.gov.api.springboot.application.services;
+
+import java.util.List;
+import org.springframework.stereotype.Service;
+import uk.gov.api.springboot.domain.model.Api;
+import uk.gov.api.springboot.domain.model.repositories.ApiStorage;
+
+@Service
+public class ApiService {
+
+  private final ApiStorage storage;
+
+  public ApiService(ApiStorage storage) {
+    this.storage = storage;
+  }
+
+  public List<Api> retrieveAll() {
+    return storage.findAll();
+  }
+}

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/dtos/Api.java examples/java/spring-boot/src/main/java/uk/gov/api/springboot/domain/model/Api.java

@@ -1,4 +1,4 @@
-package uk.gov.api.springboot.dtos;
+package uk.gov.api.springboot.domain.model;
 
 /** Domain object for API (metadata) objects. */
 public record Api(

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/domain/model/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * The Domain Model Ring is to contain any entities of the business, and their state and behaviour.
+ * Entities in the Domain Model Ring can only be coupled to other things in the Domain Model Ring.
+ */
+@DomainModelRing
+package uk.gov.api.springboot.domain.model;
+
+import org.jmolecules.architecture.onion.classical.DomainModelRing;

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/domain/model/repositories/ApiStorage.java

@@ -0,0 +1,9 @@
+package uk.gov.api.springboot.domain.model.repositories;
+
+import java.util.List;
+import uk.gov.api.springboot.domain.model.Api;
+
+public interface ApiStorage {
+
+  List<Api> findAll();
+}

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/domain/services/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * The Domain Service Ring is to contain anything related to the underlying domain model's business
+ * logic.
+ */
+@DomainServiceRing
+package uk.gov.api.springboot.domain.services;
+
+import org.jmolecules.architecture.onion.classical.DomainServiceRing;

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/config/ContentNegotiationConfiguration.java examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/config/ContentNegotiationConfiguration.java

@@ -1,4 +1,4 @@
-package uk.gov.api.springboot.config;
+package uk.gov.api.springboot.infrastructure.config;
 
 import me.jvt.spring.ContentNegotiator;
 import org.springframework.context.annotation.Bean;

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/config/CorrelationIdFilter.java examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/config/CorrelationIdFilter.java

@@ -1,4 +1,4 @@
-package uk.gov.api.springboot.config;
+package uk.gov.api.springboot.infrastructure.config;
 
 import java.io.IOException;
 import java.util.Optional;

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/config/ErrorResponseDecorator.java examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/config/ErrorResponseDecorator.java

@@ -1,4 +1,4 @@
-package uk.gov.api.springboot.config;
+package uk.gov.api.springboot.infrastructure.config;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import java.io.IOException;
@@ -8,7 +8,7 @@
 import org.springframework.http.MediaType;
 import org.springframework.stereotype.Component;
 import org.springframework.web.HttpMediaTypeNotAcceptableException;
-import uk.gov.api.models.metadata.v1alpha.ErrorResponse;
+import uk.gov.api.springboot.infrastructure.models.metadata.v1alpha.ErrorResponse;
 
 @Component
 public class ErrorResponseDecorator {

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/config/MdcFacade.java examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/config/MdcFacade.java

@@ -1,4 +1,4 @@
-package uk.gov.api.springboot.config;
+package uk.gov.api.springboot.infrastructure.config;
 
 import org.slf4j.MDC;
 import org.springframework.stereotype.Component;

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/mappers/V1AlphaMapper.java examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/mappers/V1AlphaMapper.java

@@ -1,14 +1,12 @@
-package uk.gov.api.springboot.mappers;
+package uk.gov.api.springboot.infrastructure.mappers;
 
 import java.net.URI;
 import org.springframework.stereotype.Component;
-import uk.gov.api.models.metadata.v1alpha.ApiMetadata;
-import uk.gov.api.models.metadata.v1alpha.Data;
-import uk.gov.api.springboot.dtos.Api;
+import uk.gov.api.springboot.domain.model.Api;
+import uk.gov.api.springboot.infrastructure.models.metadata.v1alpha.ApiMetadata;
+import uk.gov.api.springboot.infrastructure.models.metadata.v1alpha.Data;
 
-/**
- * Mapper class to convert service-layer Data Transformation Objects (DTOs) to HTTP-layer objects.
- */
+/** Mapper class to convert Domain objects to Infrastructure objects.. */
 @Component
 public class V1AlphaMapper {
 

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/controllers/v1alpha/ApiController.java examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/models/metadata/v1alpha/ApiController.java

@@ -1,13 +1,11 @@
-package uk.gov.api.springboot.controllers.v1alpha;
+package uk.gov.api.springboot.infrastructure.models.metadata.v1alpha;
 
 import java.util.List;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
-import uk.gov.api.models.metadata.v1alpha.ApiMetadata;
-import uk.gov.api.models.metadata.v1alpha.BulkMetadataResponse;
-import uk.gov.api.springboot.mappers.V1AlphaMapper;
-import uk.gov.api.springboot.services.ApiService;
+import uk.gov.api.springboot.application.services.ApiService;
+import uk.gov.api.springboot.infrastructure.mappers.V1AlphaMapper;
 
 @RestController
 @RequestMapping("/apis")

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * The Infrastructure Ring is to contain any public-facing infrastructure, such as REST, GraphQL,
+ * GRPC, Messaging interfaces, as well as implementations of any infrastructure such as datastores.
+ */
+@InfrastructureRing
+package uk.gov.api.springboot.infrastructure;
+
+import org.jmolecules.architecture.onion.classical.InfrastructureRing;

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/infrastructure/repositories/EmptyApiStorage.java

@@ -0,0 +1,16 @@
+package uk.gov.api.springboot.infrastructure.repositories;
+
+import java.util.Collections;
+import java.util.List;
+import org.springframework.stereotype.Repository;
+import uk.gov.api.springboot.domain.model.Api;
+import uk.gov.api.springboot.domain.model.repositories.ApiStorage;
+
+@Repository
+public class EmptyApiStorage implements ApiStorage {
+
+  @Override
+  public List<Api> findAll() {
+    return Collections.emptyList();
+  }
+}

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/repositories/ApiRepository.java

@@ -1,4 +1,4 @@
-package uk.gov.api.springboot;
+package uk.gov.api.springboot.application;
 
 import static org.assertj.core.api.Assertions.assertThat;
 

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/repositories/EmptyApiRepository.java

@@ -1,4 +1,4 @@
-package uk.gov.api.springboot.services;
+package uk.gov.api.springboot.application.services;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.when;
@@ -10,8 +10,8 @@
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
-import uk.gov.api.springboot.dtos.Api;
-import uk.gov.api.springboot.repositories.ApiRepository;
+import uk.gov.api.springboot.domain.model.Api;
+import uk.gov.api.springboot.domain.model.repositories.ApiStorage;
 
 @ExtendWith(MockitoExtension.class)
 class ApiServiceTest {
@@ -21,11 +21,11 @@ class RetrieveAll {
 
     @InjectMocks private ApiService service;
 
-    @Mock private ApiRepository repository;
+    @Mock private ApiStorage storage;
 
     @Test
     void delegates(@Mock List<Api> apis) {
-      when(repository.findAll()).thenReturn(apis);
+      when(storage.findAll()).thenReturn(apis);
 
       List<Api> actual = service.retrieveAll();
 

examples/java/spring-boot/src/main/java/uk/gov/api/springboot/services/ApiService.java

@@ -15,7 +15,12 @@
 class ArchUnitTest {
   @ArchTest
   @SuppressWarnings("unused")
-  ArchRule requireFinalFields = classesThatAreNotTests().should().haveOnlyFinalFields();
+  ArchRule requireFinalFields =
+      classesThatAreNotTests()
+          .and()
+          .resideOutsideOfPackage("uk.gov.api.springboot.infrastructure.models.metadata..")
+          .should()
+          .haveOnlyFinalFields();
 
   @ArchTest
   @SuppressWarnings("unused")