SOQL-Lib 基础功能全面解析：提升 Salesforce 开发效率

一、动态 SOQL 构建

SOQL-Lib 通过 SOQL.cls 类提供了动态构建 SOQL 查询的能力，这种方式比传统的字符串拼接更加安全和灵活。

基础查询示例

// 查询 Account 表的 Id 和 Name 字段，限制返回 100 条记录
SOQL.of(Account.SObjectType)
    .with(Account.Id, Account.Name)
    .setLimit(100)
    .toList();

条件查询示例

String accountName = '';

SOQL.of(Account.SObjectType)
    .whereAre(SOQL.FilterGroup
        .add(SOQL.Filter.with(Account.BillingCity).equal('Krakow'))
        .add(SOQL.Filter.name().contains(accountName)
            .ignoreWhen(String.isEmpty(accountName)))
    )
    .toList();

这种构建方式会自动处理空值条件，避免了传统方式中需要手动检查空值的繁琐操作。

二、自动变量绑定

SOQL-Lib 会自动处理 WHERE 条件中的变量绑定，无需开发者手动处理，既安全又高效。

// 自动绑定变量到查询条件
SOQL.of(Account.SObjectType)
    .with(Account.Id, Account.Name)
    .whereAre(SOQL.Filter.with(Account.Name).contains('Test'))
    .toList();

系统会自动生成绑定变量映射：

{
  "v1" : "%Test%"
}

三、权限控制机制

用户模式与系统模式

• USER_MODE（默认）：强制执行当前用户的对象权限、字段级安全性和共享规则
• SYSTEM_MODE：忽略当前用户的对象和字段级权限，共享规则由 sharingMode 控制

// 系统模式查询示例
SOQL.of(Account.SObjectType)
    .with(Account.Id, Account.Name)
    .systemMode()
    .toList();

四、共享规则控制

SOQL-Lib 提供了灵活的共享规则控制方式：

// 不强制执行共享规则查询
SOQL.of(Account.SObjectType)
    .with(Account.Id, Account.Name)
    .systemMode()
    .withoutSharing()
    .toList();

开发者可以根据业务需求选择：

• withSharing()：强制执行共享规则
• withoutSharing()：不强制执行共享规则
• inheritedSharing()：继承调用类的共享模式（默认）

五、测试模拟功能

SOQL-Lib 的模拟功能让单元测试更加简单高效：

基本模拟示例

// 控制器类
public with sharing class ExampleController {
    public static List<Account> getPartnerAccounts(String accountName) {
        return SOQL_Account.query()
            .mockId('ExampleController.getPartnerAccounts')
            .toList();
    }
}

// 测试类
@IsTest
private class ExampleControllerTest {
    @IsTest
    static void getPartnerAccounts() {
        List<Account> accounts = new List<Account>{
            new Account(Name = 'MyAccount 1'),
            new Account(Name = 'MyAccount 2')
        };

        SOQL.mock('ExampleController.getPartnerAccounts').thenReturn(accounts);
        
        List<Account> result = ExampleController.getPartnerAccounts('MyAccount');
        Assert.areEqual(accounts, result);
    }
}

支持多种模拟数据来源：

• 内存中的 SObject 列表
• 单个 SObject 记录
• 静态资源 CSV 文件
• 计数结果

六、最佳实践建议

1. 使用 Selector 模式避免重复代码

public inherited sharing class SOQL_Account extends SOQL implements SOQL.Selector {
    public static SOQL_Account query() {
        return new SOQL_Account();
    }

    private SOQL_Account() {
        super(Account.SObjectType);
        // 默认配置
        with(Account.Id, Account.Name, Account.Type)
            .systemMode()
            .withoutSharing();
    }

    public SOQL_Account byIndustry(String industry) {
        with(Account.Industry)
            .whereAre(Filter.with(Account.Industry).equal(industry));
        return this;
    }
}

2. 使用缓存提升性能

对于不经常变更的数据（如 Profile、BusinessHours 等），使用缓存可以显著提升性能：

public with sharing class SOQL_ProfileCache extends SOQLCache implements SOQLCache.Selector {
    public static SOQL_ProfileCache query() {
        return new SOQL_ProfileCache();
    }

    private SOQL_ProfileCache() {
        super(Profile.SObjectType);
        cacheInOrgCache();
        with(Profile.Id, Profile.Name, Profile.UserType);
        maxHoursWithoutRefresh(24);
    }
}

3. 使用增强的结果转换方法

SOQL-Lib 提供了丰富的结果转换方法：

// 传统方式
Map<Id, Id> contactIdToAccountId = new Map<Id, Id>();
for (Contact contact : [SELECT Id, AccountId FROM Contact]) {
    contactIdToAccountId.put(contact.Id, contact.AccountId)
}

// 使用 SOQL-Lib 方式
Map<String, String> contactIdToAccountId = 
    SOQL_Contact.query().toMap(Contact.Id, Contact.AccountId);

七、总结

SOQL-Lib 为 Salesforce 开发者提供了一套强大而灵活的工具集，通过本文介绍的基础功能，开发者可以：

1. 更安全地构建动态 SOQL 查询
2. 更精细地控制权限和共享规则
3. 更高效地编写单元测试
4. 更优雅地组织查询代码
5. 更简单地实现性能优化

这些功能组合使用，可以显著提升开发效率和代码质量，是 Salesforce 开发中值得掌握的重要工具。