Product Catalog Service with REST API

Description

Application is a demo of a product catalog having simplified logic.

Used technologies

• Java 25
• Maven 4 (wrapper)
• Maven BuildTime Profiler Extension
• Spring Boot
• Spring Web MVC
• Spring Cache (Caffeine)
• Spring Data JPA
• Flyway DB migration tool
• H2 DB
• Project Reactor
• Resilience4j
• Lombok
• Docker
• OpenAPI 3 & Swagger UI (springdoc-openapi)
• JUnit Jupiter
• Mockito
• JaCoCo
• CycloneDX SBOM
• OWASP

Misc

• Repository is licensed under Apache License 2.0
• Repository uses GitHub Actions (Java_CI_with_Maven)
• Repository uses Renovate dependency updates (via Renovate GitHub App)
• Repository uses Dependabot dependency updates (see dependabot.yml)
• Readme badges are rendered using shields.io
• JaCoCo badges sources are generated by jacoco-badge-generator
• LoC badge is generated by SCC
• ER diagram is generated by mermaid.live
• ASCII Art for SpringBoot banner was generated with TAAG (font Calvin S)
• SpringBoot custom Favicon was generated with favicon.cc

Functionality

• Application implements CRUD operations for Categories and Products
• Category and Product services are @Transactional to avoid race condition
• Application gets currency exchange rates from Frankfurter https://frankfurter.dev
  • Frankfurter REST API is called via Spring RestTemplate and decorated with Resilience4j CircuitBreaker
• Rates are cached with Caffeine during a period of their validity
  • Cache eviction is scheduled to 16:01 CET MON-FRI

Database

Application DB stores categorized products:

• Categories are multilevel (i.e. Computers <-- Portable computers <-- Tablets)
• Products can relate to multiple categories (i.e. MacBook relates to Notebook and to Apple)
• Product prices are stored in original and base currency (i.e. original price in USD and calculated price in EUR)

DB migration is done with Flyway using scripts:

• V1__create_schema.sql
  • initial script target/classes/db/create_schema.sql is generated with Spring Data JPA when starting application with dev profile (for details see application-dev.yml)
• V2__insert_data.sql

Application uses H2 DB.

Configuration

See application specific configuration in pcs: section of application.yml

Getting started

Maven build

# Build with Maven wrapper
$ ./mvnw package

Maven BuildTime Profiler Extension

The BuildTime Profiler Extension is activated by default. To deactivate the profiler extension for all maven builds just uncomment the parameter -Dmaven-build-time-profiler.disabled in maven.config.

Docker build

# Build and tag Docker image with Docker
# Firstly build artifact required by Docker with Maven Wrapper
$ ./mvnw package -DskipTests
# Secondly build with Docker
$ docker build -t mirogaudi/product-catalog-service:1.0.0 .
$ docker tag mirogaudi/product-catalog-service:1.0.0 mirogaudi/product-catalog-service:latest

# Or build Docker image with Maven wrapper via Docker plugin
$ ./mvnw package -Pdocker -DskipTests

Run

Run with Java

# Run with Java
$ java -jar target/product-catalog-service-1.0.0.jar

Run with Maven

# Run with Maven wrapper (via Spring Boot plugin)
$ ./mvnw spring-boot:run

Run with Docker

# Run with Docker
$ docker run -it -d --rm --name product-catalog-service -p 8080:8080 mirogaudi/product-catalog-service:latest

Run in IDE

Just run in IDE: ProductCatalogServiceApplication.java

View and try Application API

• OpenAPI docs: http://localhost:8080/pcs/v3/api-docs
• Swagger UI: http://localhost:8080/pcs/swagger-ui/index.html
• HTTP client: request-categories.http, request-products.http

Spring Boot Actuator

• Actuator: http://localhost:9000/actuator
• Swagger UI: http://localhost:8080/pcs/swagger-ui/index.html?urls.primaryName=x-actuator
• HTTP client: request-actuator.http

View DB

• H2 console http://localhost:8080/pcs/h2-console
  • url: jdbc:h2:file:./target/db/pcs;AUTO_SERVER=TRUE
  • username: sa
  • password: <empty>

Code quality

Static code analysis

# Build performing static code analysis
$ ./mvnw package -Pcheckstyle,pmd,spotbugs -DskipTests

Checkstyle

Project uses checkstyle.xml configuration based on customized Checkstyle google_checks.xml.

# Build checking with Checkstyle
$ ./mvnw validate -Pcheckstyle -DskipTests

PMD

# Build checking with PMD
$ ./mvnw package -Ppmd -DskipTests

SpotBugs

# Build checking with SpotBugs
$ ./mvnw package -Pspotbugs -DskipTests

Code coverage

# Build generating JaCoCo code coverage report and checking code coverage metrics
$ ./mvnw package -Pcode-coverage

Software Bill of Materials (SBOM)

CycloneDX SBOM

# Build generating CycloneDX SBOM
$ ./mvnw package -Psbom -DskipTests

Generated SBOM can be reviewed:

• as file ./target/classes/META-INF/sbom/application.cdx.json

• or via SBOM Actuator Endpoint http://localhost:9000/actuator/sbom/application

  (Just rerun Application with Java or Maven)

Dependencies vulnerabilities

OWASP

# Build generating OWASP dependency vulnerability report
$ ./mvnw package -Powasp -DskipTests

Snyk

Snyk analysis can be viewed at snyk.io: Snyk Test Results

Maintenance

Update dependencies

Dependencies are to be updated automatically with Renovate/Dependabot or could be updated manually.

Update Maven Wrapper

# Update Maven wrapper to use Maven a.b.c 
$ mvn wrapper:wrapper -Dmaven=<a.b.c>

Check for new versions with versions-maven-plugin

# Check for Maven plugins updates
$ ./mvnw versions:display-plugin-updates

# Check for Maven parent updates
$ ./mvnw versions:display-parent-updates

# Check for Maven property-linked dependencies updates
$ ./mvnw versions:display-property-updates

# Check for Maven dependencies updates
$ ./mvnw versions:display-dependency-updates

To ignore case-insensitive alpha, beta, dev, milestone and release candidate versions in checks above add the following D-parameter: maven.version.ignore='(?i).*[-.](alpha|beta|dev|m|rc)([-.]?\d+)?'

$ ./mvnw -Dmaven.version.ignore='(?i).*[-.](alpha|beta|dev|m|rc)([-.]?\d+)?' versions:<goal>

TODO:

• update:
  • SB to v4 (https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide)
  • flywaydb to v12
  • springdoc-openapi to v3
• clean up:
  • use Flyway with maven plugin instead of dev app props
  • test db with integration testing
  • check if all transactions are valid and using proxy classes
  • use WebClient or declarative web call instead of RestTemplate
  • check cache test
  • use https://spring.io/guides/gs/cloud-circuit-breaker for Circuit Breaker
    • test it
  • use logback
  • use Rest Assured for integration testing
• use conventional commits https://www.conventionalcommits.org/
• add semantic releases (https://semver.org/) and/or CHANGELOG.md https://keepachangelog.com/
• implement:
  • add PATCH call to update price
  • add price history