Architectural refactoring changes a boundary, not a contract
External consumers are not only users: they include API clients, modules, tests, event subscribers, and other services. Architectural refactoring can move responsibility into a collaborator or interface, but the endpoint, topic, payload, signatures, and side-effect order must remain unchanged.
For example, event publication can move from OrderService to OrderEventPublisher if business logic does not change the external topic or payload.
| Boundary | What to preserve |
|---|---|
| REST API | Routes, statuses, body, and public signatures |
| Event integration | Topic, payload, and publication order |
| Data flow | Records, transactions, and observable side effects |
| Architecture | Clearer responsibility without a hidden migration |
What must not be added silently to a refactor
- changes to REST responses or public signatures;
- renaming a topic or changing the event format;
- updating Spring, Kafka, or other dependencies;
- changing business rules and fixing defects;
- changing transport or serialization configuration;
- broad cleanup in neighboring modules.
Plan an architectural change
- Record current behavior with integration, API, and characterization tests.
- Define one architectural boundary to clean up.
- Move responsibility into a collaborator or interface without changing the contract.
- Work in small steps without dependency updates or unrelated formatting.
- Run applicable unit, integration, build, lint, and type-check checks.
- Check the diff and whether one logical revert is possible.
PR acceptance criteria
| Criterion | What to confirm |
|---|---|
| Behavior | External results and contracts are unchanged |
| Scope | The diff is limited to one idea |
| Quality | Relevant checks succeed |
| Architecture | Class responsibilities are clearer |
| Safety | No accidental dependencies, config changes, or migration |
| Recovery | The changes are easy to revert with one revert |
The human role in acceptance
Tools and tests provide evidence, but they do not define the task boundary by themselves. A person decides whether the change is truly refactoring, whether the work should be split, whether the interface improves the architectural boundary, and whether the PR is clear enough for safe acceptance.
In the PR description, show the goal, affected files, non-goals, commands run, risk assessment, and behavior-preservation status separately.
Canonical lesson source · JavaRush
Open JavaRush material