Mendesain kontrak Java yang minimal, stabil, expressive, dan mudah diimplementasikan.

Contract design skill:
  ├─ role modeling
  │   ├─ identify capability
  │   ├─ avoid god interface
  │   ├─ separate query/command roles
  │   └─ separate consumer/provider roles
  │
  ├─ abstraction selection
  │   ├─ interface
  │   ├─ abstract class
  │   ├─ sealed interface
  │   ├─ record/enum alternative
  │   ├─ functional interface
  │   └─ final concrete class
  │
  ├─ evolution design
  │   ├─ adding methods
  │   ├─ default methods
  │   ├─ private interface helpers
  │   ├─ skeletal implementation
  │   └─ compatibility risks
  │
  ├─ implementation guidance
  │   ├─ invariants
  │   ├─ protected hooks
  │   ├─ final template methods
  │   ├─ nullability/error rules
  │   └─ contract tests
  │
  └─ failure modeling
      ├─ marker interface abuse
      ├─ inheritance lock-in
      ├─ default method conflict
      ├─ binary/source compatibility trap
      ├─ leaky abstraction
      └─ framework proxy limitation

1. Apakah ini role, family implementation, closed variant, atau concrete value?
2. Apakah caller butuh polymorphism atau cukup function/callback?
3. Apakah implementor butuh shared state/invariant?
4. Apakah public API ini harus bisa bertahan bertahun-tahun?
5. Apakah method ini benar-benar bagian dari kontrak minimum?
6. Apakah default method aman secara semantic dan binary?
7. Apakah abstraction ini mudah dites sebagai contract?
8. Apakah abstraction ini akan dipakai oleh framework/proxy/reflection?

interface UserService {
    User create(User user);
    User update(User user);
    void delete(UserId id);
    Optional<User> findById(UserId id);
    List<User> search(UserQuery query);
    void exportCsv(OutputStream out);
    void importCsv(InputStream in);
    void rebuildIndex();
    void notifyUser(UserId id, Message message);
}

public interface UserLookup {
    Optional<User> findById(UserId id);
}

public interface UserSearch {
    List<User> search(UserQuery query);
}

public interface UserRegistration {
    User create(CreateUserRequest request);
}

public interface UserProfileUpdate {
    User update(UpdateUserRequest request);
}

public interface UserRemoval {
    void delete(UserId id);
}

public final class AccountPageRenderer {
    private final UserLookup users;

    public AccountPageRenderer(UserLookup users) {
        this.users = Objects.requireNonNull(users);
    }
}

public interface ClockSource {
    Instant now();
}

public interface IdGenerator<T> {
    T nextId();
}

public interface Policy<C, R> {
    R evaluate(C context);
}

public abstract class AbstractRetryingClient implements RemoteClient {
    private final RetryPolicy retryPolicy;
    private final ClockSource clock;

    protected AbstractRetryingClient(RetryPolicy retryPolicy, ClockSource clock) {
        this.retryPolicy = Objects.requireNonNull(retryPolicy);
        this.clock = Objects.requireNonNull(clock);
    }

    @Override
    public final Response execute(Request request) {
        Objects.requireNonNull(request, "request");

        RetryState state = RetryState.initial(clock.now());

        while (true) {
            try {
                return doExecute(request, state);
            } catch (TransientRemoteException ex) {
                if (!retryPolicy.shouldRetry(state, ex)) {
                    throw ex;
                }
                state = state.next(clock.now());
            }
        }
    }

    protected abstract Response doExecute(Request request, RetryState state);
}

Interface first untuk role.
Abstract class only when shared implementation is part of the contract.
Final concrete class when extension is not intended.
Sealed type when variant set must be controlled.
Record when this is transparent immutable data carrier.
Enum when this is a fixed set of singleton constants with optional behavior.

public interface OrderManager {
    void submit(Order order);
    void cancel(OrderId id);
    void approve(OrderId id);
    void reject(OrderId id, String reason);
    Optional<Order> find(OrderId id);
    List<Order> search(OrderSearchCriteria criteria);
    void export(OrderExportTarget target);
}

public interface OrderSubmission {
    SubmittedOrder submit(DraftOrder order);
}

public interface OrderCancellation {
    CancelledOrder cancel(OrderId id, CancellationReason reason);
}

public interface OrderApproval {
    ApprovedOrder approve(OrderId id, ApprovalDecision decision);
}

public interface OrderLookup {
    Optional<OrderView> find(OrderId id);
}

public interface CaseReader {
    Optional<CaseSnapshot> find(CaseId id);
}

public interface CaseCommandHandler<C extends CaseCommand> {
    CaseResult handle(C command);
}

public interface EventPublisher<E> {
    void publish(E event);
}

public interface EventHandler<E> {
    void handle(E event);
}

public interface EventBus<E> {
    void publish(E event);
    void subscribe(EventHandler<E> handler);
}

public interface PriceLookup {
    Optional<Money> findPrice(ProductId productId);
}

public interface PriceCalculator {
    Money calculate(PriceContext context);
}

void process(Order order);

SubmittedOrder submit(DraftOrder order);
ApprovedOrder approve(OrderId id, ApprovalDecision decision);
RejectedOrder reject(OrderId id, RejectionReason reason);

1. Operation apa?
2. Input apa yang dianggap valid?
3. Output apa yang dijanjikan?
4. Side effect apa yang mungkin terjadi?
5. Failure apa yang merupakan bagian dari kontrak?

public interface Handler {
    Object handle(Object input);
}

public interface Handler<I, O> {
    O handle(I input);
}

public interface CaseEscalationPolicy {
    EscalationDecision evaluate(CaseSnapshot snapshot, EscalationContext context);
}

public interface CustomerLookup {
    Optional<Customer> find(CustomerId id);
}

public interface CustomerLookup {
    Customer find(CustomerId id); // returns null if missing? throws? unknown
}

public interface OrderSearch {
    List<OrderSummary> search(OrderQuery query);
}

List<OrderSummary> search(OrderQuery query); // may return null

- parameter tidak boleh null kecuali disebutkan;
- return value tidak pernah null kecuali disebutkan;
- missing single value -> Optional;
- missing many values -> empty collection;
- invalid input -> exception yang terdokumentasi;
- domain rejection -> result object atau domain exception sesuai boundary.

public interface PaymentAuthorization {
    AuthorizationResult authorize(AuthorizationRequest request)
            throws PaymentGatewayUnavailableException;
}

Apakah failure ini recoverable oleh caller?
Apakah checked exception memberi value?
Apakah domain rejection harus exception atau result?
Apakah infrastructure failure harus bocor ke domain API?
Apakah method name menunjukkan side effect?

public sealed interface AuthorizationResult
        permits AuthorizationResult.Approved, AuthorizationResult.Declined {

    record Approved(AuthorizationId authorizationId) implements AuthorizationResult {}
    record Declined(DeclineCode code, String message) implements AuthorizationResult {}
}

@FunctionalInterface
public interface Rule<C, R> {
    R evaluate(C context);
}

Predicate<CaseSnapshot> predicate

@FunctionalInterface
public interface EscalationCondition {
    boolean matches(CaseSnapshot snapshot);

    default EscalationCondition and(EscalationCondition other) {
        Objects.requireNonNull(other, "other");
        return snapshot -> this.matches(snapshot) && other.matches(snapshot);
    }
}

@FunctionalInterface
public interface Validator<T> {
    ValidationResult validate(T value);
}

ValidationSeverity severity();

Validator<Order> validator = order -> validateOrder(order);

@FunctionalInterface
public interface Validator<T> {
    ValidationResult validate(T value);

    default ValidationSeverity severity() {
        return ValidationSeverity.ERROR;
    }
}

public interface Repository<ID, T> {
    Optional<T> findById(ID id);

    default T getRequired(ID id) {
        return findById(id).orElseThrow(() -> new NoSuchElementException("No entity: " + id));
    }
}

public interface Policy<C, R> {
    R evaluate(C context);

    default Policy<C, R> traced(String name, PolicyTracer tracer) {
        Objects.requireNonNull(name, "name");
        Objects.requireNonNull(tracer, "tracer");

        return context -> {
            tracer.before(name, context);
            R result = evaluate(context);
            tracer.after(name, context, result);
            return result;
        };
    }
}

public interface SessionAwareService {
    Session currentSession();

    default User currentUser() {
        return currentSession().user();
    }
}

interface Auditable {
    default String label() {
        return "auditable";
    }
}

interface Displayable {
    default String label() {
        return "displayable";
    }
}

final class CaseView implements Auditable, Displayable {
    @Override
    public String label() {
        return Displayable.super.label();
    }
}

class BaseNamed {
    public String name() {
        return "base";
    }
}

interface Named {
    default String name() {
        return "interface";
    }
}

final class Concrete extends BaseNamed implements Named {
}

class implementation > interface default implementation
more specific interface > less specific interface
conflict between unrelated defaults -> must override

interface OldApi {
}

interface OtherApi {
    default void reset() {}
}

class Impl implements OldApi, OtherApi {
}

default void reset() {}

public interface NormalizedText {
    String raw();

    default String normalized() {
        return normalize(raw());
    }

    default boolean isBlankAfterNormalization() {
        return normalize(raw()).isBlank();
    }

    private static String normalize(String value) {
        return value == null ? "" : value.trim().replaceAll("\\s+", " ");
    }
}

Jika helper makin kompleks, kemungkinan logic itu bukan milik interface.
Jika butuh state, interface bukan tempatnya.
Jika butuh inheritance hook, abstract class lebih tepat.
Jika helper domain-heavy, pindahkan ke collaborator.

public interface MoneyFormatter {
    String format(Money money);

    static MoneyFormatter iso() {
        return money -> money.currency().code() + " " + money.amount();
    }
}

public interface UserUtils {
    static boolean isValidEmail(String email) { ... }
    static String normalizeName(String name) { ... }
    static int calculateAge(LocalDate birthDate) { ... }
}

public interface SensitiveData {
}

public interface DomainEvent {
    EventId eventId();
    Instant occurredAt();
}

public interface InternalOnly {
}

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Audited {
    AuditCategory value();
}

public interface Redactable {
    RedactedView redact(RedactionPolicy policy);
}

public interface RuleSet<C> {
    List<Rule<C>> rules();

    default EvaluationReport evaluate(C context) {
        EvaluationReport.Builder report = EvaluationReport.builder();
        for (Rule<C> rule : rules()) {
            report.add(rule.evaluate(context));
        }
        return report.build();
    }
}

public abstract class AbstractRuleSet<C> implements RuleSet<C> {
    private final List<Rule<C>> rules;

    protected AbstractRuleSet(List<Rule<C>> rules) {
        this.rules = List.copyOf(Objects.requireNonNull(rules, "rules"));
    }

    @Override
    public final List<Rule<C>> rules() {
        return rules;
    }
}

public interface EventHandler<E> {
    void handle(E event);
}

public abstract class AbstractEventHandler<E> implements EventHandler<E> {
    private final Class<E> eventType;

    protected AbstractEventHandler(Class<E> eventType) {
        this.eventType = Objects.requireNonNull(eventType, "eventType");
    }

    public final Class<E> eventType() {
        return eventType;
    }
}

External API depends on EventHandler.
Framework can inspect AbstractEventHandler when available.
Custom implementation is still possible.

public abstract class PaymentProcessor {
    public abstract PaymentResult process(PaymentCommand command);
}

public interface PaymentProcessor {
    PaymentResult process(PaymentCommand command);
}

public abstract class AbstractPaymentProcessor implements PaymentProcessor {
    protected final PaymentAudit audit;

    protected AbstractPaymentProcessor(PaymentAudit audit) {
        this.audit = Objects.requireNonNull(audit);
    }
}

public abstract class AbstractImporter<T> {
    public final ImportReport importFrom(InputStream input) throws IOException {
        Objects.requireNonNull(input, "input");

        List<T> records = parse(input);
        ImportReport.Builder report = ImportReport.builder();

        for (T record : records) {
            ValidationResult validation = validate(record);
            if (validation.isValid()) {
                persist(record);
                report.imported(record);
            } else {
                report.rejected(record, validation);
            }
        }

        return report.build();
    }

    protected abstract List<T> parse(InputStream input) throws IOException;

    protected ValidationResult validate(T record) {
        return ValidationResult.valid();
    }

    protected abstract void persist(T record);
}

/**
 * Persists one validated record.
 *
 * Contract:
 * - record is non-null
 * - record has already passed validate(record)
 * - implementation may throw ImportPersistenceException
 * - implementation must not close resources owned by the template
 */
protected abstract void persist(T record);

public abstract class AbstractService {
    protected final Map<String, Object> context = new HashMap<>();
}

public abstract class AbstractService {
    private final Map<String, Object> context = new HashMap<>();

    protected final Optional<Object> contextValue(String key) {
        return Optional.ofNullable(context.get(key));
    }

    protected final void putContextValue(String key, Object value) {
        context.put(Objects.requireNonNull(key), Objects.requireNonNull(value));
    }
}

public sealed interface ApprovalDecision
        permits ApprovalDecision.Approved, ApprovalDecision.Rejected, ApprovalDecision.NeedsMoreInfo {

    record Approved(ApproverId approverId) implements ApprovalDecision {}

    record Rejected(ApproverId approverId, String reason) implements ApprovalDecision {}

    record NeedsMoreInfo(String question) implements ApprovalDecision {}
}

public interface TaxRule {
    TaxResult apply(TaxContext context);
}

public sealed interface TaxDecision
        permits TaxDecision.Taxable, TaxDecision.Exempt, TaxDecision.RequiresReview {

    record Taxable(Money amount) implements TaxDecision {}
    record Exempt(String legalBasis) implements TaxDecision {}
    record RequiresReview(String reason) implements TaxDecision {}
}

public interface Identified<ID> {
    ID id();
}

public interface Versioned {
    long version();
}

public interface AggregateRoot<ID> extends Identified<ID>, Versioned {
}

interface ReadableEntity extends Identified<UUID>, Versioned, Timestamped, Auditable, Serializable, Comparable<ReadableEntity> {
}

public interface AuditTrailWriter {
    void append(AuditRecord record);
}

public record AuditRecord(
        ObjectId objectId,
        long version,
        Instant occurredAt,
        String action
) {}

Extend interface only when every implementation of child role is necessarily also a valid implementation of parent role.

public final class WorkflowEngine {
    public interface Listener {
        void onTransition(TransitionEvent event);
    }
}

JDK dynamic proxy      -> interface-based
CGLIB/Byte Buddy       -> subclass/class-based
Reflection scanning    -> annotation/type metadata
DI container           -> interface or concrete type injection
AOP                    -> proxy boundary dependent

public interface CaseCommandHandler<C extends CaseCommand> {
    CaseResult handle(C command);
}

public sealed interface CaseCommandHandler<C extends CaseCommand>
        permits InternalCaseCommandHandler {
    CaseResult handle(C command);
}

public interface CustomerExporter {
    void export(Customer customer, OutputStream out) throws IOException;
}

ExportFormat supportedFormat();

interface OldApi {
    Number value();
}

interface NewApi {
    Integer value();
}

void write(Data data) throws IOException;

public interface IdGeneratorContract<T> {
    IdGenerator<T> generator();

    @Test
    default void generatedIdsAreNotNull() {
        assertNotNull(generator().nextId());
    }

    @Test
    default void generatedIdsAreUniqueAcrossReasonableSample() {
        Set<T> ids = new HashSet<>();
        for (int i = 0; i < 1_000; i++) {
            assertTrue(ids.add(generator().nextId()));
        }
    }
}

final class UuidGeneratorTest implements IdGeneratorContract<UUID> {
    @Override
    public IdGenerator<UUID> generator() {
        return new UuidGenerator();
    }
}

Interface contract tests:
  ├─ null handling
  ├─ invalid input handling
  ├─ idempotency/non-idempotency
  ├─ deterministic behavior
  ├─ ordering guarantee
  ├─ equality/hash compatibility if relevant
  ├─ exception mapping
  ├─ concurrency expectation if documented
  └─ side-effect boundary

public interface PlatformService {
    void createUser();
    void deleteUser();
    void sendEmail();
    void generateReport();
    void publishEvent();
    void clearCache();
}

public interface UserNameNormalizer {
    String normalize(String value);
}

public final class DefaultUserNameNormalizer implements UserNameNormalizer {
    ...
}

Apakah caller butuh swapping implementation?
Apakah ini public extension point?
Apakah ini dependency inversion boundary?
Apakah test double sulit tanpa interface?
Apakah future implementation realistis atau hanya spekulatif?

public abstract class AbstractThing {
    public abstract void run();
}

public interface CustomerApi {
    Customer find(String id);

    default Customer findOrCreate(String id) { ... }
    default void sendWelcomeEmail(String id) { ... }
    default void auditAccess(String id) { ... }
    default void warmCache(String id) { ... }
}

public interface Important {
}

public interface UserRepository {
    EntityManager entityManager();
}

1. Name role by capability, not implementation.
2. Keep method count minimal.
3. Make inputs domain-specific.
4. Make outputs explicit.
5. Define null policy.
6. Define failure policy.
7. Avoid leaking infrastructure unless the interface is infrastructure.
8. Consider generic parameter only if it increases type safety.
9. Add default methods only when derivable from primitive operations.
10. Write contract tests.

@FunctionalInterface
public interface CaseAssignmentPolicy {
    AssignmentDecision decide(CaseSnapshot snapshot, AgentPool pool);
}

public interface Exporter<T> {
    void export(T value, OutputStream output) throws IOException;
}

public abstract class AbstractTextExporter<T> implements Exporter<T> {
    private final Charset charset;

    protected AbstractTextExporter(Charset charset) {
        this.charset = Objects.requireNonNull(charset, "charset");
    }

    @Override
    public final void export(T value, OutputStream output) throws IOException {
        Objects.requireNonNull(value, "value");
        Objects.requireNonNull(output, "output");

        try (Writer writer = new OutputStreamWriter(output, charset)) {
            write(value, writer);
        }
    }

    protected abstract void write(T value, Writer writer) throws IOException;
}

@Override
public final void export(T value, OutputStream output) throws IOException {
    Objects.requireNonNull(value, "value");
    Objects.requireNonNull(output, "output");

    Writer writer = new OutputStreamWriter(output, charset);
    write(value, writer);
    writer.flush();
}

public sealed interface ValidationResult
        permits ValidationResult.Valid, ValidationResult.Invalid {

    record Valid() implements ValidationResult {}

    record Invalid(List<Violation> violations) implements ValidationResult {
        public Invalid {
            violations = List.copyOf(violations);
            if (violations.isEmpty()) {
                throw new IllegalArgumentException("violations must not be empty");
            }
        }
    }

    static ValidationResult valid() {
        return new Valid();
    }

    static ValidationResult invalid(List<Violation> violations) {
        return new Invalid(violations);
    }
}

public interface CaseService {
    Case create(Case input);
    Case update(Case input);
    void assign(String caseId, String userId);
    void escalate(String caseId);
    void close(String caseId);
    Case find(String caseId);
    List<Case> search(Map<String, Object> filters);
}

public interface CaseIntake {
    CaseId open(OpenCaseCommand command);
}

public interface CaseAssignment {
    AssignmentResult assign(AssignCaseCommand command);
}

public interface CaseEscalation {
    EscalationResult escalate(EscalateCaseCommand command);
}

public interface CaseClosure {
    ClosureResult close(CloseCaseCommand command);
}

public interface CaseLookup {
    Optional<CaseSnapshot> find(CaseId id);
}

public interface CaseSearch {
    Page<CaseSummary> search(CaseSearchQuery query, PageRequest page);
}

public sealed interface EscalationResult
        permits EscalationResult.Escalated,
                EscalationResult.NotAllowed,
                EscalationResult.AlreadyEscalated {

    record Escalated(CaseId caseId, EscalationLevel level) implements EscalationResult {}
    record NotAllowed(CaseId caseId, String reason) implements EscalationResult {}
    record AlreadyEscalated(CaseId caseId, EscalationLevel currentLevel) implements EscalationResult {}
}

public final class DefaultCaseApplicationService
        implements CaseIntake, CaseAssignment, CaseEscalation, CaseClosure {

    private final CaseRepository repository;
    private final CasePolicyEngine policies;
    private final DomainEventPublisher events;

    public DefaultCaseApplicationService(
            CaseRepository repository,
            CasePolicyEngine policies,
            DomainEventPublisher events
    ) {
        this.repository = Objects.requireNonNull(repository);
        this.policies = Objects.requireNonNull(policies);
        this.events = Objects.requireNonNull(events);
    }

    @Override
    public EscalationResult escalate(EscalateCaseCommand command) {
        // command boundary, policy boundary, aggregate state transition, event publication
        throw new UnsupportedOperationException("example");
    }
}

public final class EscalationController {
    private final CaseEscalation escalation;

    public EscalationController(CaseEscalation escalation) {
        this.escalation = Objects.requireNonNull(escalation);
    }
}

- original interface
- role map
- new interfaces
- caller dependency before/after
- tests simplified
- methods removed from public exposure

1. What invariant does it enforce?
2. What state does it own?
3. Which method is template method?
4. Which methods are subclass hooks?
5. Are protected hooks documented?
6. Could this be interface + skeletal implementation?

- derived from primitive operation? safe
- assumes state? risky
- performs side effect? risky
- creates conflict potential? inspect
- could be static helper instead? maybe

Is this a closed variant or an extension point?

1. Interface names should be capability names, not implementation names.
2. Abstract classes should protect invariant, not merely avoid duplicate code.
3. Default methods should be derived, small, and side-effect-light.
4. Protected members are API and require documentation.
5. Avoid protected fields.
6. Avoid god interfaces.
7. Avoid speculative interfaces for every class.
8. Prefer interface + optional skeletal implementation over abstract class-only API.
9. Use sealed interfaces for closed results and domain alternatives.
10. Do not seal plugin/extension interfaces without a deliberate proxy/extension story.
11. Write contract tests for important interfaces.
12. Keep role dependency as narrow as possible.

Role?                         -> interface
Single behavior role?          -> functional interface
Shared implementation/invariant? -> abstract class, ideally behind interface
Closed variant family?         -> sealed interface/class
Transparent immutable data?    -> record
Fixed singleton alternatives?   -> enum
No polymorphism needed?         -> final concrete class