Skip to content

Commit f5d5cb8

Browse files
odrotbohmodrotbohm
committed
GH-21 - Add project announcing blog post.
1 parent b39e5da commit f5d5cb8

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎etc/introducing-spring-modulith.adoc

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
= Introducing Spring Modulith
2+
:docs: https://docs.spring.io/spring-modulith/docs/0.1.0-M1/reference/html/
3+
4+
When designing software systems, architects and developers have plenty of architectural options to choose from. Microservice-based systems have become ubiquitous in the last couple of years. However, the idea of monolithic, modular systems has also regained popularity recently.
5+
Independent of the architectural style ultimately selected, the individual applications comprising the overall system need their structure to be evolvable and able to follow changes in business requirements.
6+
7+
Traditionally, application frameworks have provided structural guidance by providing abstractions aligned with technical concepts, such as Spring Framework’s stereotype annotations (`@Controller`, `@Service`, `@Repository`, and so on).
8+
However, shifting the focus to https://dannorth.net/2022/02/10/cupid-for-joyful-coding/#domain-based[align code structure with the domain] has proven to lead to better structured applications that are ultimately more understandable and maintainable.
9+
Until now, the Spring team has given verbal and written guidance on how we recommend structuring your Spring Boot applications.
10+
We decided that we can do more than that.
11+
12+
https://spring.io/projects/spring-modulith[_Spring Modulith_] is a new, experimental Spring project that supports developers in expressing these logical application modules in code and in building well-structured, domain-aligned Spring Boot applications.
13+
14+
[[example]]
15+
== An Example
16+
17+
Let us have a look at https://github.com/spring-projects-experimental/spring-modulith/tree/main/spring-modulith-example[a concrete example].
18+
Assume we need to develop an e-commerce application, for which we start with two logical modules.
19+
An _order_ module deals with order processing, and an _inventory_ keeps track of the stock for the products we sell.
20+
Our primary focus for this post is the use case that the inventory needs to be updated once an order is completed.
21+
Our project structure would look something like this (`○` denotes a public type, `-` a private one):
22+
23+
----
24+
□ Example
25+
└─ □ src/main/java
26+
├─ □ example
27+
| └─ ○ Application.java
28+
|
29+
├─ □ example.inventory
30+
| ├─ ○ InventoryManagement.java
31+
| └─ - InventoryInternal.java
32+
|
33+
├─ □ example.order
34+
| └─ ○ OrderManagement.java
35+
└─ □ example.order.internal
36+
└─ ○ OrderInternal.java
37+
----
38+
39+
This arrangement starts with the usual skeleton, a base package that contains the Spring Boot application class.
40+
Our two business modules are reflected by direct sub-packages: `inventory` and `order`.
41+
The inventory uses a rather simple arrangement.
42+
It consists of only a single package. Thus, we can use Java visibility modifiers to hide internal components from access by code residing in other modules, such as `InventoryInternal`, as the Java compiler restricts access to non-public types.
43+
44+
The `order` package, on the contrary, contains a sub-package that exposes a Spring bean which--in our case--needs to be public, because `OrderManagement` refers to it.
45+
This arrangement of types, unfortunately, rules out the compiler as a helper to prevent illegal access to `OrderInternal`, because, in plain Java, packages are not hierarchical.
46+
A sub-package is not hidden inside a parent one.
47+
Spring Modulith, however, establishes the notion of _application modules_, that--by default--consist of an API package (the ones directly located under the application's main package--in our case `inventory` and `order`) and, optionally, nested ones (`order.internal`).
48+
The latter are considered internal, and the code residing in those modules is inaccessible to other modules.
49+
This application module model can link:{docs}#fundamentals.customizing-modules[be tweaked] to your liking, but let us stick with this default arrangement for this post.
50+
51+
[[verification]]
52+
== Verifying the Modular Structure
53+
54+
To verify the application's structure and that our code adheres to the structures we defined, we can create a test case that creates an `ApplicationModules` instance:
55+
56+
[source, java]
57+
----
58+
class ModularityTests {
59+
60+
@Test
61+
void verifyModularity() {
62+
ApplicationModules.of(Application.class).verify();
63+
}
64+
}
65+
----
66+
67+
Assuming `InventoryManagement` introduced a dependency on `OrderInternal`, that test would fail with the following error message and, thus, break the build:
68+
69+
----
70+
- Module 'inventory' depends on non-exposed type ….internal.OrderInternal within module 'order'!
71+
InventoryManagement declares constructor InventoryManagement(InventoryInternal, OrderInternal) in (InventoryManagement.java:0)
72+
----
73+
74+
The initial step (`ApplicationModules.of(…)`) inspects the application structure, applies the module conventions and analyzes which parts of each application module are part of their _provided interface_.
75+
As `OrderInternal` does not reside in the application module's API package, the reference to it from the `inventory` module is considered invalid and, thus, is reported as such in the next step, the invocation of `….verify()`.
76+
77+
The verification as well as the underlying analysis of the application module model are implemented by using https://www.archunit.org/[ArchUnit].
78+
It will reject cyclic dependencies between application modules, access to types considered internal (as per the definition above), and, optionally, allow only references to modules explicitly allow-listed by using `@ApplicationModule(allowedDependencies = …)` on the application modules `package-info.java`.
79+
For more information on how to define application module boundaries and allowed dependencies between them in the link, see the link:{docs}#fundamentals.modules[reference documentation].
80+
81+
[[integration-tests]]
82+
== Application Module Integration Tests
83+
84+
Being able to build a model of the application’s structure is also helpful for integration testing.
85+
Similar to Spring Boot's slice test annotations, developers can indicate that they want to include only the components and configuration for a particular application module by using Spring Modulith's `@ApplicationModuleTest` on an integration test.
86+
This helps to isolate integration tests against changes and the potential failures of tests located in other modules.
87+
An integration test class would look something like this:
88+
89+
[source, java]
90+
----
91+
package example.order;
92+
93+
@ApplicationModuleTest
94+
class OrderIntegrationTests {
95+
96+
// Test methods go here
97+
}
98+
----
99+
100+
Similar to a test case run with `@SpringBootTest`, `@ApplicationModuleTest` finds the application's main class annotated with `@SpringBootApplication`.
101+
It then initializes the application module model, finds the module the test class is located in, and defaults to bootstrap exactly that module.
102+
If you run this class and have the log level for `org.springframework.modulith.test` raised to `DEBUG`, you will see output that looks like this:
103+
104+
----
105+
… - Bootstrapping @ApplicationModuleTest for example.order in mode STANDALONE (class example.Application)…
106+
…
107+
… - ## example.order ##
108+
… - > Logical name: order
109+
… - > Base package: example.order
110+
… - > Direct module dependencies: none
111+
… - > Spring beans:
112+
… - + ….OrderManagement
113+
… - + ….internal.OrderInternal
114+
…
115+
… - Re-configuring auto-configuration and entity scan packages to: example.order.
116+
----
117+
118+
The test execution reports which module is bootstrapped, its logical structure, and how it ultimately alters the Spring Boot bootstrap to include only the module's base package.
119+
It can be link:{docs}#testing.bootstrap-modes[tweaked] to explicitly include other application modules, or bootstrap an entire tree of modules.
120+
121+
[[events]]
122+
== Using Events for Inter-module Interaction
123+
124+
Shifting the integration testing focus towards application modules usually reveals their outgoing dependencies, typically established by references to Spring beans residing in other modules.
125+
While those can be mocked (by using `@MockBean`) to satisfy the test execution, it is often a better idea to replace the cross-module bean dependencies with an application event being published and consuming that with the previously explicitly invoked component.
126+
127+
Our example is already arranged in this preferred way, as it publishes an `OrderCompleted` event during the call to `OrderManagement.complete(…)`.
128+
Spring Modulith's `PublishedEvents` abstraction allows testing that an integration test case has caused particular application events to be published:
129+
130+
[source, java]
131+
----
132+
@ApplicationModuleTest
133+
@RequiredArgsConstructor
134+
class OrderIntegrationTests {
135+
136+
private final OrderManagement orders;
137+
138+
@Test
139+
void publishesOrderCompletion(PublishedEvents events) {
140+
141+
var reference = new Order();
142+
143+
orders.complete(reference);
144+
145+
// Find all OrderCompleted events referring to our reference order
146+
var matchingMapped = events.ofType(OrderCompleted.class)
147+
.matchingMapped(OrderCompleted::getOrderId, reference.getId()::equals);
148+
149+
assertThat(matchingMapped).hasSize(1);
150+
}
151+
}
152+
----
153+
154+
[[summary]]
155+
== A Tool Box for Well-structured Spring Boot Applications
156+
157+
Spring Modulith provides convention and APIs to declare and verify logical modules in your Spring Boot application.
158+
On top of the features described above, the first release has many more features to help developers structuring their applications:
159+
160+
* Support for more link:{docs}#fundamentals.modules.advanced[advanced package arrangements].
161+
* Support to link:{docs}#testing.bootstrap-modes[flexibly select] a set of application modules to include in an integration test run.
162+
* A link:{docs}#events.publication-registry[transaction event publication] log to let developers integrate application modules through events in transactional contexts.
163+
* Deriving link:{docs}#documentation[developer documentation] from the application module structure, including C4 and UML component diagrams as well as the Application Module Canvas (a tabular high-level description of each module).
164+
* Runtime link:{docs}#observability[observability] on the application module level.
165+
* A link:{docs}#moments[Passage of Time Events] implementation.
166+
167+
You can find more about the project in link:{docs}[its reference documentation] and check out the https://github.com/spring-projects-experimental/spring-modulith/tree/main/spring-modulith-example[example project].
168+
Despite the broad set of features already available, this is just the start of the journey.
169+
We look forward to your feedback and feature ideas for the project.
170+
Also, be sure to follow us https://twitter.com/springmodulith[on Twitter] for the latest social media updates on the project.
171+
172+
[[about-moduliths]]
173+
== About Moduliths
174+
175+
Spring Modulith (no trailing "s") is the continuation of the https://github.com/moduliths/moduliths[Moduliths (with trailing "s") project] but using Spring Boot 3.0, Framework 6, Java 17, and JakartaEE 9 as the baseline.
176+
The old Moduliths project is currently available in version 1.3, is compatible with Spring Boot 2.7, and will be maintained as long as the corresponding Boot generation.
177+
We have used the experience gained with it over the last two years, streamlined a few abstractions, tweaked a couple of defaults here and there, and decided to start with a more state-of-the-art baseline.
178+
For more detailed guidance on how to migrate to Spring Modulith, see the Spring Modulith link:{docs}#appendix.migrating-from-moduliths[reference documentation].

0 commit comments

Comments
 (0)