Gradle plugin to create a java and kotlin application based on Clean Architecture following our best practices!
To use the plugin you need Gradle version 7.6.1 or later, to start add the following section into your build.gradle file.
plugins {
id "co.com.bancolombia.cleanArchitecture" version "3.6.3"
}
Or if is a new project execute this script in the root directory of your project.
echo "plugins {
id \"co.com.bancolombia.cleanArchitecture\" version \"3.6.3\"
}" > build.gradle
To use the plugin you need Gradle version 6.9 or later, to start add the following section into your build.gradle.kts file.
plugins {
id("co.com.bancolombia.cleanArchitecture") version "3.6.3"
}
Or if is a new project execute this script in the root directory of your project.
echo "plugins {
id(\"co.com.bancolombia.cleanArchitecture\") version \"3.6.3\"
}" > build.gradle.kts
The Scaffolding Clean Architecture plugin will allow you run 8 tasks:
The cleanArchitecture | ca
task will generate a clean architecture structure in your project, this task has four optional parameters; package
, type
, name
and coverage
.
If you run this task on an existing project it will override the main.gradle
, build.gradle
and gradle.properties
files.
-
package
= <package.we.need>
: You can specify the main or default package of your project.Default Value = co.com.bancolombia
-
type
= <imperative | reactive>
: With this parameter the task will generate a POO project.Default Value = reactive
-
name
= NameProject
: This parameter is going to specify the name of the project.Default Value = cleanArchitecture
-
coverage
= <jacoco | cobertura>
: This parameter is going to specify the coverage tool for the project.Default Value = jacoco
-
lombok
= <true | false>
: Specify if you want to use this plugin .Default Value = true
-
metrics
= <true | false>
: Specify if you want to enable this feature with micrometer .Default Value = true
-
language
= <JAVA | KOTLIN>
: Specify if you want to use this plugin .Default Value = JAVA
-
javaVersion
= <VERSION_1_8 | VERSION_11 | VERSION_17>
: Java version .Default Value = VERSION_17
gradle cleanArchitecture --package=co.com.bancolombia --type=reactive --name=NameProject --coverage=jacoco --lombok=true
gradle ca --package=co.com.bancolombia --type=reactive --name=NameProject --coverage=jacoco --lombok=true
The structure will look like this for java:
π¦NameProject
β£ πapplications
β β πapp-service
β β β£ πsrc
β β β β£ πmain
β β β β β£ πjava
β β β β β β π[package]
β β β β β β β£ πconfig
β β β β β β β β π[configs and beans]
β β β β β β β πMainApplication.java
β β β β β πresources
β β β β β β£ π[properties]
β β β β πtest
β β β β β πjava
β β β β β β π[package]
β β β πbuild.gradle
β£ πdeployment
β β£ π[Dockerfile, Pipelines as a code]
β£ πdomain
β β£ πmodel
β β β£ πsrc
β β β β£ πmain
β β β β β πjava
β β β β β β π[package]
β β β β πtest
β β β β β πjava
β β β β β β π[package]
β β β πbuild.gradle
β β πusecase
β β β£ πsrc
β β β β£ πmain
β β β β β πjava
β β β β β β π[package]
β β β β πtest
β β β β β πjava
β β β β β β π[package]
β β β β β β β πusecase
β β β πbuild.gradle
β£ πinfrastructure
β β£ πdriven-adapters
β β£ πentry-points
β β πhelpers
β£ π.gitignore
β£ πbuild.gradle
β£ πgradle.properties
β£ πlombok.config
β£ πmain.gradle
β£ πREADME.md
β πsettings.gradle
The structure will look like this for kotlin:
π¦NameProject
β£ πapplications
β β πapp-service
β β β£ πsrc
β β β β£ πmain
β β β β β£ πkotlin
β β β β β β π[package]
β β β β β β β£ πconfig
β β β β β β β β π[configs and beans]
β β β β β β β πMainApplication.kt
β β β β β πresources
β β β β β β£ π[properties]
β β β β πtest
β β β β β πkotlin
β β β β β β π[package]
β β β πbuild.gradle.kts
β£ πdeployment
β β£ π[Dockerfile, Pipelines as a code]
β£ πdomain
β β£ πmodel
β β β£ πsrc
β β β β£ πmain
β β β β β πkotlin
β β β β β β π[package]
β β β β πtest
β β β β β πkotlin
β β β β β β π[package]
β β β πbuild.gradle.kts
β β πusecase
β β β£ πsrc
β β β β£ πmain
β β β β β πkotlin
β β β β β β π[package]
β β β β πtest
β β β β β πkotlin
β β β β β β π[package]
β β β β β β β πusecase
β β β πbuild.gradle.kts
β£ πinfrastructure
β β£ πdriven-adapters
β β£ πentry-points
β β πhelpers
β£ π.gitignore
β£ πbuild.gradle.kts
β£ πgradle.properties
β£ πlombok.config
β£ πREADME.md
β πsettings.gradle.kts
The generateModel | gm
task will generate a class and interface in model layer, this task has one required parameter name
.
gradle generateModel --name=[modelName]
gradle gm --name [modelName]
This task will generate something like that:
π¦domain
β£ πmodel
β β£ πsrc
β β β£ πmain
β β β β πjava
β β β β β π[package]
β β β β β β πmodel
β β β β β β β£ πgateways
β β β β β β β β πModelRepository.java
β β β β β β β πModel.java
β β β πtest
β β β β πjava
β β β β β π[package]
β β β β β β πmodel
β β πbuild.gradle
This task will generate something like that for kotlin:
π¦domain
β£ πmodel
β β£ πsrc
β β β£ πmain
β β β β πkotlin
β β β β β π[package]
β β β β β β πmodel
β β β β β β β£ πgateways
β β β β β β β β πModelRepository.kt
β β β β β β β πModel.kt
β β β πtest
β β β β πkotlin
β β β β β π[package]
β β β β β β πmodel
β β πbuild.gradle.kts
The generateUseCase | guc
task will generate a class in model layer, this task has one required parameter name
.
gradle generateUseCase --name=[useCaseName]
gradle guc --name [useCaseName]
This task will generate something like that:
π¦domain
β πusecase
β β£ πsrc
β β β£ πmain
β β β β πjava
β β β β β π[package]
β β β β β β πusecase
β β β β β β β πbusiness
β β β β β β β β πBusinessUseCase.java
β β β πtest
β β β β πjava
β β β β β π[package]
β β β β β β πusecase
β β β β β β β πbusiness
β β πbuild.gradle
This task will generate something like that for kotlin:
π¦domain
β πusecase
β β£ πsrc
β β β£ πmain
β β β β πkotlin
β β β β β π[package]
β β β β β β πusecase
β β β β β β β πbusiness
β β β β β β β β πBusinessUseCase.kt
β β β πtest
β β β β πkotlin
β β β β β π[package]
β β β β β β πusecase
β β β β β β β πbusiness
β β πbuild.gradle.kts
The generateDrivenAdapter | gda
task will generate a module in Infrastructure layer, this task has one required parameter type
.
Whether you'll use generic one also parameter name
is required.
gradle generateDrivenAdapter --type=[drivenAdapterType]
gradle gda --type [drivenAdapterType]
Reference for drivenAdapterType | Name | Additional Options | Java | Kotlin |
---|---|---|---|---|
generic | Empty Driven Adapter | --name [name] | β | β |
jpa | JPA Repository | --secret [true-false] | β | β |
mongodb | Mongo Repository | --secret [true-false] | β | β |
asynceventbus | Async Event Bus | β | β | |
restconsumer | Rest Client Consumer | --url [url] | β | β |
redis | Redis | --mode [template-repository] --secret [true-false] | β | β |
rsocket | RSocket Requester | β | β | |
r2dbc | R2dbc Postgresql Client | β | β | |
kms | AWS Key Management Service | β | β | |
secrets | Secrets Manager Bancolombia | β | β | |
s3 | AWS Simple Storage Service | β | β | |
mq | JMS MQ Client to send messages | β | β | |
ktor | HTTP client for kotlin | β | β | |
dynamodb | Dynamo DB adapter | β | β | |
sqs | SQS message sender | β | β |
This task will generate something like that:
π¦infrastructure
β£ πdriven-adapters
β β πjpa-repository
β β β£ πsrc
β β β β£ πmain
β β β β β πjava
β β β β β β π[package]
β β β β β β β πjpa
β β β β β β β β£ πconfig
β β β β β β β β β πDBSecret.java
β β β β β β β β£ πhelper
β β β β β β β β β πAdapterOperations.java
β β β β β β β β£ πJPARepository.java
β β β β β β β β πJPARepositoryAdapter.java
β β β β πtest
β β β β β πjava
β β β β β β π[package]
β β β β β β β πjpa
β β β β β β β β πhelper
β β β πbuild.gradle
The generateEntryPoint | gep
task will generate a module in Infrastructure layer, this task has one required parameter type
.
Whether you'll use generic one also parameter name
is required.
gradle generateEntryPoint --type=[entryPointType]
gradle gep --type [entryPointType]
Reference for entryPointType | Name | Additional Options | Java | Kotlin |
---|---|---|---|---|
generic | Empty Entry Point | --name [name] | β | β |
restmvc | API REST (Spring Boot Starter Web) | --server [serverOption] default undertow | β | β |
webflux | API REST (Spring Boot Starter WebFlux) | --router [true, false] default true | β | β |
rsocket | Rsocket Controller Entry Point | β | β | |
graphql | API GraphQL | --pathgql [name path] default /graphql | β | β |
asynceventhandler | Async Event Handler | β | β | |
mq | JMS MQ Client to listen messages | β | β | |
sqs | SQS Listener | β | β |
Additionally, if you'll use a restmvc, you can specify the web server on which the application will run. By default, undertow.
gradle generateEntryPoint --type=restmvc --server=[serverOption]
gradle gep --type=restmvc --server=[serverOption]
Reference for serverOption | Name |
---|---|
undertow | Undertow server (default) |
tomcat | Tomcat server |
jetty | Jetty server |
This task will generate something like that:
π¦infrastructure
β£ πentry-points
β β πgeneric
β β β£ πsrc
β β β β£ πmain
β β β β β πjava
β β β β β β π[package]
β β β β β β β πgeneric
β β β β πtest
β β β β β πjava
β β β β β β π[package]
β β β β β β β πgeneric
β β β πbuild.gradle
The generateHelper | gh
task will generate a module in Infrastructure layer, this task has one required parameter name
.
gradle generateHelper --name=[helperName]
gradle gh --name=[helperName]
The generatePipeline | gpl
task will generate CI pipeline inside the folder "./deployment/", this task has one required parameter type
.
gradle generatePipeline --type=[pipelineType]
gradle gpl --type=[pipelineType]
Reference for pipelineType | Name |
---|---|
azure | Azure Pipeline |
github | GitHub Action |
jenkins | Jenkins Pipeline |
circleci | CircleCI Pipeline |
The generateAcceptanceTest | gat
task will generate subproject by karate framework inside the folder "./deployment/", this task has one optional parameter, name
.
name
= NameAcceptanceTestProject
: This parameter is going to specify the name of the acceptance test project.Default Value = acceptanceTest
gradle generateAcceptanceTest --name=[acceptanceTestProjectName]
gradle gat --name=[acceptanceTestProjectName]
Karate is an open-source tool to combine API test-automation, mocks, performance-testing and even UI automation into a single, unified framework. The BDD syntax popularized by Cucumber is language-neutral, and easy for even non-programmers. Assertions and HTML reports are built-in, and you can run tests in parallel for speed.
The generatePerformanceTest | gpt
task will generate Performance test inside the folder "./performance-test/", this task has one required parameter type
.
gradle generatePerformanceTest --type=[performanceType]
gradle gpt --type=[performanceType]
| Reference for **performanceType** | Name |
| ------------------------------ | -------------- |
| jmeter | Jmeter Performance Test |
The validateStructure | vs
Validate that project references aren't violated.
gradle validateStructure
gradle vs
This validation has another best practices verifications, which you can see on the generated
ArchitectureTest
file within the unit tests of the app-service
module.
One important point made by Robert C. Martin on Clean Architecture is the Dependency Rule, that can be summarized like this: source code dependencies can only point inwards. Nothing in an inner circle can know anything at all about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by the code in an inner circle.
Having that in mind, the validateStructure | vs
task performs the following validations:
- Model module: to have no dependencies at all.
- UseCase module: to declare dependency to the Model module ONLY, and no other additional dependencies.
- Infrastructure Layer modules:
- Allow declaration of any external dependency.
- Allow declaration of dependency on Model and/or UseCase modules.
- Avoid declaration of dependency AppService module.
Whitelisting dependencies:
Some dependencies, specially when working with BOMs (Bills of Materials), are injected transversally to the project, making the validation task to flag failures to rules 1 and 2. To avoid this scenario, or other you may encounter, you can configure a set of whitelisted dependencies.
Example:
-
Let's say you have declared a BOM in your project:
dependencies { implementation(platform("com.myorg:my-bom:0.0.1")) }
-
This will make
validateStructure | vs
to flag a failure indicating an error like this:Validating Model Module --- Dependency com.myorg:some-bom is not allowed in Model Layer
-
To avoid this, you can white list your BOM like this:
// build.gradle cleanPlugin { modelProps { whitelistedDependencies = "my-bom, <dep2>, <depN..>" } }
Indicating only the name of the dependencies comma-separated.
The deleteModule | dm
task will delete a sub project, this task has one required parameter module
.
gradle deleteModule --module=[name]
gradle dm --module=[name]
The updateCleanArchitecture | u
task will update plugin and dependencies in all sub projects, this task has one optional parameter dependencies
if you only want to update some dependencies the dependency need to contain the group, and the artifact for example for the dependency cleanArchitecture you will need to append co.com.bancolombia:cleanArchitecture.
It also updates the spring, lombok, gradle and some other dependencies according to the plugin version that you are using, ocassionally it could make changes in other project structural files.
We recommend that you commit your changes to git before running this command, but you can skip the verification passing --git false
.
gradle updateCleanArchitecture --dependencies=[dependency1, dependency2, ...]
gradle u --dependencies=[dependency1, dependency2, ...]
Review the issues, we hear new ideas. Read more Contributing
You can help the Contributors Team to prioritize features and improvements by permitting the Contributors team to send gradle tasks usage statistics to Analytics Server. The Contributors Team collect usage statistics unless you explicitly opt in off.
Due to the user input limitations to gradle task, when running any plugin task you will be notified about the analytics recollection, and you have the possibility to disable this recollection. If you enable or disable analytics explicitly, future task executions will not notify you.
To explicitly enable analytics and avoid the notification message
gradle analytics --enabled true
# o gradle a --enabled true
To disable analytics
gradle analytics --enabled false
# # o gradle a --enabled false
Usage analytics include the commands and selected flags for each execution. Usage analytics may include the following information:
- Your operating system (macOS, Linux distribution, Windows) and its version.
- Java vendor name and version.
- Java specification and runtime versions.
- Plugin version.
- Project language (
kotlin
orjava
) - Task name that was run.
- Workspace information like language, user that is running the task.
- For generate use case, generate model, generate helper and delete module tasks, the name will be sent.
- For all tasks, the type and name, the time it took to run the task, and project type (reactive, imperative).
Read more About Clean Architecure