Design and Implementation of an Extension‑Point Mechanism for SaaS Multi‑Tenant Business Differentiation

In SaaS multi‑tenant systems, business differentiation (e.g., different pricing rules or order validation per tenant) quickly leads to tangled if‑else code or an exploding inheritance hierarchy.

What is an Extension Point

The mechanism consists of three steps: (1) abstract the varying logic into an interface called an ExtensionPoint; (2) each tenant provides its own implementation, called an Extension; (3) at runtime the framework routes calls to the appropriate implementation based on a business code (bizCode).

Business code depends only on the ExtensionPoint interface, not on concrete classes. Adding a new tenant only requires adding a class annotated with @Extension.

Declaring an Extension Point

public interface ExtensionPoint {}

public interface PriceCalcExtPt extends ExtensionPoint {
    BigDecimal calculate(Order order);
}

The interface name must end with "ExtPt" so the framework can recognise it, similar to Spring’s @Service/@Repository naming convention.

Implementing Extensions

@Extension
public class DefaultPriceCalcExt implements PriceCalcExtPt {
    @Override
    public BigDecimal calculate(Order order) {
        return order.getUnitPrice().multiply(BigDecimal.valueOf(order.getQuantity()));
    }
}

@Extension(bizCode = "ali.taobao.supermarket")
public class TaobaoSupermarketPriceCalcExt implements PriceCalcExtPt {
    @Override
    public BigDecimal calculate(Order order) {
        // supermarket uses tiered pricing
        return stepPriceCalculate(order);
    }
}

@Extension(bizCode = "ali.taobao")
public class TaobaoPriceCalcExt implements PriceCalcExtPt {
    @Override
    public BigDecimal calculate(Order order) {
        // Taobao uses full‑reduction discount
        return discountCalculate(order);
    }
}

If no bizCode is specified, the class serves as the default implementation.

bizCode Hierarchical Routing

ExtensionExecutor locates the correct Extension by first trying an exact match of the bizCode, then progressively stripping the last segment after a dot and retrying, finally falling back to the default implementation. If none is found, a BizException is thrown.

protected <Ext> Ext locateExtension(Class<Ext> targetClz, Context context) {
    String bizCode = context.getBizCode();
    // exact match
    Extension extension = firstTry(targetClz, bizCode);
    if (extension != null) return extension;
    // hierarchical fallback
    extension = loopTry(targetClz, bizCode);
    if (extension != null) return extension;
    // default
    extension = tryDefault(targetClz);
    if (extension != null) return extension;
    throw new BizException("找不到扩展实现");
}

The loopTry method repeatedly removes the trailing segment after the last dot and looks up the remaining prefix, enabling a tenant‑wide implementation (e.g., "ali") to be automatically used by all its sub‑tenants unless they provide a more specific Extension.

This routing mirrors Java’s ClassLoader delegation model but in reverse order: the most specific implementation wins.

ExtensionRepository: Registration and Conflict Prevention

All Extensions are registered at application startup into an ExtensionRepository, which stores them in a Map<ExtensionCoordinate, ExtensionPoint>. The key combines the fully‑qualified ExtensionPoint interface name and the bizCode. Duplicate registrations for the same key cause a startup‑time BizException, preventing runtime ambiguity.

private Map<ExtensionCoordinate, ExtensionPoint> extensionRepo = new HashMap<>();

ExtensionPoint preVal = extensionRepository.getExtensionRepo()
    .put(extensionCoordinate, extension);
if (preVal != null) {
    throw new BizException("Duplicate registration: " + extensionCoordinate);
}

The repository uses a plain HashMap because registration occurs in a single‑threaded bootstrap phase; after that only read operations are performed, so no concurrent map is needed.

Bootstrap: Annotation‑Driven Automatic Registration

During the bootstrap phase, the framework scans configured packages, finds classes annotated with @Extension, extracts the bizCode, determines the associated ExtPt interface, builds an ExtensionCoordinate, and registers the pair in the repository.

public class Bootstrap {
    private List<String> packages;
    private RegisterFactory registerFactory;

    public void init() {
        Set<Class<?>> classSet = scanConfiguredPackages();
        registerBeans(classSet);
    }

    private void registerBeans(Set<Class<?>> classSet) {
        for (Class<?> targetClz : classSet) {
            RegisterI register = registerFactory.getRegister(targetClz);
            if (register != null) {
                register.doRegistration(targetClz);
            }
        }
    }
}

Business developers only need to add @Extension on their classes; no additional configuration is required.

Using the Extension in Business Code

@Service
@RequiredArgsConstructor
public class OrderService {
    private final ExtensionExecutor extensionExecutor;

    public Response createOrder(CreateOrderCmd cmd) {
        // bizCode is taken from the current context
        BigDecimal price = extensionExecutor.execute(
                PriceCalcExtPt.class,
                cmd.getContext(),
                ext -> ext.calculate(order)
        );
        // further processing …
    }
}

The service depends solely on the PriceCalcExtPt interface; adding a new tenant only means adding a new @Extension class.

Conclusion

The Extension‑Point mechanism isolates tenant‑specific logic in SaaS systems without exploding inheritance trees or tangled conditional statements. By declaring variation points as interfaces, providing per‑tenant implementations, and routing based on a hierarchical bizCode, the design achieves clean separation, automatic fallback, and early conflict detection.

The approach yields a clear ROI: the more tenants and the more complex their individual rules, the greater the maintenance benefit. For a small number of simple tenants the overhead may be unnecessary, but once the tenant count exceeds ten with distinct business rules, the mechanism dramatically improves code maintainability.