Introducing Go-Architect

Francisco Daines — Fri, 22 Dec 2023 14:50:27 +0000

Summary

In this article, I will introduce you to a tool called Go-Architect, we will see its main features and how it can be used to analyze the architecture of a project in Go language.

TL/DR

You can find the complete project documentation at https://go-architect.github.io/

What is Go-Architect?

Go-Architect is a Software Architecture Analysis Tool for projects written in Go language. You can use this tool to analyze the design of your artifacts in order to ease decisions related to refactoring your code, fixing issues or evolving the artifact's features.

Why we should use an Architecture Analysis Tool?

Software Architecture Analysis Tool are used to improve quality and maintainability of software architectures.

There are some benefits for using this kind of tools, like:

Early Detection of Design Flaws: Architecture analysis tools can help identify design flaws, inconsistencies, or violations of architectural principles before they become critical issues, saving time and resources by addressing problems when they are easier and cheaper to fix.
Quality Assurance: These kind of tools can enforce best practices, coding standards and clean architecture concepts, ensuring that the software architecture adheres to established guidelines.
Enhance Maintainability: Ensuring that our architecture adheres to established architectural guidelines over time.
Architectural Evolution Analysis: This tools offers several ways to analyze (in different ways) the changes in software architecture over the time.

Features

Go-Architect Provides the following set of analysis tools.

Project Metrics

This Tool display common metrics used to have a quick idea of the size and complexity of our project.

Dependencies Graph

The Dependency Graph is a visual representation that illustrates the relationships and dependencies between packages in a software artifact. It helps developers and maintainers understand packages relations, which is crucial for managing and building complex software projects.

Dependency Structure Matrix

The Dependency Structure Matrix (DSM) Tool is a graphical representation used to visualize and analyze dependencies between packages in a Project.

Instability & Abstractness

The Instability v/s Abstractness Graph is a powerful tool used to analyze how maintainable, flexible, and easy to understand is an artifact.

Dependency Coupling Analysis

Dependency Coupling Tool helps us to detect how coupled is our artifact with a specific dependency, that can be an internal, same organization, external or a standard package.

VCS Analysis

This tool is focused on analyze the VCS history of the artifact, displaying some information about contributions and changes over packages/files in the artifact.

Installation

Requirements

Go v1.19 (https://go.dev/doc/install)
GoCyclo (https://pkg.go.dev/github.com/fzipp/gocyclo) for Cyclomatic complexity metrics
GoCognit (https://pkg.go.dev/github.com/uudashr/gocognit) for Cognitive complexity metrics

Installation Process

At the moment, installing Go-Architect can only be done manually, by executing the following commands:

git clone https://github.com/go-architect/go-architect
cd go-architect
make install

Conclusion

In this article, we have explored the basics of Go-Architect, an Architecture Analysis Tool for Go projects that can be used to improve maintainability, detect design flaws and ensure quality in your project.

You can find the project documentation at https://go-architect.github.io/

Introducing Arch-Go

Francisco Daines — Tue, 20 Apr 2021 22:53:18 +0000

Summary

In this article, we'll show what is Arch-Go and how to use it in order to check the architecture of a project in Go.

What is Arch-Go?

Arch-Go is a testing tool that verifies if your Go project adheres to your architectural guidelines.

A little review of architectural guidelines

The architectural guidelines of a system defines properties like the following:

How packages are defined
How packages interact
What kind of assets should be part of each package
Some properties related to specific assets, for example it describes some functions or interfaces properties.

For instance, let's think that you're working on a Rest Service using a layered structure containing the following three packages: presentation, businesslogic and persistence.

Presentation: it contains our REST handlers.
Business Logic: it contains the components that encapsulates the business logic of our service.
Persistence: it contains components to access our persistence services, like a database client.

As we have decided to use a layered architecture, we can find out some dependency rules between its packages:

The components in presentation package should depend only on components in the businesslogic package.
The components in businesslogic package should depend only on components in the persistence package.
Components in persistence package should not depend on any other package.

What happens if a developer includes a dependency that is not allowed?, for example, a handler that depends on a persistence component. Of course, we should detect this violation in a Pull-Request code review, but as this process is manual then is prone to errors, so we can easily get the following result.

What are the consequences of including these dependencies?, in terms of functionalities maybe there will be no impact, but related to system maintenance there are some implications, like:

Unnecessary coupling between presentation and persistence layers, so changes in persistence probably will have an impact on presentation.
As our handlers have more dependencies, testing them will require more effort.
Onboarding of new developers will be more complex, as the explanation of dependencies is an important part of this process.

Declarative aproach

Arch-Go uses a declarative approach to set the architecture rules, so in order to specify what rules to check we need to setup a YAML file.
The selection of a declarative approach was made thinking in simplify the comprehension of the architectural rules and to help the sharing of these rules between artifacts, products and teams.

Verification rules in Arch-Go

Rules for dependencies between packages:

Set what dependencies between packages are allowed and what are not allowed.

Rules for packages content:

Set the allowed content for the package (interfaces, structs, functions and methods).
Set the restricted content for the package (interfaces, structs, functions and methods).

Cyclic dependencies:

Allows to check for dependency cycles in selected packages.

Functions properties:

Set the maximum number of parameters that functions in a package are allowed to receive.
Set the maximum number of values that functions in a package are allowed to return.
Set the maximum number of public functions per file.
Set the maximum number of lines inside a function.

Architecture validation using Arch-Go

Installation

Arch-Go is currently published as a module, so, in order to install it, you need to execute the go get command, as follows.

$ go get -u github.com/fdaines/arch-go

For the verification of a successful installation process, you can execute the following command:

$ arch-go -h

Creating Dependencies Rules

Going back to our example service, we can see some dependency rules:

Components in presentation package should only depends on components in businesslogic package.
Components in businesslogic package should only depends on components in persistence package.
Components in persistence package should not depends on any other package.

Those dependency rules, can be described using the Arch-Go YAML schema as follows:

dependenciesRules:
  - package: "**.presentation"
    shouldOnlyDependsOn:
      - "**.businesslogic"
  - package: "**.businesslogic"
    shouldOnlyDependsOn:
      - "**.persistence"
    shouldNotDependsOn:
      - "**.presentation"
  - package: "**.persistence"
    shouldNotDependsOn:
      - "**.presentation"
      - "**.businesslogic"

Running Arch-Go

To run Arch-Go we will use an example project that has the code and rules defined.

$ git clone https://github.com/fdaines/arch-go-sample-project.git
$ cd arch-go-sample-project
$ arch-go

As our project complies with our architectural guidelines, the output should be similar to:

Of course, we have a code example that violates a dependency rule (the branch is named: dependency-rule-violation). To check this example, just run in the command line

$ git checkout dependency-rule-violation
$ arch-go

In this case, the output from Arch-Go should be similar as follows.

Running Arch-Go as part of a Github Actions Workflow

To include Arch-Go verification as part of a Github actions workflow, you need to include a YAML file under github/workflows/, with content as follows:

name: 'arch-go'

on:
  workflow_dispatch:
  push:
    branches:
      - master

jobs:
  Arch-Go:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-go@v2
        with:
          stable: 'false'
          go-version: '1.15'
      - name: Install Arch-Go
        run: go get -u github.com/fdaines/arch-go
      - name: Run Arch-Go
        run: arch-go

Then, each time we push into master branch, Github Actions will run this workflow and checks if the code complies with our architectural guidelines.

Conclusion

In this article, we have explored the basics of using Arch-Go to check our projects. Arch-Go simplifies the verification of architectural guidelines improving the quality project for reducing maintenance costs.

Forem: Francisco Daines

Introducing Go-Architect

Summary

TL/DR

What is Go-Architect?

Why we should use an Architecture Analysis Tool?

Features

Project Metrics

Dependencies Graph

Dependency Structure Matrix

Instability & Abstractness

Dependency Coupling Analysis

VCS Analysis

Installation

Requirements

Installation Process

Conclusion

Introducing Arch-Go

Summary

What is Arch-Go?

A little review of architectural guidelines

Declarative aproach

Verification rules in Arch-Go

Rules for dependencies between packages:

Rules for packages content:

Cyclic dependencies:

Functions properties:

Architecture validation using Arch-Go

Installation

Creating Dependencies Rules

Running Arch-Go

Running Arch-Go as part of a Github Actions Workflow

Conclusion