Salesforce 自定义对象开发者指南：深入 Apex、DML 与元数据 API

背景与应用场景

在 Salesforce 平台中，Object (对象) 是数据结构的核心，类似于传统数据库中的表。Salesforce 提供了丰富的 Standard Objects (标准对象)，如 Account (客户)、Contact (联系人) 和 Opportunity (商机)，来满足通用的业务需求。然而，任何一家企业的业务流程都有其独特性，标准对象往往无法完全覆盖所有场景。这时，Custom Objects (自定义对象) 就成为了扩展 Salesforce 功能、构建定制化应用的关键。

对于 Salesforce 开发人员而言，自定义对象不仅仅是一个在 UI 上创建的数据容器。它们是我们代码的基石，是我们通过 Apex、SOQL (Salesforce Object Query Language) 和 DML (Data Manipulation Language) 进行交互的核心实体。无论是开发一个复杂的项目管理应用，还是一个简单的设备追踪系统，其底层都离不开精心设计的自定义对象。

应用场景示例：

  • 项目管理：创建一个名为 `Project__c` 的自定义对象来存储项目信息，如项目名称、负责人、开始日期、结束日期和状态。再创建一个 `Task__c` 对象，通过 Master-Detail Relationship (主从关系) 关联到 `Project__c`，用于追踪项目下的具体任务。
  • 招聘管理：创建一个 `Position__c` 对象表示招聘职位，再创建一个 `Candidate__c` 对象表示候选人，并使用一个 `Job_Application__c` 联结对象 (Junction Object) 来管理候选人对多个职位的申请。
  • 资产追踪：创建一个 `Asset_Tracking__c` 对象，用于记录公司内部的硬件资产，如笔记本电脑、显示器的序列号、分配给的员工以及购买日期。

理解如何通过编程方式与自定义对象进行交互，包括数据操作和元数据管理，是衡量一位 Salesforce 开发人员能力的重要标准。本文将从开发者的视角，深入探讨自定义对象的原理、代码交互、注意事项及最佳实践。

原理说明

从技术层面看，一个自定义对象在 Salesforce 平台中由数据和元数据两部分组成。

1. 数据 (Data)

数据指的是存储在对象中的具体记录 (Records)，相当于数据库表中的行。作为开发者，我们主要通过以下方式与数据进行交互：

  • DML (Data Manipulation Language - 数据操作语言): 这是 Apex 中用于对数据库记录执行 `insert` (插入)、`update` (更新)、`delete` (删除)、`upsert` (插入或更新) 等操作的关键字。对自定义对象记录的所有增删改都通过 DML 完成。
  • SOQL (Salesforce Object Query Language - Salesforce 对象查询语言): 这是用于从 Salesforce 数据库中检索数据的查询语言，语法与 SQL 类似。我们可以使用 SOQL 来读取自定义对象的记录。通过 `__r` 后缀，我们还可以方便地查询关联对象的数据。

2. 元数据 (Metadata)

元数据是“关于数据的数据”，它定义了自定义对象的结构和行为。这包括：

  • API Name (API 名称): 这是自定义对象和字段在代码和 API 调用中唯一的标识符。所有自定义对象和字段的 API 名称都以 `__c` 结尾，例如 `Project__c`。这是区分标准对象和自定义对象的关键。一旦创建，API 名称便不可更改（只能修改 Label）。
  • Fields (字段): 定义了对象能存储哪些信息，类似于数据库表的列。例如，文本字段、日期字段、公式字段以及关系字段 (Lookup, Master-Detail)。
  • Relationships (关系): 定义了对象之间的关联，是构建复杂数据模型的基础。
  • Page Layouts (页面布局), Record Types (记录类型), Validation Rules (验证规则) 等：这些都属于对象的元数据，共同定义了用户界面和业务逻辑。

对于开发者而言，除了通过 DML 和 SOQL 操作数据外，我们还可以通过 Metadata API 来编程化地创建、修改或删除自定义对象及其元数据。这在自动化部署 (CI/CD)、构建托管包 (Managed Packages) 或动态配置应用时非常有用。

示例代码

以下代码示例将展示开发者如何通过 Apex 与一个假设的自定义对象 `Book__c` 进行交互。该对象包含 `Name` (标准字段), `Author__c` (Text), `Published_Year__c` (Number) 等字段。

1. 使用 DML 和 SOQL 操作自定义对象记录

这个例子展示了最常见的数据操作：创建一本新书的记录，然后查询出来进行验证。

// 示例 1: 创建并查询自定义对象记录
// 假设存在一个名为 Book__c 的自定义对象

// 步骤 1: 实例化一个新的 Book__c SObject
// 在 Apex 中，每个自定义对象都对应一个 SObject 类型，其名称与对象的 API Name 相同。
Book__c newBook = new Book__c();

// 步骤 2: 为字段赋值
// 使用点表示法访问字段，注意自定义字段的 API Name 必须以 __c 结尾。
newBook.Name = 'The Three-Body Problem'; // Name 是标准字段，无需 __c
newBook.Author__c = 'Cixin Liu';
newBook.Published_Year__c = 2008;

// 步骤 3: 使用 DML 的 insert 语句将记录插入到数据库
// 建议将 DML 操作放在 try-catch 块中以处理潜在的异常，如验证规则失败。
try {
    insert newBook;
    // 插入成功后，newBook 变量会自动填充 Id 字段值。
    System.debug('成功创建书籍，记录ID为: ' + newBook.Id);
} catch (DmlException e) {
    System.debug('创建书籍记录失败: ' + e.getMessage());
}

// 步骤 4: 使用 SOQL 查询刚刚创建的记录
// SOQL 查询语句中，对象和字段名同样使用 API Name。
// 为了避免查询到不相关的数据，我们使用 Id 进行精确过滤。
if (newBook.Id != null) {
    List<Book__c> queriedBooks = [
        SELECT Id, Name, Author__c, Published_Year__c
        FROM Book__c
        WHERE Id = :newBook.Id
    ];

    // 步骤 5: 验证查询结果并输出
    if (!queriedBooks.isEmpty()) {
        Book__c myBook = queriedBooks[0];
        System.debug('查询到的书籍名称: ' + myBook.Name);
        System.debug('作者: ' + myBook.Author__c);
        System.debug('出版年份: ' + myBook.Published_Year__c);
    }
}

2. 使用 Apex Metadata API 创建自定义对象

这是一个更高级的用例，展示了如何使用 Apex 代码动态地创建一个新的自定义对象。这在需要根据某些业务逻辑自动生成数据结构时非常强大。

// 示例 2: 通过 Metadata API 动态创建自定义对象
// 此代码需要在具有部署权限的用户上下文中异步执行。

// 步骤 1: 实例化一个 CustomObject 元数据类型
// Metadata 命名空间包含了所有可用于操作元数据的 Apex 类。
Metadata.CustomObject customObject = new Metadata.CustomObject();

// 步骤 2: 定义自定义对象的基本属性
customObject.fullName = 'My_Dynamic_Object__c'; // 必须以 __c 结尾
customObject.label = 'My Dynamic Object';
customObject.pluralLabel = 'My Dynamic Objects';
customObject.sharingModel = Metadata.SharingModel.ReadWrite; // 定义共享模型
customObject.deploymentStatus = Metadata.DeploymentStatus.Deployed;
customObject.description = '一个通过 Apex Metadata API 动态创建的对象。';

// 步骤 3: 定义对象的 Name 字段 (所有自定义对象都必须有)
Metadata.CustomField nameField = new Metadata.CustomField();
nameField.type = Metadata.FieldType.Text;
nameField.label = 'Object Name';
nameField.fullName = 'Name'; // Name 字段的 fullName 特殊，就是 'Name'
customObject.nameField = nameField;

// 步骤 4: 创建一个自定义字段并添加到对象中
Metadata.CustomField customField = new Metadata.CustomField();
customField.fullName = 'Status__c';
customField.label = 'Status';
customField.type = Metadata.FieldType.Text;
customField.length = 80;
customObject.fields = new List<Metadata.CustomField>{customField};

// 步骤 5: 创建一个部署容器并添加元数据组件
Metadata.DeployContainer container = new Metadata.DeployContainer();
container.addMetadata(customObject);

// 步骤 6: 异步部署元数据
// Metadata.Operations.enqueueDeployment 是一个异步方法，它返回一个 ID 用于追踪部署状态。
Id asyncResultId = Metadata.Operations.enqueueDeployment(container, null);
System.debug('元数据部署已启动，追踪 ID: ' + asyncResultId);

// 你需要另外编写代码来轮询这个 asyncResultId 的状态，以确认部署是否成功。

注意事项

1. 权限与安全 (Permissions & Security)

对象权限：用户能否访问自定义对象记录，取决于其 Profile (简档) 或 Permission Set (权限集) 中设置的 CRUD (Create, Read, Update, Delete) 权限。如果用户没有某个对象的 Read 权限，任何查询该对象的 SOQL 都会失败。

字段级安全 (Field-Level Security - FLS): 即使用户有对象的读取权限，也可能因为 FLS 的设置而无法读取或编辑特定字段。Apex 默认在系统模式下运行，会忽略 FLS，但可以通过 `Security.stripInaccessible` 方法或使用 `WITH SECURITY_ENFORCED` 子句来强制遵循 FLS。

共享模型 (Sharing Model): 对象的组织范围默认设置 (Organization-Wide Defaults - OWD) 决定了记录的基线可见性。如果设置为 Private，开发者需要考虑使用 Sharing Rules (共享规则)、Roles (角色) 或 Apex Managed Sharing 来开放记录的访问权限。

2. API 限制与 Governor Limits

Salesforce 是一个多租户环境，为了保证平台稳定性，对代码执行有严格的资源限制，即 Governor Limits。

  • DML 限制：在单次执行事务中，DML 语句的调用次数不能超过 150 次。因此，必须避免在循环中执行 DML 操作。始终将要操作的记录添加到一个 List 中，然后进行一次性的批量 DML 操作。
  • SOQL 查询限制：单次事务中，SOQL 查询返回的总记录数不能超过 50,000 条。查询语句的调用次数不能超过 100 次。同样，应避免在循环中执行 SOQL。
  • 自定义对象限制：一个 Org 中可创建的自定义对象数量是有限的，具体取决于 Salesforce 版本 (例如，Enterprise Edition 为 200 个，Unlimited Edition 为 2000 个)。在设计数据模型时需要考虑这个上限。

3. 错误处理

DML 操作可能会因为多种原因失败，如触发了验证规则、必填字段为空、唯一性约束冲突等。稳健的代码必须包含完善的错误处理机制。

  • 使用 `try-catch` 块：将 DML 语句包裹在 `try-catch` 块中，可以捕获 `DmlException` 并进行优雅地处理，而不是让整个事务回滚。
  • 使用 `Database` 类方法：`Database.insert(records, allOrNone)` 方法提供了更精细的控制。当 `allOrNone` 设置为 `false` 时，即使部分记录失败，成功的记录也会被提交。该方法返回一个 `Database.SaveResult` 对象数组，可以遍历它来检查每条记录的成功或失败状态及具体错误信息。

总结与最佳实践

自定义对象是 Salesforce 平台灵活性的核心体现，也是开发者构建定制化解决方案的基础。作为一名 Salesforce 开发人员，掌握其深层原理和编程交互方式至关重要。

最佳实践：

  1. 规划先于编码：在创建任何自定义对象之前，先仔细规划你的数据模型。思考对象间的关系、数据类型以及未来的扩展性。一个糟糕的数据模型会给后续的开发和维护带来无尽的麻烦。
  2. 遵循命名约定：为自定义对象和字段使用清晰、一致的 API 名称（英文）和 Label（显示标签）。例如，对象名使用单数形式 (如 `Project__c`)，字段名清晰描述其用途 (如 `Estimated_Hours__c`)。
  3. 善用描述字段：始终为你的自定义对象和字段填写详细的描述。这对于未来的你或其他接手项目的开发者来说是极其宝贵的文档。
  4. 代码批量化 (Bulkification): 永远假设你的代码会处理多条记录。无论是 SOQL 查询还是 DML 操作，都要以集合 (List, Set, Map) 为中心进行设计，以避免触及 Governor Limits。
  5. 安全第一：在设计和编码时，始终将权限和数据可见性放在心上。根据业务需求选择合适的共享模型，并考虑 Apex 代码的运行上下文 (`with sharing` vs `without sharing`)。
  6. 优先选择声明式工具：在编写复杂的 Apex Trigger 之前，优先考虑是否能用 Flow、Validation Rule 或其他声明式工具实现需求。代码应该作为解决复杂逻辑的最后手段。

通过遵循这些原则，你可以构建出健壮、可扩展且易于维护的 Salesforce 应用，而自定义对象正是这一切的起点。

评论

发表评论

此博客中的热门博文

Salesforce 登录取证：深入解析用户访问监控与安全

背景与应用场景 在当今的数字化环境中，企业信息安全至关重要。Salesforce 作为全球领先的 CRM 平台，存储着企业最核心的客户数据、销售记录和商业机密。因此，对 Salesforce 组织的访问控制和监控是安全体系中不可或缺的一环。 Login Forensics（登录取证） 是一种通过分析用户登录数据来识别、调查和响应潜在安全威胁的过程。 无论是满足合规性要求（如 SOX、GDPR、HIPAA），还是主动防御内部威胁和外部攻击，登录取证都提供了关键的数据支持。其主要应用场景包括： 安全审计与合规： 向审计人员提供详细的用户登录记录，证明企业已实施适当的访问控制措施。 威胁检测： 识别异常登录行为，例如： 短时间内来自不同地理位置的登录尝试。 在非工作时间或节假日的登录。 来自已知恶意 IP 地址的访问。 特定用户的大量失败登录尝试，可能预示着密码暴力破解攻击。 故障排查： 帮助用户解决“无法登录”等问题，通过查看登录状态和失败原因快速定位问题。 用户行为分析： 了解用户如何以及何时访问 Salesforce，为优化用户体验和系统性能提供数据依据。 Salesforce 平台提供了强大的原生工具来支持登录取证，主要依赖于两个核心功能：标准的 LoginHistory 对象和更为高级的 Event Monitoring（事件监控） 。 原理说明 Salesforce 通过记录每一次用户登录尝试的详细信息，为登录取证提供了数据基础。根据需求和复杂度的不同，我们可以通过两种主要方式来访问这些数据。 1. LoginHistory SObject LoginHistory 是一个标准的 Salesforce 对象，用于存储组织过去 6 个月内的用户登录历史记录。它就像一个标准的“登录日志”，记录了每次登录尝试的基本信息。系统管理员或拥有“查看设置和配置”权限的用户可以通过 SOQL (Salesforce Object Query Language) 查询、报表或 API 来访问这些数据。 该对象包含的关键字段有： UserId...
阅读全文

Salesforce Experience Cloud 技术深度解析：构建社区站点 (Community Sites)

背景与应用场景 在数字化转型的浪潮中，企业 increasingly seek to build engaging online spaces to connect with their customers, partners, and employees. Salesforce Experience Cloud, formerly known as Community Cloud, is a powerful platform designed precisely for this purpose. It enables the rapid creation of branded, secure, and intelligent digital experiences, all built on the trusted Salesforce platform. 作为一名 Salesforce 技术架构师，理解 Experience Cloud 的核心能力与架构是设计可扩展、安全且高性能解决方案的关键。这些数字体验站点（通常仍被称为 Community Sites）不仅仅是简单的网站，它们是深入集成到企业 CRM 数据和业务流程中的动态门户。 常见的应用场景包括： 客户自助服务门户 (Customer Self-Service Portal): 客户可以在这里查找知识库文章、提交和跟踪支持个案 (Cases)、参与社区讨论，从而降低服务成本并提升客户满意度。 合作伙伴关系管理门户 (Partner Relationship Management Portal): 合作伙伴可以通过门户进行交易注册 (Deal Registration)、管理销售线索 (Leads) 和业务机会 (Opportunities)、获取营销资料，与企业实现无缝的销售协同。 员工社区 (Employee Community): 为员工提供一个集中的平台，用于获取公司信息、进行内部协作、访问人力资源系统等，增强员工归属感和工作效率。 这些门户的核心价值在于，它们将正确的数据和流程在正确的时间，安全地呈现在正确的用户面前。而这一切的实现，都依赖于其背后精巧的技术架构。 原理说明 要精通 Experience Cloud，我们必须深入理解其...
阅读全文

精通 Salesforce Email Studio：咨询顾问指南之 AMPscript 与数据扩展实现动态个性化邮件

背景与应用场景 作为一名 Salesforce 咨询顾问，我经常与各种规模的企业合作，他们共同的目标是提升客户参与度并最终推动业务增长。在数字营销领域，电子邮件仍然是与客户建立和维持关系最有效、最具成本效益的渠道之一。然而，如今的客户期望收到的不再是千篇一律的通用邮件，而是与他们个人兴趣、行为和需求高度相关的内容。这正是 Salesforce Marketing Cloud 中的 Email Studio 发挥关键作用的地方。 Email Studio 不仅仅是一个群发邮件的工具，它是一个强大的平台，能够通过深度个性化来创造卓越的客户体验。实现这种深度个性化的核心技术在于 AMPscript 和 Data Extensions (数据扩展) 的结合使用。脱离了这两个工具，邮件营销很容易退化为简单的广播，导致参与度下降和客户流失。 在我的咨询实践中，以下是一些最常见的应用场景，它们都依赖于 AMPscript 和 Data Extensions 来实现： 1. 欢迎系列邮件 (Welcome Series) 当新用户注册时，根据其注册来源（如：官网、社交媒体活动、线下门店）或提供的兴趣偏好，动态展示不同的欢迎语、产品推荐或入门指南。 2. 废弃购物车挽回 (Abandoned Cart Recovery) 电商企业最关键的自动化流程之一。通过 AMPscript 查询与订阅者关联的废弃购物车 Data Extension，邮件可以动态地展示被遗弃的具体商品图片、名称、价格，并提供一个直接返回购物车的链接。 3. 个性化产品推荐 (Personalized Product Recommendations) 根据客户的购买历史、浏览行为或会员等级，从一个庞大的产品目录 Data Extension 中动态抓取并展示最相关的产品，实现“千人千面”的推荐效果。 4. 基于地理位置的动态内容 (Geo-Targeted Content) 根据订阅者档案中存储的城市或邮政编码，在邮件中动态展示距离最近的门店地址、当地的促销活动或符合当地气候的产品。 5. 忠诚度计划状态更新 (Loyalty Program Updates) 在每月账单或营销邮件中，动态显示客户的当前...
阅读全文