repository·main·Indexed 27 days ago
https://github.com/spring-projects/spring-petclinicA sample Spring Boot application demonstrating the capabilities of the Spring framework, including Spring Data and other ecosystem components. The project provides a reference implementation for learning Spring Boot, featuring owner, pet, and visit management via web controllers, support for H2, MySQL, and PostgreSQL databases, and containerization options via Docker.
The application uses SCSS for styling. If you modify src/main/resources/static/resources/css/petclinic.scss or upgrade Bootstrap, you must re-compile the CSS using the Maven 'css' profile.
Note: There is no Gradle build profile for compiling CSS.
./mvnw package -P cssSpring Petclinic is a Spring Boot application that requires Java 17 or later. You can run it using Maven or Gradle after cloning the repository.
git clone https://github.com/spring-projects/spring-petclinic.git
cd spring-petclinicUsing Maven:
./mvnw spring-boot:runUsing Gradle:
./gradlew bootRunYou can build a container image using the Spring Boot build plugin (requires a Docker daemon) and then run it locally.
./mvnw spring-boot:build-image# Verify the image exists
docker images | grep petclinic
# Run the container
docker run -p 8080:8080 docker.io/library/spring-petclinic:latest./mvnw spring-boot:build-image
docker run -p 8080:8080 docker.io/library/spring-petclinic:latestFor fast feedback during development, use the specialized test applications provided in the source code. These are set up as main() methods:
PetClinicIntegrationTests: Uses the default H2 database and Spring Boot Devtools.MySqlTestApplication: Uses Testcontainers to manage a MySQL database in Docker.PostgresIntegrationTests: Uses Docker Compose to manage a PostgreSQL database.You can run these directly from your IDE to perform integration testing against specific database types.
By default, Petclinic uses an in-memory H2 database. To use a persistent database, you must activate the corresponding Spring profile using spring.profiles.active.
mysql: For MySQL databases.postgres: For PostgreSQL databases.You can use the provided docker-compose.yml to start database containers. Each service is named after the Spring profile:
docker compose up mysql
# OR
docker compose up postgresThe docker-compose.yml file provides a PostgreSQL service configuration. You can use this to run a PostgreSQL instance compatible with the application.
Key environment variables:
POSTGRES_PASSWORD: The password for the database user (defaults to petclinic).POSTGRES_USER: The database user (defaults to petclinic).POSTGRES_DB: The name of the database to create (defaults to petclinic).services:
postgres:
image: postgres:18.4
ports:
- "5432:5432"
environment:
- POSTGRES_PASSWORD=petclinic
- POSTGRES_USER=petclinic
- POSTGRES_DB=petclinicThe docker-compose.yml file provides a MySQL service configuration. You can use this to run a MySQL instance compatible with the application.
Key environment variables:
MYSQL_ROOT_PASSWORD: Set the root password.MYSQL_ALLOW_EMPTY_PASSWORD: Set to true to allow empty passwords.MYSQL_USER: The database user (defaults to petclinic).MYSQL_PASSWORD: The password for the database user (defaults to petclinic).MYSQL_DATABASE: The name of the database to create (defaults to petclinic).Configuration files can be mounted to ./conf.d to customize the MySQL server settings.
services:
mysql:
image: mysql:9.7
ports:
- "3306:3306"
environment:
- MYSQL_ROOT_PASSWORD=
- MYSQL_ALLOW_EMPTY_PASSWORD=true
- MYSQL_USER=petclinic
- MYSQL_PASSWORD=petclinic
- MYSQL_DATABASE=petclinic
volumes:
- "./conf.d:/etc/mysql/conf.d:ro"CrashController provides a specific endpoint to test how the application handles runtime exceptions and error views. Accessing the /oups endpoint will intentionally throw a RuntimeException to showcase the application's error handling mechanism and the resolution of the error.html view.To create a new owner, use the following endpoints:
/owners/new: Displays the creation form./owners/new: Submits the owner data. On success, it redirects to /owners/{id} and sets a flash message New Owner Created.The PetController handles web requests for managing pets associated with a specific owner. All endpoints are prefixed with /owners/{ownerId}.
| Method | Endpoint | Description |
|---|---|---|
GET | /owners/{ownerId}/pets/new | Displays the form to create a new pet for the owner. |
POST | /owners/{ownerId}/pets/new | Processes the creation of a new pet. Redirects to the owner's profile on success. |
GET | /owners/{ownerId}/pets/{petId}/edit | Displays the form to edit an existing pet. |
POST | /owners/{ownerId}/pets/{petId}/edit | Processes the updates for an existing pet. Redirects to the owner's profile on success. |
DataIntegrityViolationException containing unique_owner_pet_name), a validation error name: duplicate is returned.birthDate cannot be in the future. If it is, a validation error birthDate: typeMismatch.birthDate is returned.id field is disallowed from being bound during updates to prevent unauthorized ID manipulation.The OwnerController provides several web endpoints for managing pet clinic owners, including creation, searching, updating, and viewing details.
Note on Security: The controller uses @InitBinder to disallow the id field and *.id from being bound directly from web requests to prevent ID spoofing during updates.
Search for owners using the following endpoint:
GET /owners
lastName (String): The last name to search for. If omitted, it performs a broad search.page (int): The page number to retrieve (defaults to 1).Behavior:
notFound error on the lastName field./owners/{id}.owners/ownersList view with pagination details (currentPage, totalPages, totalItems, and listOwners).