Awesome
Linter used to enforce some good project structure and validate top level architecture (code layers)
Quick start
What exactly is project architecture?
You can imagine some simple architecture, for example classic onion part from "clean architecture":
And describe/declare it as semantic yaml linter config:
version: 3
workdir: internal
components:
handler: { in: handlers/* } # wildcard one level
service: { in: services/** } # wildcard many levels
repository: { in: domain/*/repository } # wildcard DDD repositories
model: { in: models } # match exactly one package
commonComponents:
- models
deps:
handler:
mayDependOn:
- service
service:
mayDependOn:
- repository
see config syntax for details.
And now linter will check all project code inside internal
workdir
and show warnings, when code violate this rules.
For best experience you can add linter into CI workflow
Example of broken code
Imagine some main.go
, when we provide repository
into handler
and get some bad
flow:
func main() {
// ..
repository := booksRepository.NewRepository()
handler := booksHandler.NewHandler(
service,
repository, // !!!
)
// ..
}
Linter will easily found this issue:
Install/Run
Wia Docker
docker run --rm -v ${PWD}:/app fe3dback/go-arch-lint:latest-stable-release check --project-path /app
other docker tags and versions
From sources
It require go 1.20+
go install github.com/fe3dback/go-arch-lint@latest
go-arch-lint check --project-path ~/code/my-project
# or
cd ~/code/my-project
go-arch-lint check
Precompiled binaries
IDE plugin for autocompletion and other help
<img src="https://user-images.githubusercontent.com/2073883/104641610-0f453900-56bb-11eb-8419-6d94fbcb4d2f.png" alt="jetbrains goland logo" align="left" width="80px" height="80px">https://plugins.jetbrains.com/plugin/15423-goarchlint-file-support
Usage
How to add linter to existing project?
Adding a linter to a project takes several steps:
- Current state of the project
- Create a
.go-arch-lint.yml
file describing the ideal project architecture - Linter find some issues in the project. Don’t fix them right now, but “legalize” them by adding them to the config and marking
todo
with the label - In your free time, technical debt, etc. fix the code
- After fixes, clean up config to target state
Execute
Usage:
go-arch-lint check [flags]
Flags:
--arch-file string arch file path (default ".go-arch-lint.yml")
-h, --help help for check
--max-warnings int max number of warnings to output (default 512)
--project-path string absolute path to project directory (where '.go-arch-lint.yml' is located) (default "./")
Global Flags:
--json (alias for --output-type=json)
--output-color use ANSI colors in terminal output (default true)
--output-json-one-line format JSON as single line payload (without line breaks), only for json output type
--output-type string type of command output, variants: [ascii, json] (default "default")
This linter will return:
Status Code | Description |
---|---|
0 | Project has correct architecture |
1 | Found warnings |
How is working?
Linter will:
- match/mark go packages with components
- finds all dependencies between components
- build a dependency graph
- compares the actual (code) and desired (config) dependency graph
- if it got a non-empty DIFF, then project has some issues
Graph
Example config of this repository: .go-arch-lint.yml
You can generate dependencies graph with command graph
:
go-arch-lint graph
See full graph documentation for details.
Pre-Commit
go-arch-lint can also be used as a pre-commit hook, acting before each commit is made.
This is useful to always check that your new code still respects your repo architecture, and to always update your graph SVG.
- Install pre-commit from https://pre-commit.com/#install
- Create a
.pre-commit-config.yaml
file at the root of your repository with the following content:
repos:
- repo: https://github.com/fe3dback/go-arch-lint
rev: master
hooks:
- id: go-arch-lint-check
- id: go-arch-lint-graph
args: ['--include-vendors=true', '--out=go-arch-lint-graph.svg']
- If needed, add any flags you need in
args
. - Auto-update the config to the latest repos' versions by executing
pre-commit autoupdate
- Install with
pre-commit install
- Now you're all set! Try a commit, and see the logs (passing or failing).