Salesforce 第二代软件包 (2GP) 开发人员深度指南

背景与应用场景

我是一名 Salesforce 开发人员。在我的日常工作中，构建可扩展、可维护且易于分发的应用程序至关重要。Salesforce 平台上的应用程序分发机制被称为 Packaging (打包)。长期以来，First-Generation Packaging (1GP) (第一代软件包) 是我们的主要工具，但它与传统的基于 Org (组织) 的开发模式紧密相连，存在版本控制困难、依赖管理不灵活、自动化程度低等诸多挑战。

为了应对现代软件开发的需求，Salesforce 推出了 Second-Generation Packaging (2GP) (第二代软件包)。2GP 是一种全新的打包框架，它彻底改变了我们在 Salesforce 平台上构建和部署应用程序的方式。它的核心是Source-Driven Development (源码驱动开发) 模式，即以版本控制系统（如 Git）中的源代码为唯一信任源，而不是某个特定的 Salesforce Org。

这种转变使得 2GP 成为现代 DevOps 和 CI/CD (持续集成/持续部署) 实践的基石。对于我们开发人员来说，这意味着我们可以像开发其他平台的应用一样，利用强大的工具和自动化的流程来管理 Salesforce 应用的整个生命周期。

2GP 的核心应用场景包括：

  • ISV (独立软件供应商) 合作伙伴： 为 AppExchange 开发和分发商业应用程序。2GP 提供了更强大的模块化、依赖管理和版本控制能力，使 ISV 能够构建更复杂、更可靠的解决方案。
  • 企业内部应用开发： 大型企业通常有多个 Salesforce Orgs（例如，按业务部门或地理区域划分）。通过 2GP，企业可以将共享的功能（如自定义的触发器框架、集成中间件、公共组件库）打包，并在所有 Org 中统一安装和升级，极大地提高了代码复用性和治理能力。
  • 大型项目模块化： 将一个庞大、复杂的单体应用（"Happy Soup"）分解为多个逻辑上独立的、可独立开发和部署的小型软件包。这种微服务的思想有助于降低复杂性，提升团队的开发效率和敏捷性。
  • 系统集成商 (SI)： 为客户构建可重复使用的解决方案或加速器。SI 可以将通用的功能模块打包，在新项目中快速部署，缩短交付周期。

原理说明

要深入理解 2GP，我们需要掌握几个核心概念，这些概念共同构成了一个围绕源码和自动化的开发生态系统。

Dev Hub (开发中心)

Dev Hub 是 2GP 的指挥中心。它通常是你的生产 Org 或一个特殊的业务 Org。你需要在 Dev Hub 中启用 Salesforce DX 功能，它负责跟踪你所有的 Scratch Orgs (临时组织)、软件包以及软件包版本。所有 2GP 软件包的创建和版本管理命令都必须在授权到 Dev Hub 的环境下执行。

Source-Driven Development (源码驱动开发)

这是 2GP 的灵魂。所有元数据（Apex 类、对象、字段、权限集等）都以文件形式存储在版本控制系统中。sfdx-project.json 文件是项目的清单文件，它定义了项目的结构、软件包、依赖关系和命名空间等关键信息，是整个开发流程的起点和真实来源。

Scratch Orgs (临时组织)

Scratch Orgs 是一种临时的、可配置的、可通过 API 创建和销毁的 Salesforce Org。它们是 2GP 开发的理想环境。我们可以在 Scratch Org 中进行功能开发、单元测试和集成测试，而不会影响任何持久化环境。由于它们是基于源码创建的，因此可以确保每次都从一个干净、一致的环境开始。

Package 和 Package Version (软件包和软件包版本)

在 2GP 中，Package 是一个逻辑容器，它在 sfdx-project.json 文件中定义，并与 Dev Hub 中的一个记录相关联。它本身不是可安装的。真正可安装的实体是 Package Version。每次你准备好发布一个软件包的新快照时，你都会创建一个新的版本。这个版本是一个不可变的、经过版本控制的元数据构件，可以被安装到任何 Salesforce Org（如 Sandbox 或生产 Org）。

Namespace (命名空间)

对于计划在 AppExchange 上分发的 Managed Package (受管软件包)，Namespace 是必需的。它是一个唯一的标识符，会作为你所有自定义组件（对象、字段、Apex 类等）API 名称的前缀。这可以防止你的软件包组件与其他组织或软件包中的组件发生命名冲突。一个 Namespace 只能链接到一个 Dev Hub，并且这个操作是不可逆的。

Package Dependencies (软件包依赖关系)

2GP 最强大的功能之一就是其灵活的依赖管理。你可以在 sfdx-project.json 文件中明确声明一个软件包依赖于另一个软件包的特定版本。当安装主软件包时，Salesforce 会自动处理并安装其所有依赖项。这使得构建由多个小型、独立、可重用模块组成的复杂应用程序成为可能。

示例代码

以下示例将引导你完成 2GP 的核心生命周期，所有命令均基于 Salesforce CLI。这些示例直接来源于 Salesforce 官方文档，确保了准确性和可靠性。

1. 配置 sfdx-project.json

这是我们项目的核心配置文件。在这个例子中，我们定义了两个软件包：base-app 和 feature-app。其中，feature-app 依赖于 base-app 的特定版本。

{
  "packageDirectories": [
    {
      "path": "force-app/main/default",
      "default": true,
      "package": "base-app",
      "versionName": "ver 0.1",
      "versionNumber": "0.1.0.NEXT",
      "definitionFile": "config/project-scratch-def.json"
    },
    {
      "path": "force-app/feature/default",
      "package": "feature-app",
      "versionName": "ver 0.1",
      "versionNumber": "0.1.0.NEXT",
      "definitionFile": "config/project-scratch-def.json",
      "dependencies": [
        {
          "package": "base-app",
          "versionNumber": "0.1.0.LATEST"
        }
      ]
    }
  ],
  "namespace": "my_namespace",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "58.0",
  "packageAliases": {
    "base-app": "0HoB00000004CFpKAM",
    "base-app@0.1.0-1": "04tB0000000IB1fIAG",
    "feature-app": "0HoB00000004CFqKAM"
  }
}

注释：

  • packageDirectories: 定义了项目中的源代码路径和它们对应的软件包。
  • package: 软件包的别名，在整个项目中保持唯一。
  • versionNumber: 定义了软件包版本的格式。NEXT 是一个关键字，每次创建版本时会自动递增。
  • dependencies: 在 feature-app 中，我们声明了它依赖于 base-app 的最新（LATEST）版本。
  • packageAliases: 用于存储软件包 ID（0Ho...）和软件包版本 ID（04t...）的别名，方便在命令行中引用。

2. 创建一个软件包 (Package)

这个命令在 Dev Hub 中注册一个新的软件包实体。你只需要为每个软件包执行一次此操作。

sf package create --name "base-app" --package-type Managed --path "force-app/main/default" --target-dev-hub MyDevHub

注释：

  • --name: 软件包的名称，应与 sfdx-project.json 中的别名匹配。
  • --package-type: 指定软件包类型，通常是 Managed（受管）或 Unlocked（非受管）。
  • --path: 包含此软件包元数据的目录路径。
  • --target-dev-hub: 用于执行此操作的 Dev Hub 的别名。

3. 创建一个软件包版本 (Package Version)

这是最常用的命令，它会获取指定路径下的源代码，并创建一个不可变的软件包版本构件。

sf package version create --package "base-app" --path "force-app/main/default" --installation-key "MyInstallKey123" --wait 20 --code-coverage --target-dev-hub MyDevHub

注释：

  • --package: 要创建版本的软件包的别名。
  • --installation-key: 为此版本设置安装密码，增加安全性。
  • --wait: 指定等待版本创建完成的分钟数。
  • --code-coverage: 强制计算 Apex 代码覆盖率。如果覆盖率低于75%，对于受管软件包，版本创建将失败。

4. 推广软件包版本 (Promote)

一旦一个软件包版本经过充分测试并准备好发布，你需要将其“推广”为可发布状态。只有被推广的版本才能安装到生产 Org。

sf package version promote --package "base-app@0.1.0-1" --target-dev-hub MyDevHub

注释：

  • --package: 要推广的软件包版本的别名或 ID (04t...)。你可以在 sfdx-project.json 的 `packageAliases` 中找到它。

注意事项

权限与设置

  • Dev Hub 启用： 必须在你的业务组织（通常是生产 Org）中启用 Dev Hub 功能。
  • 用户权限： 在 Dev Hub 中执行操作的用户需要 "Salesforce DX" 权限集，或者至少拥有“创建和更新第二代软件包”和“管理第二代软件包”的系统权限。

命名空间 (Namespace)

  • 不可逆转： 将一个 Namespace 链接到你的 Dev Hub 是一个不可逆转的操作。一旦链接，该 Namespace 只能用于从此 Dev Hub 创建的软件包。
  • 唯一性： Namespace 在所有 Salesforce Org 中是唯一的。在注册前，请仔细规划你的命名空间。

依赖管理

  • 禁止循环依赖： 你不能创建循环依赖，例如包 A 依赖包 B，同时包 B 又依赖包 A。
  • 版本锁定： 依赖项必须指向一个具体的、已发布的软件包版本 ID (04t...)，或者使用 LATEST 关键字指向最新已推广的版本。在 CI/CD 流程中，建议锁定到具体的版本 ID 以确保构建的确定性。

版本控制与升级

  • Package Ancestry (软件包血缘)： 2GP 强制执行一个清晰的“血缘”概念。每个新版本都必须有一个“祖先”，通常是前一个版本。这确保了升级路径的平滑。如果你尝试创建一个没有有效祖先的版本（例如，基于一个完全不同的代码分支），版本创建可能会失败。
  • 破坏性变更： 从受管软件包中删除组件（如 Apex 类、对象字段）是一个破坏性变更，需要非常谨慎。你不能简单地从代码库中删除它们，而需要遵循一个弃用流程，或者在某些情况下，这些变更是不被允许的。

错误处理

  • 版本创建失败： 如果 package version create 命令失败，请仔细检查输出日志。常见原因包括 Apex 测试失败、代码覆盖率不足、元数据格式错误或无效的依赖关系。
  • 日志查询： 你可以使用 sf package version create list 来查看版本创建请求的历史记录和状态。

总结与最佳实践

作为一名 Salesforce 开发人员，拥抱 Second-Generation Packaging (2GP) 是迈向现代化、专业化应用开发的关键一步。它将我们从繁琐的手动部署和不透明的 Org 状态中解放出来，让我们能够专注于编写高质量的代码，并将其无缝地集成到自动化的 DevOps 流程中。

2GP 的核心优势在于它的模块化、自动化和可追溯性。通过将大型应用分解为更小的、独立的软件包，我们降低了维护成本，提高了开发速度，并实现了真正的代码复用。

最佳实践：

  • 模块化设计 (Modular Design)

    遵循单一职责原则。让每个软件包都专注于一个明确的业务功能或技术能力。例如，一个包负责处理与外部系统的集成，另一个包提供一套通用的 Lightning Web Components，还有一个包实现核心的业务逻辑。

  • 版本控制策略 (Version Control Strategy)

    采用成熟的 Git 分支策略，如 GitFlow。使用功能分支进行新开发，将发布分支用于创建软件包版本，并使用主分支作为已发布代码的稳定记录。这为并行开发和版本管理提供了清晰的框架。

  • 自动化一切 (Automate Everything)

    构建一个完整的 CI/CD 流水线。当代码合并到特定分支时，自动触发脚本来：1) 创建一个新的 Scratch Org；2) 推送源代码；3) 运行所有 Apex 测试；4) 如果测试通过，则创建一个新的软件包版本；5) 将新版本自动安装到一个用于测试的 Sandbox 中。

  • 依赖清晰化 (Clarify Dependencies)

    在 sfdx-project.json 中明确并锁定所有依赖关系的版本。这可以避免“在我的机器上能用”的问题，并确保构建过程是可重复和确定性的。

  • 全面的测试 (Comprehensive Testing)

    不要仅仅依赖 Apex 单元测试。在 CI/CD 流程中集成自动化测试，包括集成测试（测试包与包之间的交互）和端到端的功能测试，以确保每个软件包版本的质量。

通过遵循这些原则和实践，你可以充分利用 2GP 的强大功能，为你的客户和用户交付更稳定、更可靠、更易于维护的 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) 在每月账单或营销邮件中，动态显示客户的当前...
阅读全文