SOLID Principles — The Foundation of Clean Code

package com.example.solid.srp.bad;
 
import java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Instant;
import java.util.Objects;
 
/**
 * Everything that could ever happen to an invoice lives here.
 * Any change to PDF layout, SMTP, disk layout, or validation rules touches this type.
 */
public final class InvoiceEverythingService {
 
    public record Invoice(String id, String customerId, BigDecimal amount, Instant createdAt) {
    }
 
    public Invoice createInvoice(String customerId, BigDecimal amount) {
        Objects.requireNonNull(customerId, "customerId");
        Objects.requireNonNull(amount, "amount");
        if (amount.signum() <= 0) {
            throw new IllegalArgumentException("amount must be positive");
        }
        if (customerId.isBlank()) {
            throw new IllegalArgumentException("customerId must not be blank");
        }
        return new Invoice("INV-" + System.nanoTime(), customerId, amount, Instant.now());
    }
 
    public void saveToDisk(Invoice invoice, Path directory) throws Exception {
        Objects.requireNonNull(invoice, "invoice");
        Objects.requireNonNull(directory, "directory");
        Path file = directory.resolve(invoice.id() + ".txt");
        String line = invoice.id() + "|" + invoice.customerId() + "|" + invoice.amount() + "|"
                + invoice.createdAt() + "\n";
        Files.writeString(file, line);
    }
 
    public void emailCustomer(Invoice invoice, String smtpHost) {
        System.out.println("EMAIL via " + smtpHost + " to customer " + invoice.customerId()
                + " for invoice " + invoice.id());
    }
 
    public byte[] renderPdf(Invoice invoice) {
        String text = "Invoice " + invoice.id() + " amount=" + invoice.amount();
        return text.getBytes(StandardCharsets.UTF_8);
    }
}

package com.example.solid.srp.good;
 
import java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Instant;
import java.util.Objects;
 
record Invoice(String id, String customerId, BigDecimal amount, Instant createdAt) {
}
 
final class InvoiceValidator {
    public void validateNew(String customerId, BigDecimal amount) {
        Objects.requireNonNull(customerId, "customerId");
        Objects.requireNonNull(amount, "amount");
        if (customerId.isBlank()) {
            throw new IllegalArgumentException("customerId must not be blank");
        }
        if (amount.signum() <= 0) {
            throw new IllegalArgumentException("amount must be positive");
        }
    }
}
 
final class InvoiceFactory {
    public Invoice newInvoice(String customerId, BigDecimal amount) {
        return new Invoice("INV-" + System.nanoTime(), customerId, amount, Instant.now());
    }
}
 
final class InvoiceFileRepository {
    public void save(Invoice invoice, Path directory) throws Exception {
        Objects.requireNonNull(invoice, "invoice");
        Objects.requireNonNull(directory, "directory");
        Path file = directory.resolve(invoice.id() + ".txt");
        String line = invoice.id() + "|" + invoice.customerId() + "|" + invoice.amount() + "|"
                + invoice.createdAt() + "\n";
        Files.writeString(file, line);
    }
}
 
interface MailSender {
    void sendInvoiceNotice(Invoice invoice);
}
 
final class LoggingMailSender implements MailSender {
    private final String smtpHost;
 
    public LoggingMailSender(String smtpHost) {
        this.smtpHost = Objects.requireNonNull(smtpHost, "smtpHost");
    }
 
    @Override
    public void sendInvoiceNotice(Invoice invoice) {
        System.out.println("EMAIL via " + smtpHost + " to customer " + invoice.customerId()
                + " for invoice " + invoice.id());
    }
}
 
interface InvoiceDocumentRenderer {
    byte[] render(Invoice invoice);
}
 
final class PlainTextInvoiceRenderer implements InvoiceDocumentRenderer {
    @Override
    public byte[] render(Invoice invoice) {
        String text = "Invoice " + invoice.id() + " amount=" + invoice.amount();
        return text.getBytes(StandardCharsets.UTF_8);
    }
}
 
/** Thin façade: orchestrates collaborators without owning their policies. */
public final class InvoiceApplicationService {
 
    private final InvoiceValidator validator = new InvoiceValidator();
    private final InvoiceFactory factory = new InvoiceFactory();
    private final InvoiceFileRepository repository = new InvoiceFileRepository();
    private final MailSender mailSender;
    private final InvoiceDocumentRenderer renderer;
 
    public InvoiceApplicationService(MailSender mailSender, InvoiceDocumentRenderer renderer) {
        this.mailSender = Objects.requireNonNull(mailSender, "mailSender");
        this.renderer = Objects.requireNonNull(renderer, "renderer");
    }
 
    public Invoice issueAndPersist(String customerId, BigDecimal amount, Path directory) throws Exception {
        validator.validateNew(customerId, amount);
        Invoice invoice = factory.newInvoice(customerId, amount);
        repository.save(invoice, directory);
        mailSender.sendInvoiceNotice(invoice);
        return invoice;
    }
 
    public byte[] downloadPdf(Invoice invoice) {
        return renderer.render(invoice);
    }
}

package com.example.solid.srp.spring;
 
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
 
import java.math.BigDecimal;
import java.util.Objects;
 
@RestController
class InvoiceController {
 
    private final InvoiceWorkflowService workflowService;
 
    InvoiceController(InvoiceWorkflowService workflowService) {
        this.workflowService = Objects.requireNonNull(workflowService, "workflowService");
    }
 
    @PostMapping("/api/invoices")
    InvoiceResponse create(@RequestBody CreateInvoiceRequest request) {
        Invoice invoice = workflowService.createInvoice(request.customerId(), request.amount());
        return new InvoiceResponse(invoice.id(), invoice.customerId(), invoice.amount());
    }
 
    public record CreateInvoiceRequest(String customerId, BigDecimal amount) {
    }
 
    public record InvoiceResponse(String id, String customerId, BigDecimal amount) {
    }
}
 
@Service
class InvoiceWorkflowService {
 
    private final InvoiceRepository invoices;
    private final ApplicationEventPublisher events;
 
    InvoiceWorkflowService(InvoiceRepository invoices, ApplicationEventPublisher events) {
        this.invoices = Objects.requireNonNull(invoices, "invoices");
        this.events = Objects.requireNonNull(events, "events");
    }
 
    @Transactional
    public Invoice createInvoice(String customerId, BigDecimal amount) {
        Invoice inv = new Invoice("INV-" + System.nanoTime(), customerId, amount);
        invoices.save(inv);
        events.publishEvent(new InvoiceCreatedEvent(inv.id(), inv.customerId()));
        return inv;
    }
}
 
interface InvoiceRepository {
    void save(Invoice invoice);
}
 
record InvoiceCreatedEvent(String invoiceId, String customerId) {
}
 
record Invoice(String id, String customerId, BigDecimal amount) {
}

package com.example.solid.ocp.bad;
 
import java.math.BigDecimal;
import java.util.Objects;
 
public final class CheckoutService {
 
    public enum PaymentType {
        CARD, PAYPAL, CRYPTO
    }
 
    public String charge(PaymentType type, BigDecimal amount, String accountRef) {
        Objects.requireNonNull(type, "type");
        Objects.requireNonNull(amount, "amount");
        if (amount.signum() <= 0) {
            throw new IllegalArgumentException("amount must be positive");
        }
        return switch (type) {
            case CARD -> {
                System.out.println("Stripe card charge " + amount);
                yield "CARD_OK";
            }
            case PAYPAL -> {
                System.out.println("PayPal charge " + amount);
                yield "PAYPAL_OK";
            }
            case CRYPTO -> {
                System.out.println("Coinbase charge " + amount);
                yield "CRYPTO_OK";
            }
        };
    }
}

package com.example.solid.ocp.good;
 
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Objects;
import java.util.UUID;
 
interface PaymentMethod {
    boolean supports(PaymentContext context);
 
    PaymentResult charge(PaymentContext context);
}
 
record PaymentContext(String customerId, BigDecimal amount, String instrumentHint) {
    public PaymentContext {
        Objects.requireNonNull(customerId, "customerId");
        Objects.requireNonNull(amount, "amount");
        if (amount.signum() <= 0) {
            throw new IllegalArgumentException("amount must be positive");
        }
    }
}
 
record PaymentResult(String processorReference, String auditNote) {
}
 
final class CardPaymentMethod implements PaymentMethod {
    @Override
    public boolean supports(PaymentContext context) {
        return "CARD".equalsIgnoreCase(context.instrumentHint());
    }
 
    @Override
    public PaymentResult charge(PaymentContext context) {
        String ref = "card-" + UUID.randomUUID();
        System.out.println("Stripe card charge " + context.amount());
        return new PaymentResult(ref, "card");
    }
}
 
final class PayPalPaymentMethod implements PaymentMethod {
    @Override
    public boolean supports(PaymentContext context) {
        return "PAYPAL".equalsIgnoreCase(context.instrumentHint());
    }
 
    @Override
    public PaymentResult charge(PaymentContext context) {
        String ref = "paypal-" + UUID.randomUUID();
        System.out.println("PayPal charge " + context.amount());
        return new PaymentResult(ref, "paypal");
    }
}
 
/** New behavior = new class on classpath — no edit to existing methods. */
final class BuyNowPayLaterPaymentMethod implements PaymentMethod {
    @Override
    public boolean supports(PaymentContext context) {
        return "BNPL".equalsIgnoreCase(context.instrumentHint());
    }
 
    @Override
    public PaymentResult charge(PaymentContext context) {
        String ref = "bnpl-" + UUID.randomUUID();
        System.out.println("BNPL schedule for " + context.amount());
        return new PaymentResult(ref, "bnpl");
    }
}
 
/**
 * Composite: ordered chain; first supporting method wins.
 * Could be replaced with Spring's List&lt;PaymentMethod&gt; injection.
 */
final class CompositePaymentMethod implements PaymentMethod {
 
    private final List<PaymentMethod> delegates;
 
    public CompositePaymentMethod(List<PaymentMethod> delegates) {
        this.delegates = List.copyOf(Objects.requireNonNull(delegates, "delegates"));
    }
 
    @Override
    public boolean supports(PaymentContext context) {
        return delegates.stream().anyMatch(d -> d.supports(context));
    }
 
    @Override
    public PaymentResult charge(PaymentContext context) {
        return delegates.stream()
                .filter(d -> d.supports(context))
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("No payment method for context"))
                .charge(context);
    }
}
 
public final class CheckoutService {
 
    private final PaymentMethod paymentMethod;
 
    public CheckoutService(PaymentMethod paymentMethod) {
        this.paymentMethod = Objects.requireNonNull(paymentMethod, "paymentMethod");
    }
 
    public PaymentResult checkout(PaymentContext context) {
        if (!paymentMethod.supports(context)) {
            throw new IllegalArgumentException("Unsupported payment context");
        }
        return paymentMethod.charge(context);
    }
 
    public static void demo() {
        List<PaymentMethod> chain = new ArrayList<>();
        chain.add(new CardPaymentMethod());
        chain.add(new PayPalPaymentMethod());
        chain.add(new BuyNowPayLaterPaymentMethod());
        CheckoutService service = new CheckoutService(new CompositePaymentMethod(chain));
        service.checkout(new PaymentContext("cust-1", new BigDecimal("42.00"), "BNPL"));
    }
}

package com.example.solid.ocp.spring;
 
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
@Configuration
public class PaymentAutoConfiguration {
 
    @Bean
    @ConditionalOnProperty(name = "payments.provider", havingValue = "stripe")
    PaymentGateway stripeGateway() {
        return new StripePaymentGateway();
    }
 
    @Bean
    @ConditionalOnProperty(name = "payments.provider", havingValue = "paypal")
    PaymentGateway paypalGateway() {
        return new PayPalPaymentGateway();
    }
}
 
interface PaymentGateway {
    String charge(String customerId, String amount);
}
 
final class StripePaymentGateway implements PaymentGateway {
    @Override
    public String charge(String customerId, String amount) {
        return "stripe:" + customerId + ":" + amount;
    }
}
 
final class PayPalPaymentGateway implements PaymentGateway {
    @Override
    public String charge(String customerId, String amount) {
        return "paypal:" + customerId + ":" + amount;
    }
}

r.setWidth(5);
r.setHeight(4);
assert r.area() == 20;

package com.example.solid.lsp.bad;
 
import java.util.Objects;
 
class Rectangle {
 
    protected int width;
    protected int height;
 
    public void setWidth(int width) {
        if (width <= 0) {
            throw new IllegalArgumentException("width must be positive");
        }
        this.width = width;
    }
 
    public void setHeight(int height) {
        if (height <= 0) {
            throw new IllegalArgumentException("height must be positive");
        }
        this.height = height;
    }
 
    public int area() {
        return width * height;
    }
}
 
final class Square extends Rectangle {
 
    @Override
    public void setWidth(int width) {
        super.setWidth(width);
        super.setHeight(width);
    }
 
    @Override
    public void setHeight(int height) {
        super.setHeight(height);
        super.setWidth(height);
    }
}

package com.example.solid.lsp.good;
 
import java.util.Objects;
 
sealed interface Shape permits Rectangle, Square {
    int area();
}
 
final class Rectangle implements Shape {
 
    private final int width;
    private final int height;
 
    public Rectangle(int width, int height) {
        if (width <= 0 || height <= 0) {
            throw new IllegalArgumentException("dimensions must be positive");
        }
        this.width = width;
        this.height = height;
    }
 
    @Override
    public int area() {
        return width * height;
    }
 
    public int width() {
        return width;
    }
 
    public int height() {
        return height;
    }
}
 
final class Square implements Shape {
 
    private final int side;
 
    public Square(int side) {
        if (side <= 0) {
            throw new IllegalArgumentException("side must be positive");
        }
        this.side = side;
    }
 
    @Override
    public int area() {
        return side * side;
    }
 
    public int side() {
        return side;
    }
}

package com.example.solid.lsp.collections;
 
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
 
/**
 * Pretends to be a full List but rejects mutation — LSP landmine for API expecting List contract.
 */
public final class ReadOnlyList<T> extends ArrayList<T> {
 
    @Override
    public boolean add(T t) {
        throw new UnsupportedOperationException("read-only");
    }
 
    @Override
    public boolean addAll(Collection<? extends T> c) {
        throw new UnsupportedOperationException("read-only");
    }
}

package com.example.solid.isp.bad;
 
import java.nio.file.Path;
 
interface OfficeMachine {
 
    void print(String document);
 
    void scanToPdf(Path output);
 
    void fax(String number, String document);
 
    void staple(int pages);
}
 
final class SimplePrinter implements OfficeMachine {
    @Override
    public void print(String document) {
        System.out.println("PRINT " + document);
    }
 
    @Override
    public void scanToPdf(Path output) {
        throw new UnsupportedOperationException("no scanner");
    }
 
    @Override
    public void fax(String number, String document) {
        throw new UnsupportedOperationException("no fax");
    }
 
    @Override
    public void staple(int pages) {
        throw new UnsupportedOperationException("no stapler");
    }
}

package com.example.solid.isp.good;
 
import java.nio.file.Path;
 
interface Printable {
    void print(String document);
}
 
interface Scannable {
    void scanToPdf(Path output);
}
 
interface Faxable {
    void fax(String number, String document);
}
 
interface Stapling {
    void staple(int pages);
}
 
final class SimplePrinter implements Printable {
    @Override
    public void print(String document) {
        System.out.println("PRINT " + document);
    }
}
 
final class MfpDevice implements Printable, Scannable, Faxable, Stapling {
    @Override
    public void print(String document) {
        System.out.println("PRINT " + document);
    }
 
    @Override
    public void scanToPdf(Path output) {
        System.out.println("SCAN -> " + output);
    }
 
    @Override
    public void fax(String number, String document) {
        System.out.println("FAX " + number + " " + document);
    }
 
    @Override
    public void staple(int pages) {
        System.out.println("STAPLE " + pages);
    }
}

package com.example.solid.isp.badrepo;
 
import java.util.List;
import java.util.Optional;
 
interface MegaCustomerRepository {
 
    void save(Customer c);
 
    Optional<Customer> findById(String id);
 
    List<Customer> searchByName(String q);
 
    byte[] exportCsv();
 
    void refreshWarehouse();
 
    void runMonthlyReport();
}
 
final class CustomerService {
 
    private final MegaCustomerRepository repo;
 
    public CustomerService(MegaCustomerRepository repo) {
        this.repo = repo;
    }
 
    public Customer register(Customer c) {
        repo.save(c);
        return c;
    }
}

package com.example.solid.isp.goodrepo;
 
import java.util.List;
import java.util.Optional;
 
record Customer(String id, String name) {
}
 
interface CustomerWriteRepository {
    void save(Customer c);
}
 
interface CustomerReadRepository {
    Optional<Customer> findById(String id);
}
 
interface CustomerSearchRepository {
    List<Customer> searchByName(String q);
}
 
interface CustomerReportingRepository {
    byte[] exportCsv();
}
 
interface CustomerWarehouseSync {
    void refreshWarehouse();
}
 
final class CustomerService {
 
    private final CustomerWriteRepository writes;
    private final CustomerReadRepository reads;
 
    public CustomerService(CustomerWriteRepository writes, CustomerReadRepository reads) {
        this.writes = writes;
        this.reads = reads;
    }
 
    public Customer register(Customer c) {
        writes.save(c);
        return reads.findById(c.id()).orElseThrow();
    }
}

package com.example.solid.dip.bad;
 
import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.util.Objects;
 
public final class OrderCheckoutService {
 
    public void checkout(String orderId, BigDecimal amount, String customerEmail) throws Exception {
        Objects.requireNonNull(orderId, "orderId");
        Objects.requireNonNull(amount, "amount");
        try (Connection c = DriverManager.getConnection("jdbc:mysql://localhost/demo", "u", "p")) {
            PreparedStatement ps = c.prepareStatement("INSERT INTO payments(order_id, amount) VALUES (?,?)");
            ps.setString(1, orderId);
            ps.setBigDecimal(2, amount);
            ps.executeUpdate();
        }
        System.out.println("Stripe charge " + amount);
        System.out.println("SMTP to " + customerEmail);
    }
}

package com.example.solid.dip.good;
 
import java.math.BigDecimal;
import java.util.Objects;
 
interface PaymentLedger {
    void recordPayment(String orderId, BigDecimal amount);
}
 
interface PaymentGateway {
    String charge(BigDecimal amount, String orderId);
}
 
interface CustomerNotifier {
    void notifyPaymentReceived(String customerEmail, String orderId);
}
 
public final class OrderCheckoutService {
 
    private final PaymentLedger ledger;
    private final PaymentGateway gateway;
    private final CustomerNotifier notifier;
 
    public OrderCheckoutService(PaymentLedger ledger, PaymentGateway gateway, CustomerNotifier notifier) {
        this.ledger = Objects.requireNonNull(ledger, "ledger");
        this.gateway = Objects.requireNonNull(gateway, "gateway");
        this.notifier = Objects.requireNonNull(notifier, "notifier");
    }
 
    public void checkout(String orderId, BigDecimal amount, String customerEmail) {
        gateway.charge(amount, orderId);
        ledger.recordPayment(orderId, amount);
        notifier.notifyPaymentReceived(customerEmail, orderId);
    }
}
 
final class InMemoryPaymentLedger implements PaymentLedger {
    @Override
    public void recordPayment(String orderId, BigDecimal amount) {
        System.out.println("LEDGER " + orderId + " " + amount);
    }
}
 
final class FakePaymentGateway implements PaymentGateway {
    @Override
    public String charge(BigDecimal amount, String orderId) {
        return "fake-charge-" + orderId + "-" + amount;
    }
}
 
final class LoggingCustomerNotifier implements CustomerNotifier {
    @Override
    public void notifyPaymentReceived(String customerEmail, String orderId) {
        System.out.println("NOTIFY " + customerEmail + " for " + orderId);
    }
}

package com.example.solid.dip.springdemo;
 
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.stereotype.Service;
 
import java.math.BigDecimal;
import java.util.Objects;
 
interface PaymentGateway {
    String charge(BigDecimal amount);
}
 
@Service
class CheckoutAppService {
 
    private final PaymentGateway gateway;
 
    CheckoutAppService(@Qualifier("primaryGateway") PaymentGateway gateway) {
        this.gateway = Objects.requireNonNull(gateway, "gateway");
    }
 
    public String pay(BigDecimal amount) {
        return gateway.charge(amount);
    }
}
 
@Configuration
class PaymentsConfig {
 
    @Bean(name = "primaryGateway")
    @Profile("prod")
    PaymentGateway stripeGateway() {
        return amount -> "stripe:" + amount;
    }
 
    @Bean(name = "primaryGateway")
    @Profile("!prod")
    PaymentGateway fakeGateway() {
        return amount -> "fake:" + amount;
    }
}

package com.example.solid.dip.test;
 
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
 
import java.math.BigDecimal;
 
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
 
public class CheckoutMockTest {
 
    interface PaymentGateway {
        String charge(BigDecimal amount);
    }
 
    static final class Checkout {
        private final PaymentGateway gateway;
 
        Checkout(PaymentGateway gateway) {
            this.gateway = gateway;
        }
 
        String pay(BigDecimal amount) {
            return gateway.charge(amount);
        }
    }
 
    @Test
    void usesInjectedDouble() {
        PaymentGateway gw = Mockito.mock(PaymentGateway.class);
        when(gw.charge(any())).thenReturn("ok");
        Checkout c = new Checkout(gw);
        org.junit.jupiter.api.Assertions.assertEquals("ok", c.pay(new BigDecimal("9.99")));
        verify(gw).charge(new BigDecimal("9.99"));
    }
}