SOLID Principles for Backend Engineers

// BAD: OrderProcessor has at least four reasons to change —
// order validation rules, persistence technology, payment provider,
// and notification channel are all tangled together.
public class OrderProcessor {
 
    private final DataSource dataSource;
    private final HttpClient paymentHttpClient;
 
    public OrderProcessor(DataSource dataSource, HttpClient paymentHttpClient) {
        this.dataSource = dataSource;
        this.paymentHttpClient = paymentHttpClient;
    }
 
    public void processOrder(OrderRequest request) throws SQLException {
        // 1. Validation logic
        if (request.getItems().isEmpty()) {
            throw new IllegalArgumentException("Order must have at least one item");
        }
        if (request.getCustomerId() == null) {
            throw new IllegalArgumentException("Customer ID required");
        }
 
        // 2. Price calculation
        BigDecimal total = BigDecimal.ZERO;
        for (LineItem item : request.getItems()) {
            total = total.add(item.getPrice().multiply(BigDecimal.valueOf(item.getQuantity())));
        }
 
        // 3. Direct JDBC persistence
        try (Connection conn = dataSource.getConnection()) {
            PreparedStatement stmt = conn.prepareStatement(
                "INSERT INTO orders (customer_id, total, status) VALUES (?, ?, ?)");
            stmt.setString(1, request.getCustomerId());
            stmt.setBigDecimal(2, total);
            stmt.setString(3, "PENDING");
            stmt.executeUpdate();
        }
 
        // 4. Raw HTTP call to payment provider
        String json = "{\"amount\":" + total + ",\"customer\":\"" + request.getCustomerId() + "\"}";
        HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://api.stripe.com/v1/charges"))
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        // ... send, parse response, retry on failure ...
 
        // 5. Email sending, inline
        String emailBody = "Your order for $" + total + " has been placed.";
        // ... SMTP client call ...
    }
}

public class OrderValidator {
    public void validate(OrderRequest request) {
        if (request.getItems().isEmpty()) {
            throw new InvalidOrderException("Order must have at least one item");
        }
        if (request.getCustomerId() == null) {
            throw new InvalidOrderException("Customer ID required");
        }
    }
}
 
public class OrderPricingService {
    public Money calculateTotal(List<LineItem> items) {
        return items.stream()
            .map(item -> item.getPrice().multiply(item.getQuantity()))
            .reduce(Money.ZERO, Money::add);
    }
}
 
public interface OrderRepository {
    Order save(Order order);
}
 
public class JdbcOrderRepository implements OrderRepository {
    private final DataSource dataSource;
    // JDBC-specific persistence only — changes only when schema/storage changes
    public JdbcOrderRepository(DataSource dataSource) { this.dataSource = dataSource; }
 
    @Override
    public Order save(Order order) { /* JDBC insert */ return order; }
}
 
// The orchestrator has exactly one reason to change: the order placement workflow itself
public class OrderService {
    private final OrderValidator validator;
    private final OrderPricingService pricingService;
    private final OrderRepository orderRepository;
    private final PaymentGateway paymentGateway;
    private final NotificationService notificationService;
 
    public OrderService(OrderValidator validator, OrderPricingService pricingService,
                         OrderRepository orderRepository, PaymentGateway paymentGateway,
                         NotificationService notificationService) {
        this.validator = validator;
        this.pricingService = pricingService;
        this.orderRepository = orderRepository;
        this.paymentGateway = paymentGateway;
        this.notificationService = notificationService;
    }
 
    public Receipt placeOrder(OrderRequest request) {
        validator.validate(request);
        Money total = pricingService.calculateTotal(request.getItems());
        Order order = orderRepository.save(Order.pending(request, total));
        PaymentResult payment = paymentGateway.charge(order.toPaymentRequest());
        notificationService.notifyOrderPlaced(order);
        return new Receipt(order, payment);
    }
}

// BAD: every new coupon type requires editing this method and re-testing
// every existing coupon type along with it.
public class CouponService {
 
    public Money applyDiscount(Order order, Coupon coupon) {
        if (coupon.getType() == CouponType.PERCENTAGE) {
            BigDecimal rate = coupon.getValue().divide(BigDecimal.valueOf(100));
            return order.getTotal().multiply(BigDecimal.ONE.subtract(rate));
        } else if (coupon.getType() == CouponType.FLAT) {
            return order.getTotal().subtract(Money.of(coupon.getValue()));
        } else if (coupon.getType() == CouponType.FREE_SHIPPING) {
            return order.getTotal().subtract(order.getShippingCost());
        } else if (coupon.getType() == CouponType.BUY_ONE_GET_ONE) {
            // added six months later, by someone who didn't read the first three branches
            return applyBogoDiscount(order);
        }
        throw new IllegalArgumentException("Unknown coupon type: " + coupon.getType());
    }
}

public interface DiscountStrategy {
    Money apply(Order order);
}
 
public class PercentageDiscount implements DiscountStrategy {
    private final BigDecimal percentage;
    public PercentageDiscount(BigDecimal percentage) { this.percentage = percentage; }
 
    @Override
    public Money apply(Order order) {
        BigDecimal rate = percentage.divide(BigDecimal.valueOf(100));
        return order.getTotal().multiply(BigDecimal.ONE.subtract(rate));
    }
}
 
public class FlatAmountDiscount implements DiscountStrategy {
    private final Money amount;
    public FlatAmountDiscount(Money amount) { this.amount = amount; }
 
    @Override
    public Money apply(Order order) {
        return order.getTotal().subtract(amount).max(Money.ZERO);
    }
}
 
public class FreeShippingDiscount implements DiscountStrategy {
    @Override
    public Money apply(Order order) {
        return order.getTotal().subtract(order.getShippingCost());
    }
}
 
// Adding BuyOneGetOneDiscount later touches zero existing files.
public class BuyOneGetOneDiscount implements DiscountStrategy {
    @Override
    public Money apply(Order order) { /* new logic, isolated and independently testable */ return order.getTotal(); }
}
 
public class CouponService {
    public Money applyDiscount(Order order, DiscountStrategy strategy) {
        return strategy.apply(order);
    }
}

public interface InventoryRepository {
    Optional<InventoryRecord> findBySku(String sku);
    void reserve(String sku, int quantity);
    void release(String sku, int quantity);
}
 
// BAD: a "read-only" implementation that silently breaks the contract.
// Every caller of reserve()/release() now has to know, out of band,
// that this particular implementation will blow up.
public class ReadOnlyInventoryRepository implements InventoryRepository {
 
    @Override
    public Optional<InventoryRecord> findBySku(String sku) {
        return queryReplica(sku);
    }
 
    @Override
    public void reserve(String sku, int quantity) {
        throw new UnsupportedOperationException("Read replica cannot reserve stock");
    }
 
    @Override
    public void release(String sku, int quantity) {
        throw new UnsupportedOperationException("Read replica cannot release stock");
    }
}

// Any code written against the interface is now unsafe to call generically:
public void checkout(InventoryRepository repo, String sku, int qty) {
    repo.reserve(sku, qty);  // works for JdbcInventoryRepository,
                              // throws for ReadOnlyInventoryRepository
}

public interface InventoryReader {
    Optional<InventoryRecord> findBySku(String sku);
}
 
public interface InventoryWriter {
    void reserve(String sku, int quantity);
    void release(String sku, int quantity);
}
 
public interface InventoryRepository extends InventoryReader, InventoryWriter {}
 
// Now this class only claims to implement what it can actually honor.
public class ReadOnlyInventoryRepository implements InventoryReader {
    @Override
    public Optional<InventoryRecord> findBySku(String sku) {
        return queryReplica(sku);
    }
}
 
// Checkout code depends only on the capability it needs, and the
// compiler guarantees every implementation can actually reserve stock.
public void checkout(InventoryWriter writer, String sku, int qty) {
    writer.reserve(sku, qty);
}

public class Payment {
    protected final Money amount;
    protected Payment(Money amount) { this.amount = amount; }
 
    // Base contract: accepts any positive amount
    public void process() {
        if (amount.isNegative() || amount.isZero()) {
            throw new IllegalArgumentException("Amount must be positive");
        }
        doCharge();
    }
 
    protected void doCharge() { /* ... */ }
}
 
// BAD: silently strengthens the precondition the base class advertised.
// Callers who successfully process $5 payments via other Payment subtypes
// will get surprised by this one rejecting amounts under $50.
public class WireTransferPayment extends Payment {
    public WireTransferPayment(Money amount) { super(amount); }
 
    @Override
    public void process() {
        if (amount.isLessThan(Money.of(50))) {
            throw new IllegalArgumentException("Wire transfers require a $50 minimum");
        }
        super.process();
    }
}

// BAD: a single fat interface for every kind of outbound notification.
public interface NotificationService {
    void sendEmail(String to, String subject, String body);
    void sendSms(String phoneNumber, String message);
    void sendPushNotification(String deviceToken, String title, String body);
    void sendWebhook(String url, String payload);
    void sendSlackMessage(String channel, String message);
}
 
// A team building a lightweight order-confirmation feature only needs email,
// but must implement (or stub) all five methods to satisfy the interface.
public class SimpleEmailNotifier implements NotificationService {
    @Override
    public void sendEmail(String to, String subject, String body) { /* real */ }
 
    @Override
    public void sendSms(String phoneNumber, String message) {
        throw new UnsupportedOperationException(); // forced stub
    }
 
    @Override
    public void sendPushNotification(String deviceToken, String title, String body) {
        throw new UnsupportedOperationException(); // forced stub
    }
 
    @Override
    public void sendWebhook(String url, String payload) {
        throw new UnsupportedOperationException(); // forced stub
    }
 
    @Override
    public void sendSlackMessage(String channel, String message) {
        throw new UnsupportedOperationException(); // forced stub
    }
}

public interface EmailSender {
    void send(String to, String subject, String body);
}
 
public interface SmsSender {
    void send(String phoneNumber, String message);
}
 
public interface PushSender {
    void send(String deviceToken, String title, String body);
}
 
// Implementers depend only on what they actually do.
public class SimpleEmailNotifier implements EmailSender {
    @Override
    public void send(String to, String subject, String body) { /* real, complete implementation */ }
}
 
// A fan-out orchestrator composes the narrow interfaces it needs —
// it depends on abstractions, and each is fully honored by its implementer.
public class OrderNotificationOrchestrator {
    private final EmailSender emailSender;
    private final PushSender pushSender;
 
    public OrderNotificationOrchestrator(EmailSender emailSender, PushSender pushSender) {
        this.emailSender = emailSender;
        this.pushSender = pushSender;
    }
 
    public void notifyOrderConfirmed(Customer customer, Order order) {
        emailSender.send(customer.getEmail(), "Order Confirmed", renderEmail(order));
        if (customer.hasPushEnabled()) {
            pushSender.send(customer.getDeviceToken(), "Order Confirmed", renderPush(order));
        }
    }
}

// BAD: OrderService (high-level business logic) directly instantiates and
// depends on RazorpayClient (low-level infrastructure detail).
public class OrderService {
    private final RazorpayClient razorpayClient = new RazorpayClient("live_key_xxx");
 
    public Receipt checkout(Order order) {
        RazorpayChargeRequest request = new RazorpayChargeRequest(order.getTotal().toPaise());
        RazorpayChargeResponse response = razorpayClient.charge(request);
        return new Receipt(order, response.getTransactionId());
    }
}

// The abstraction both layers depend on. Owned by the domain, not by any vendor SDK.
public interface PaymentGateway {
    PaymentResult charge(PaymentRequest request);
}
 
// Low-level detail — depends on (implements) the abstraction, not the other way around.
public class RazorpayPaymentGateway implements PaymentGateway {
    private final RazorpayClient client;
 
    public RazorpayPaymentGateway(RazorpayClient client) { this.client = client; }
 
    @Override
    public PaymentResult charge(PaymentRequest request) {
        RazorpayChargeResponse response = client.charge(toRazorpayRequest(request));
        return PaymentResult.success(response.getTransactionId());
    }
}
 
// High-level module depends only on the abstraction.
public class OrderService {
    private final PaymentGateway paymentGateway;
 
    public OrderService(PaymentGateway paymentGateway) {  // injected, not constructed
        this.paymentGateway = paymentGateway;
    }
 
    public Receipt checkout(Order order) {
        PaymentResult result = paymentGateway.charge(order.toPaymentRequest());
        return new Receipt(order, result.getTransactionId());
    }
}

// Spring wires the concrete implementation at startup — OrderService never knows.
@Configuration
public class PaymentConfig {
    @Bean
    public PaymentGateway paymentGateway(RazorpayClient client) {
        return new RazorpayPaymentGateway(client);
    }
}
 
// Testing OrderService is now trivial — no HTTP, no live credentials.
@Test
void checkoutChargesThePaymentGateway() {
    PaymentGateway fakeGateway = request -> PaymentResult.success("txn_test_123");
    OrderService service = new OrderService(fakeGateway);
 
    Receipt receipt = service.checkout(sampleOrder());
 
    assertThat(receipt.getTransactionId()).isEqualTo("txn_test_123");
}