README.md

Java Backend Boilerplate

This repository is designed to the boilerplate for Java Spring projects.

Project Guidelines

• CONTRIBUTING
• INSTALLATION

Project Targets

• People want to start API server based on Spring boot3 with JPA and postgresql quickly.
• People want to force specifications, contracts, and fitness functions.
  • See Consumer-Driven Contract
  • See API-First Design
  • See Evolutionary Architecture
• Development cycles based on XP.

Project Structures

.
├── .github
│   ├── ISSUE_TEMPLATE
│   │   ├── bug_report.md
│   │   └── task-specification.md
│   └── PULL_REQUEST_TEMPLATE.md
├── .vscode
│   ├── eclipse-java-google-style.xml
│   └── settings.json
├── LICENSE
├── README.md
├── build.gradle
├── settings.gradle
├── config
│   └── checkstyle
│       ├── checkstyle.xml
│       └── supressions.xml
├── contracts
│   └── template.yaml
├── docker-compose.yaml
├── docs
│   ├── CODE_OF_CONDUCT.md
│   ├── CONTRIBUTING.md
│   └── INSTALLATION.md
└── src
    ├── main
    │   ├── java
    │   │   └── love
    │   │       └── you
    │   │           └── babe
    │   │               ├── BabeApplication.java
    │   │               ├── controller
    │   │               │   └── TemplateController.java
    │   │               ├── repository
    │   │               │   ├── entity
    │   │               │   │   └── TemplateEntity.java
    │   │               │   └── TemplateRepository.java
    │   │               └── service
    │   │                   ├── model
    │   │                   │   └── Template.java
    │   │                   └── TemplateService.java
    │   └── resources
    │       ├── application-local.yaml
    │       └── application.yaml
    └── test
        ├── java
        │   └── love
        │       └── you
        │           └── babe
        │               ├── contracts
        │               │   ├── TemplateBase.java
        │               │   └── TestcontainersConfiguration.java
        │               └── fitness
        │                   └── LayoutTest.java
        └── resources
            ├── application-test.yaml
            └── contracts
                └── template
                    └── contract.yaml

• .github: Issue and PR templates.
• .vscode: Visual Studio Code settings.
• LICENSE: The project's license.
• build.gradle: Project's build script.
• [settings.gradle][(/settings.gradle): Project's build script.
• config/checkstyle: Project's java style settings.
  • See Checkstyle for Java gradle plugin
• contracts: API Specifications defined by OAS.
  • See Open API Specification
• docker-compose.yaml: Project's runtime script.
• docs: Project's documents.
• src/test/resources/contracts: API's integrational test specifications.
  • See Spring Contract
• src/test/java/love/you/babe/contracts: Contract's base class for setup steps.

Main dependencies

See details

Name	Description
spring-boot-starter-web	API Server
spring-boot-starter-data-jpa	ORM Framework
spring-cloud-starter-contract-verifier	Integration Test Framework
test container for Java	Isolated container
openapi generator for gradle	API IF Generator
docker	Container environment
docker compose	Container stack management
Postgresql	Opensource RDB
Gradle	Java build tool

Development Senario using this boilerplate.

1. Write API Specifications in contracts.
2. Run ./gradlew compileJava to generate API IFs at build/generated.
3. Write API Contracts in src/test/java/love/you/babe/contracts.
4. Run ./gradlew contractTest to check whether integrational tests work.
5. Develop APIs by implementing generated API IFs.
6. Run ./gradlew check to check whether all tests are passed.
7. Run ./gradlew bootBuildImage --imageName=template-java to build server's image.
8. Run docker compose up to host the image.
9. Repeat step 1-8 again.

License

Copyright (c) 2025 happy
This file can be used by MIT License.
See details at LICENSE