An opinionated Maven archetype to quickly bootstrap backend API on a sane basis. Pragmatic is in the early phase of development and is not production ready. Contributions are welcomed.
- Clone the project:
git clone git@github.com:salmanebah/pragmatic-archetype.git
- Install locally:
mvn install
- Generate a project:
cd directory/where/to/generate
andmvn archetype:generate -DarchetypeCatalog=local
- Follow the instructions to complete the generation.
- Only use frameworks and libraries when really needed:
Java SE > JSR > Spring framework > other libraries
- Prefer programmatic Spring setup to their annotation-driven counterpart (exception in
Controller
,Request
andResponse
objects) - Strive for rich domains and avoid anemic domains at all cost
- Avoid Mapping frameworks
- Restrict usage of mocking frameworks to the minimum. If possible use an in-memory version of the SUT collaborators.
- Keep these principles when writing tests
Pragmatic
is based on:
- Spring Boot web framework
- Jooq for the Database access
- Flyway for database migration
- Test containers for integration tests
- ArchUnit for architecture level tests
- Docker and Docker Compose for local development
-
domain
should contain all theentities
,value objects
,aggregate roots
and domainevents
-
usecase
should contain all the system use cases. A use case can be defined as a complete interaction between a user and the system. -
repository
should contain all the persistent components that access the datasource. Repositories should deal withentities
oraggregate roots
. -
service
should contain domain and application services. -
task
should contain asynchronous and scheduled jobs. A task should beRunnable
orCallable
and must be configured in a Spring Configuration class (i.e without using the@Scheduled
annotation). -
rest
should contain the API controllers, requests, responses and mappers. -
configuration
should contain all the spring configuration related classes. Spring Beans must be created explicitly (i.e without@Repository
,@Service
, ... stereotypes)
- i18n-ready API error messages and default messages for common errors
- Swagger documentation under
/api-doc
and/swagger
for all controllers - A docker and docker compose environment for local development
- Monitoring with Actuator available at
/actuator
, Prometheus on port9090
and Grafana on port3000
(default admin password is !changeMe!) - A Github pipeline to run unit and integration tests upon pull request and merge on the
master
branch
mvn generate-sources -Pjooq
to generate jooq classes from migration filesmvn test
to only execute unit testsmvn verify -Pit
to only execute integration testsmvn verify
to execute all the testsdocker-compose up
to run the application and all the dependencies