fflib Foundations: Apex Enterprise Patterns

Source of truth for every signature below: apex-enterprise-patterns/fflib-apex-common @ master commit dab5977 (sfdx-source/apex-common/main/classes/*.cls), fflib-apex-mocks @ master commit d81e9e1, fflib-apex-common-samplecode @ master commit 4657d63. Anything not read from those files this session is marked [unverified].

When to use

Decision table: does fflib earn its keep here?

Two or more "plain" answers means do not adopt fflib. The library costs roughly 3 extra files per SObject (interface, implementation, mock registration) and a permanent onboarding tax. See references/fflib-vs-plain-apex.md for the same requirement implemented both ways.

Core patterns

1. The four layers and the dependency rules

Entry points        triggers, LWC @AuraEnabled controllers, REST resources,
                    Batchable/Queueable, InvocableMethod
      |  (only calls)
Service layer       coarse-grained, bulkified, transaction boundary, owns the UnitOfWork
      |
Domain layer        record-oriented behaviour + validation for one SObjectType
      |
Selector layer      all SOQL
      |
Unit of Work        all DML, ordered by SObjectType dependency

Enforceable rules, in priority order:

2. Application.cls is the only wiring file

One class per package, four static finals. Verified shape from fflib-apex-common-samplecode/.../main/classes/Application.cls:

public class Application {
    // SObjectTypes in dependency order: parents before children.
    public static final fflib_Application.UnitOfWorkFactory UnitOfWork =
        new fflib_Application.UnitOfWorkFactory(
            new List<SObjectType> {
                Account.SObjectType,
                Opportunity.SObjectType,
                OpportunityLineItem.SObjectType,
                Invoice__c.SObjectType,
                InvoiceLine__c.SObjectType });

    // Interface -> implementing class.
    public static final fflib_Application.ServiceFactory Service =
        new fflib_Application.ServiceFactory(
            new Map<Type, Type> {
                IAccountsService.class => AccountsServiceImpl.class,
                IOpportunitiesService.class => OpportunitiesServiceImpl.class });

    // SObjectType -> selector class.
    public static final fflib_Application.SelectorFactory Selector =
        new fflib_Application.SelectorFactory(
            new Map<SObjectType, Type> {
                Account.SObjectType => AccountsSelector.class,
                Opportunity.SObjectType => OpportunitiesSelector.class });

    // SObjectType -> domain constructor class.
    public static final fflib_Application.DomainFactory Domain =
        new fflib_Application.DomainFactory(
            Application.Selector,
            new Map<SObjectType, Type> {
                Account.SObjectType => Accounts.Constructor.class,
                Opportunity.SObjectType => Opportunities.Constructor.class });
}

newInstance resolves the registered Type and calls Type.newInstance(), so every registered class needs a public zero-argument constructor. Unregistered lookups throw fflib_Application.DeveloperException with No implementation registered for service interface X or Selector class not found for SObjectType X (fflib_Application.cls). Full binding tables, the UserModeDML factory subclass and the common wiring mistakes are in references/application-factory.md.

3. Naming and file layout

The samplecode conventions, verified against its class paths:

The service layer is three files: a with sharing static facade (AccountsService), the interface (IAccountsService), and the implementation (AccountsServiceImpl). The facade exists so callers keep static call syntax while the factory still controls instantiation:

public with sharing class AccountsService {
    public static void updateOpportunityActivity(Set<Id> accountIds) {
        service().updateOpportunityActivity(accountIds);
    }
    private static IAccountsService service() {
        return (IAccountsService) Application.Service.newInstance(IAccountsService.class);
    }
}

Directory layout inside a package directory (samplecode uses exactly these folder names):

force-app/main/default/classes/
  Application.cls
  service/      AccountsService.cls  IAccountsService.cls  AccountsServiceImpl.cls
  domains/      Accounts.cls         IAccounts.cls
  selectors/    AccountsSelector.cls IAccountsSelector.cls
  triggerHandlers/ AccountsTriggerHandler.cls
  controllers/  batchjobs/  restapis/

4. Installation: vendor, submodule, or deploy

fflib-apex-common @ master publishes no unlocked-package version id and no GitHub release; the repo has zero releases and its README advertises only a GitHub-deploy button. Any 04t... install id for these libraries is [unverified] - do not put one in a script.

# Option A (recommended): vendor into a dedicated package directory, pinned to a commit.
git clone https://github.com/apex-enterprise-patterns/fflib-apex-mocks.git /tmp/fflib-mocks
git -C /tmp/fflib-mocks checkout d81e9e1
mkdir -p fflib/main/default
cp -R /tmp/fflib-mocks/sfdx-source/apex-mocks/main/classes fflib/main/default/classes
# then fflib-apex-common on top of the same directory

# Deploy order matters only if your own tests reference ApexMocks: mocks first, then common.
sf project deploy start --source-dir fflib --target-org vf-dev --wait 20

fflib-apex-common's current README states "Dependencies: None for deployment or for running this library's Apex tests"; its docs/changelog.md still carries the September 2014 note that ApexMocks "must be deployed to the org before deploying this library". The README reflects master - deploy mocks first anyway, it is free and removes the ambiguity. Submodule and upgrade procedures: references/install-and-layout.md. Packaging consequences: skills sf-project-structure and sf-packaging-release.

5. Mock injection points

setMock on every factory is protected and @TestVisible, so it compiles only from test context (fflib_Application.cls).

The single-argument selector and domain overloads call sObjectType() on the mock; if it is not stubbed the mock returns null and registration silently binds to null. fflib logs an INFO System.debug in that path. Prefer the two-argument overload. Detail: skill sf-fflib-testing.

6. Incremental migration from legacy Apex (strangler)

Keep the legacy class as a thin delegator until every caller is migrated, then delete it in the same release; do not leave two ways to do the same thing. Never mix a legacy [SELECT ...] and a selector for the same SObject in one class.

7. Static analysis and performance characteristics

fflib's own source suppresses PMD rules (fflib_SObjectSelector.cls header suppresses PMD.CyclomaticComplexity, PMD.ExcessivePublicCount, PMD.ApexDoc and more), so the library deploys clean only if your analyzer run excludes vendored paths. In your own fflib code expect:

Exclude the vendored fflib/ directory from the Code Analyzer target; see skill sf-code-analyzer-quality. Governor cost of the factories: each Type.newInstance() is a reflective instantiation (no limit consumed, small CPU cost); fflib_SObjectDescribe caches describes per transaction, so a selector's first getSObjectFieldList() pays describe cost once. The real risks are getSObjectFieldList() bloat (heap) and per-record selector calls (SOQL 100 limit) - skills sf-governor-limits and sf-soql-sosl-optimization.

Anti-patterns

new AccountsServiceImpl() in product code. Bypasses Application.Service, so setMock cannot intervene and every consumer test needs DML.

// Wrong
IAccountsService svc = new AccountsServiceImpl();
// Right
IAccountsService svc = (IAccountsService) Application.Service.newInstance(IAccountsService.class);

Unit of Work SObjectType list in the wrong order. fflib_SObjectUnitOfWork commits in the order given; children before parents produces REQUIRED_FIELD_MISSING on the lookup at commit time. List Account before Opportunity before OpportunityLineItem.

One Application per feature. Two factories means two registries and two mock registries; setMock on one is invisible to the other. One Application class per package directory.

Service method taking a single record. updateOne(Id accountId) guarantees a governor failure when a trigger calls it per record. Take Set<Id> / List<SObject>.

Domain class issuing SOQL. Makes the domain untestable without DML and hides query cost inside record loops. Query in the service, pass records down.

Registering the domain class instead of its constructor. Account.SObjectType => Accounts.class fails at runtime unless Accounts itself implements a constructor interface; the samplecode registers Accounts.Constructor.class. See references/application-factory.md.

Verification

# 1. Local gate: format, lint, analyzer, jest. No org needed.
node "${CLAUDE_PLUGIN_ROOT}/scripts/checks/vf-check.mjs" local --changed

# 2. Compile + run the fflib-facing tests in an org.
sf project deploy start --source-dir force-app --target-org vf-dev --wait 30
sf apex run test --target-org vf-dev --synchronous \
  --tests AccountsServiceTest --tests AccountsSelectorTest \
  --code-coverage --result-format human

# 3. Prove the factories resolve every registration (fails fast on a missing binding).
sf apex run --target-org vf-dev --file scripts/apex/assert-application-wiring.apex

# 4. Coverage + analyzer gates (apexOrgCoverageMin 85, apexClassCoverageMin 75, severity 3).
node "${CLAUDE_PLUGIN_ROOT}/scripts/checks/vf-check.mjs" apex --target-org vf-dev
node "${CLAUDE_PLUGIN_ROOT}/scripts/checks/vf-check.mjs" analyzer

scripts/apex/assert-application-wiring.apex (anonymous Apex, run after every Application.cls edit):

for (SObjectType t : new List<SObjectType>{ Account.SObjectType, Opportunity.SObjectType }) {
    fflib_ISObjectSelector s = Application.Selector.newInstance(t);
    System.assertEquals(t, s.sObjectType(), 'Selector bound to wrong SObjectType: ' + t);
}
System.assert(Application.Service.newInstance(IAccountsService.class) instanceof IAccountsService);
System.assertNotEquals(null, Application.UnitOfWork.newInstance());

References

• references/application-factory.md - full Application.cls, factory API tables, setMock matrix, wiring mistakes
• references/install-and-layout.md - vendoring, submodule, sfdx-project.json, .forceignore, version pinning, upgrades
• references/class-catalogue.md - every public fflib_* class in both libraries
• references/fflib-vs-plain-apex.md - decision matrix and one requirement implemented twice
• fflib-apex-common: https://github.com/apex-enterprise-patterns/fflib-apex-common
• fflib-apex-mocks: https://github.com/apex-enterprise-patterns/fflib-apex-mocks
• fflib-apex-common-samplecode: https://github.com/apex-enterprise-patterns/fflib-apex-common-samplecode
• Community docs: https://fflib.dev
• Trailhead, Apex Enterprise Patterns - Service Layer: https://trailhead.salesforce.com/en/content/learn/modules/apex_patterns_sl
• Trailhead, Domain and Selector Layer: https://trailhead.salesforce.com/en/content/learn/modules/apex_patterns_dsl
• Apex sharing keywords: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_keywords_sharing.htm
• PMD Apex security rules: https://docs.pmd-code.org/latest/pmd_rules_apex_security.html