Guard system architecture in the form of automated unit tests

1 Background <br>With the iteration of requirements development, the size of the code base gradually increases, the introduction of new team members and many other factors, the architectural rules formulated at the beginning of the system are inevitably destroyed. It not only destroys the unified development specification of the team, but more importantly, with the gradual growth of the code base, the maintainability and scalability of the system are greatly reduced, and the review complexity and refactoring cost are increased. R&D costs increase.

In an agile development environment, the system delivers value through iterative increments, as does the system architecture. It is impossible for the team to establish a perfect system architecture at the beginning of the project, and the system architecture should continuously evolve with the system iteration.

Architecture evolution and architecture corruption are different perspectives on architecture: architecture corruption looks at the status quo, architecture evolution focuses on the future

Structural corruption is inevitable, and corruption is bound to occur over time. And what we need to do is: find and fix early in some way

2 Why choose Archunit
We need to introduce a mechanism or technology to reduce or detect the occurrence of architecture corruption early and maintain a unified system architecture constraint.

• Support schema rule automated checking
• Lightweight and low access cost
• Timely feedback of results
• Flexible expansion and low expansion cost

Common verification methods for architectural rules: code review, code quality analysis tool or platform, Archunit

The advantages and disadvantages of several common methods are compared below:

Code Review: Enhance the intensity and quality of code reviews by controlling the occurrence of code review activities through strong processes

Advantage

• No need to introduce additional technology, no learning cost
• Flexible: More comprehensive coverage of architectural constraints through manual review

disadvantage

• Non-automatic execution, quality is ensured manually, and there are many uncontrollable human factors
• The wider the scope of the code review, the greater the labor cost
• The code review process is behind, and the rule detection results cannot be fed back in time

Code quality analysis tools: such as Sonar, Checkstyle, etc.

Advantage

• Mature tool or platform with built-in out-of-the-box rules
• Third-party tool support, does not affect the code base structure

disadvantage

• Lack of flexibility, limited support for architectural rule constraints, and inability to solve architectural-level rule constraints well
• Emphasizes code quality analysis results and cannot effectively handle mandatory rule constraints
• There is a certain cost for custom rules (varies due to platform scalability)

Archunit: Automated checking of architectural rules in the form of unit tests

Advantage

• Support rich architectural constraint rule customization capabilities, such as hierarchical dependency rules, package dependency rules, circular dependencies, inheritance relationship constraints, etc.
• Although it is reflected in the form of single test code, it does not affect the development of the main business. It can be introduced incrementally to gradually enhance the architectural constraint capability of the application.
• The Java streaming API provided by Archunit is easy to understand, low cost to access and use
• Use the pure Java unit test framework to automate the execution in the form of unit tests, and feedback the unit test results in time

disadvantage

• Additional unit test code needs to be written, which increases the workload
• Introducing a new class library has a certain learning cost

3 What is Archunit
ArchUnit is a free, simple and extensible class library that can use any Java unit testing framework to check the architectural constraints of Java code. Based on Archunit we can automatically detect:

• circular dependency
• package containment
• class dependencies
• Inclusion of classes and packages
• inheritance relationship
• annotation

The relationship between Archunit and code quality analysis tools is shown in the figure below. Both of them can analyze code, and there is a certain overlap in function coverage.

Archunit can not solve the automatic verification of constraints of all architectural properties , it mainly focuses on the evolution, maintainability, testability, interpretability of the system, etc., and can also verify the coupling degree and naming conventions.

4 Introducing Archunit

4.1 Start is so easy <br>It is very simple to use Archunit to write architectural rule constraints, which provides a convenient streaming API to quickly build rules.

Example 1: RULE.01 All enumeration classes must be suffixed with Enum

Example 2: Constraint Checking on Application Hierarchy

The result of executing Archiunit unit test under IDE is shown in the following figure:

4.2 How to organize schema rules <br>Architecture rules can be organized from multiple dimensions, such as:

Shown on the left side of the following figure: Grouping rules based on logical classification

Shown on the right side of the image below: Grouping rules based on functional classification

4.3 How to standardize the team<br>Whether the team should introduce Archunit itself is also an architectural decision. It is recommended to record the decision in a documented form. For the record form, please refer to "Lightweight Architecture Decision Recording Mechanism"

If the team wants to introduce Archunit, it can be implemented based on the model of preparation-pilot-optimization-promotion from a process and standardization perspective:

Preparation for implementation:

• From the perspective of specification reuse, the team needs to define a unified development specification, including but not limited to coding specification, exception specification, naming specification, dependency specification, etc., and reach an agreement within the team. It is recommended to use a uniform, documented form of recording (eg, an online form system). For each development rule, it is recommended to add dimension description information such as "positive example", "counterexample", "rule description", "rule detailed description", "whether it can be automatically implemented", etc.
• Implement common architectural constraints based on Archunit for reuse across different projects

Application Pilot : Select a pilot application within the product line

Review and optimization : Conduct review based on pilot effects, optimize architecture rules based on feedback from team members, modify and discard existing rules, etc.

Popularization : Promote and popularize some practices based on the pilot in other applications or business lines

For the legacy system , specific rules have been formed (possibly corrupted), and due to the continuous iteration of the business system, it is unlikely that the existing system will be completely reconstructed on a large scale in a single iteration. Therefore, it is recommended to adopt an incremental approach , gradually introduce and enrich architectural rules within the acceptable range of iterative R&D resources, and refactor the application code that violates the rules.

5 Conclusion
What Archunit can't do:

• process files
• Test all schema properties
• Only JVM languages are supported
• SOURCEAnnotation
• A large amount of code needs to be imported, and the impact of the duration after adding the CICD pipeline
• Cannot guarantee its own maintainability

Archunit is extremely valuable for automated detection of architectural constraints, and has low access and customization costs. It is strongly recommended that teams introduce pilots. After the introduction of Archunit for automatic checking of architectural constraints, the following aspects will be affected:

• Helps reduce system architecture corruption and improve system maintainability
• The introduction of new class libraries has a certain learning cost
• Code review activities add one more activity: perform architectural constraint unit testing
• In daily development, development members need to continuously execute and pay attention to the single test results of architectural constraints, and ensure that the tests pass