How to switch from one AI model to another in Java without changing behavior: depend on a port, keep the model id in config, validate typed output, and gate the swap with a golden set, shadow traffic, and a canary.
Port
Domain code calls an interface you own. Never a vendor SDK, never a model name.
Adapter
One class implements the port with Spring AI or LangChain4j. Provider details stop there.
Config
The model id, base URL, and limits live in application.yml. A swap is a config change.
Contract
Output is a record with enums. Validate it, retry once, then fail loudly. Prompts are versioned.
Gate
Golden set, then shadow, then canary. Rollback is flipping the config back, not a deploy.