spring-petclinic/README.md

Prerequisites Java 17+ Docker (for PostgreSQL) Maven

1. Start PostgreSQL

   docker run --name petclinic-ff
   -e POSTGRES_DB=petclinic
   -e POSTGRES_USER=petclinic
   -e POSTGRES_PASSWORD=petclinic
   -p 5432:5432
   -d postgres:15

2. Run Application ./mvnw spring-boot:run -Dspring.profiles.active=postgres

URLs: App: http://localhost:8080 Flags API: http://localhost:8080/api/flags H2 Console: http://localhost:8080/h2-console Database: localhost:5432/petclinic (user: petclinic, pass: petclinic)

Feature Flags Implemented Flag Key Controls Controller Method Strategy Examples add-pet Add New Pet form PetController.initNewPetForm() Global OFF/ON, Percentage add-visit Add Visit form VisitController.processNewVisit() Percentage rollout (50%) owner-search Owner search OwnerController.processFindForm() Blacklist/Whitelist users

Behavior when OFF: Returns 403 Forbidden → redirects to /oups error page.

Feature Flag Strategies (Advanced) Strategy Configuration Logic GLOBAL {"enabled": true} Everyone ON/OFF BLACKLIST {"users":["test@example.com"]} Blocks listed users WHITELIST {"users":["admin@company.com"]} Only listed users PERCENTAGE {"percentage":25} 25% of users randomly

Feature Flag Management API GET /api/flags # List all flags GET /api/flags/{key} # Get specific flag POST /api/flags # Create flag PUT /api/flags/{key} # Update flag
DELETE /api/flags/{key} # Delete flag

Example API Calls

1. Global OFF (blocks everyone): curl -X POST http://localhost:8080/api/flags
   -H "Content-Type: application/json"
   -d '{ "flagKey": "add-pet", "name": "Add New Pet", "enabled": false, "strategyType": "GLOBAL" }'

2. Percentage Rollout (50% users): curl -X POST http://localhost:8080/api/flags
   -H "Content-Type: application/json"
   -d '{ "flagKey": "add-visit", "name": "Add Visit", "enabled": true, "strategyType": "PERCENTAGE", "strategyValue": "{"percentage":50}" }'

3. Blacklist specific user: curl -X POST http://localhost:8080/api/flags
   -H "Content-Type: application/json"
   -d '{ "flagKey": "owner-search", "name": "Owner Search", "enabled": true, "strategyType": "BLACKLIST", "strategyValue": "{"users":["test@example.com"]}" }'

Test with user email: Add ?email=test@example.com to flagged URLs.

Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────┐
│   PetClinic     │◄──►│FeatureFlagService│◄──►│ PostgreSQL  │
│   Controllers   │    │  + Strategies    │    │  feature_   │
│                 │    │                  │    │  flags table│
└─────────────────┘    └──────────────────┘    └─────────────┘
│                      ▲
└──────────┬───────────┘
           │
┌─────────────────┐
│  @FeatureFlag   │  ← Custom Annotation + AOP
│    Aspect       │
└─────────────────┘

Key Implementation Features Custom-built (No FF4J/Togglz) Database persistence (survives restarts) 4 Strategies: Global/Blacklist/Whitelist/Percentage Custom Annotation @FeatureFlag("add-pet") + AOP Helper function: featureFlagService.isFeatureEnabled(flagKey, userEmail) Edge cases: Fail-open, JSON parsing errors, missing flags default ON No authentication on flag API (per requirements)

Code Locations src/main/java/org/springframework/samples/petclinic/model/ ├── FeatureFlag.java # Entity

src/main/java/org/springframework/samples/petclinic/system/
├── FeatureFlag.java              #  @FeatureFlag annotation

src/main/java/org/springframework/samples/petclinic/service/
├── FeatureFlagService.java       # Core logic + strategies

src/main/java/org/springframework/samples/petclinic/repository/
├── FeatureFlagRepository.java    # JPA

src/main/java/org/springframework/samples/petclinic/controller/
├── FeatureFlagController.java    # REST API

src/main/java/org/springframework/samples/petclinic/aop/
└── FeatureFlagAspect.java        # AOP interceptor

Controllers with flags:
├── PetController.java           # @FeatureFlag("add-pet")
├── VisitController.java         # @FeatureFlag("add-visit")  
└── OwnerController.java         # @FeatureFlag("owner-search")

Demo Script 1. App running normally → All 3 features work 2. Create Global OFF flag → Add Pet → 403 Forbidden 3. Percentage flag → Add Visit works ~50% time (random) 4. Blacklist → Owner search blocked for test@example.com 5. Database → Flags persist after restart 6. CRUD → Create/Update/Delete via API

Troubleshooting

Issue	                Solution
AOP not working	        Add @EnableAspectJAutoProxy to PetClinicApplication.java
JSON parsing fails	    Check strategyValue format
Flags not persisting	Verify Postgres connection
Package not found	    Use org.springframework.samples.petclinic.system

Original Documentation For original PetClinic features, see Spring Petclinic.

🎥 Loom Video Walkthrough: [Insert Loom Link Here]

✨ Fully functional with advanced feature flag strategies, custom annotation, and production-ready code!