Salesforce Named Credentials 深度解析：构建安全 API 集成的终极指南

十月 31, 2025

背景与应用场景

作为一名 Salesforce 集成工程师，我的日常工作核心就是将 Salesforce 与外部系统进行无缝连接。无论是与 ERP 系统同步订单数据、调用支付网关处理交易，还是从第三方服务获取最新的市场资讯，可靠且安全的 API 集成都是关键。在 Salesforce 的早期，开发者们普遍面临一个棘手的问题：如何管理外部服务的端点 URL 和认证凭证？

最初的解决方案通常是将这些敏感信息硬编码（Hardcoding）在 Apex 代码中，或者存储在自定义设置（Custom Settings）/自定义元数据（Custom Metadata）中。这些方法存在着显而易见的弊端：

安全风险：将密码、API 密钥等明文或简单加密后存储在代码或元数据中，极易被泄露，构成了严重的安全漏洞。
维护噩梦：当外部系统的 URL 或凭证发生变更时（例如，密码定期轮换或从沙箱切换到生产环境），我们需要修改代码或元数据，然后重新进行部署。这个过程繁琐、耗时且容易出错。
部署复杂性：在不同的环境（如开发、测试、生产）之间迁移集成逻辑时，必须手动更新每个环境的端点和凭证，增加了部署的复杂度和失败风险。

为了彻底解决这些问题，Salesforce 推出了 Named Credential（命名凭证）这一强大的功能。它提供了一个安全、统一的方式来定义和管理对外部 Web 服务的 API 调用端点及其所需的身份验证参数。对于集成工程师而言，Named Credential 不仅仅是一个便利工具，更是构建企业级、可扩展、安全可靠集成架构的基石。

原理说明

Named Credential 的核心思想是将 API 的端点 URL 和身份验证细节从代码中完全分离出来，进行集中化、声明式的管理。当你在 Apex 代码中引用一个 Named Credential 时，Salesforce 会在后台自动处理所有与身份验证相关的复杂工作，开发者只需关注业务逻辑本身。

一个 Named Credential 主要由以下几个关键部分构成：

1. URL

这是外部服务的根 URL 或基础端点。例如，如果要调用的 API 是 `https://api.example.com/v1/invoices`，那么 Named Credential 的 URL 字段应设置为 `https://api.example.com`。在 Apex 代码中，你只需要提供相对路径 `/v1/invoices` 即可。

2. Identity Type (身份类型)

这决定了 Salesforce 如何为对外部系统的每个调用进行身份验证。

Named Principal (指定主体)：这是最常见的类型，适用于系统对系统的集成。你为所有从 Salesforce 发出的调用设置一组固定的凭证（例如，一个专用的集成用户的用户名和密码，或一个共享的 API 密钥）。所有用户通过 Apex 调用此 Named Credential 时，都使用这同一套凭证。
Per User (每用户)：这种类型适用于需要将当前 Salesforce 用户的身份传递到外部系统的场景。每个需要访问外部系统的 Salesforce 用户都需要在外部系统中拥有自己的账户。Salesforce 会为每个用户独立管理他们的身份验证流程（例如，通过 OAuth 2.0），确保外部系统知道是哪位具体用户在执行操作。

3. Authentication Protocol (身份验证协议)

Named Credential 支持多种主流的身份验证协议，以适应不同的外部服务要求：

No Authentication：用于调用公开、无需身份验证的 API。
Password Authentication：支持基本的用户名密码验证（Basic Authentication）。Salesforce 会安全地存储这些凭证，并在每次调用时自动将其添加到请求头中。
OAuth 2.0：这是现代 Web 服务中最常用、最安全的协议。Named Credential 极大地简化了 OAuth 2.0 的复杂流程。你只需配置好一个 Auth. Provider（身份验证提供程序），然后在 Named Credential 中引用它。Salesforce 会自动处理获取、存储和刷新访问令牌（Access Token）和刷新令牌（Refresh Token）的整个过程。开发者在代码中无需关心任何与 Token 相关的逻辑。
JWT 和 JWT Token Exchange：用于更高级的、需要使用 JSON Web Tokens 进行身份验证的场景。

4. `callout:` 协议

在 Apex 代码中使用 Named Credential 的关键是 `callout:` 协议。你不再直接使用完整的 URL，而是使用 `callout:YourNamedCredentialName/path` 这样的格式作为请求的端点。当 Salesforce 的 Apex 运行时引擎看到 `callout:` 前缀时，它会：

查找名为 `YourNamedCredentialName` 的 Named Credential。
获取其配置的根 URL。
根据配置的身份验证协议，执行认证流程（如附加 Basic Auth 头，或获取并附加一个有效的 OAuth 2.0 Bearer Token）。
将根 URL 和代码中提供的 `/path` 拼接成完整的请求 URL。
发送最终构造好的 HTTP 请求到外部系统。

这种机制的优美之处在于，所有认证的复杂性和凭证管理的安全性都由平台处理，代码变得异常简洁和干净。

注意：近年来，Salesforce 引入了 External Credential (外部凭证) 的概念，它是对 Named Credential 的进一步增强和模块化。External Credential 专注于定义身份验证协议和权限，而 Named Credential 则专注于定义端点 URL 并引用一个 External Credential。对于新的集成项目，强烈建议使用这种新的模式，因为它提供了更精细的权限控制和更灵活的配置。

示例代码

假设我们已经创建了一个名为 `My_API_Service` 的 Named Credential，它指向 `https://api.example.com` 并使用密码验证（Password Authentication）或 OAuth 2.0 进行了配置。现在，我们希望通过 Apex 调用该服务的 `/user/me` 端点来获取当前用户信息。

示例：使用 Named Credential 发起一个 GET 请求

以下代码示例严格遵循 Salesforce 官方文档中的标准实践，展示了如何通过 Apex 发起一个 Apex Callout（Apex 调用）到由 Named Credential 定义的外部服务。

// 准备一个 HTTP 请求对象
HttpRequest req = new HttpRequest();

// 设置端点。这是 Named Credential 的魔力所在。
// 我们使用 'callout:' 协议，后跟 Named Credential 的 API 名称，
// 以及要访问的资源的相对路径。
// Salesforce 将会自动将 'callout:My_API_Service' 替换为 'https://api.example.com'
// 并且根据 Named Credential 的配置添加所有必要的认证头（如 Authorization）。
req.setEndpoint('callout:My_API_Service/user/me');

// 设置 HTTP 方法为 GET，用于获取数据。
req.setMethod('GET');

// 创建一个 Http 对象来发送请求。
Http http = new Http();

// 发送请求并等待响应。这个操作是一个同步调用。
// 平台会处理网络连接、发送请求、接收响应等所有底层细节。
HttpResponse res = http.send(req);

// 检查响应。一个好的实践是总是检查 HTTP 状态码。
// 200 表示请求成功。
if (res.getStatusCode() == 200) {
    // 如果成功，我们可以处理响应体中的数据。
    // getBody() 方法返回的是一个字符串，通常是 JSON 或 XML 格式。
    System.debug('响应成功: ' + res.getBody());

    // 在实际应用中，这里会进行 JSON 反序列化等操作。
    // Map<String, Object> results = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());

} else {
    // 如果请求失败，记录错误信息。
    // 这对于调试和监控集成至关重要。
    System.debug('请求失败。状态码: ' + res.getStatusCode() + '，状态: ' + res.getStatus());
    System.debug('错误响应体: ' + res.getBody());
}

正如你所看到的，代码中完全没有出现任何 URL、用户名、密码或 API 密钥。代码变得非常简洁、可读，并且可以无缝地在任何 Salesforce 环境中部署和运行，只要该环境中存在一个名为 `My_API_Service` 的 Named Credential 即可。

注意事项

作为集成工程师，在使用 Named Credential 时，必须关注以下几个方面以确保集成的健壮性和安全性：

权限管理：
- 创建和修改 Named Credential 需要 “Customize Application” （自定义应用程序）权限。
- 对于使用新版 External Credential 的 Named Credential，你可以通过权限集（Permission Sets）来精确控制哪些用户或简档（Profiles）有权执行调用。这是实现最小权限原则（Principle of Least Privilege）的重要手段。
API 限制 (Governor Limits)：
- 使用 Named Credential 并不豁免 Salesforce 的 Apex Callout 限制。每个 Apex 事务中同步调用的总数（默认为 100 次）和累计超时时间（默认为 120 秒）等限制依然适用。
- 务必在设计集成方案时考虑这些限制，必要时使用异步处理（如 Queueable Apex, Future Methods）来处理大量或耗时长的调用。
错误处理与日志记录：
- 网络调用本质上是不可靠的。代码中必须包含健壮的错误处理逻辑。始终检查 `HttpResponse.getStatusCode()` 并为非 2xx 的状态码准备好处理分支。
- 使用 `try-catch` 块来捕获可能发生的 `CalloutException`，例如当 DNS 解析失败或连接超时。
- 建立完善的日志记录机制（例如，使用平台事件或自定义日志对象），记录每次调用的关键信息（请求、响应、状态码），以便于快速排查生产环境中的问题。
命名空间与包管理：
- 如果在受管包（Managed Package）中使用 Named Credential，请注意其命名空间。代码中引用的 Named Credential 名称可能需要包含命名空间前缀，除非你将命名空间从 Named Credential 定义中移除。
自定义请求头：
- Named Credential 允许你配置静态的自定义请求头。这对于传递不常变化的 API 密钥（例如 `x-api-key`）非常有用，可以进一步保持代码的纯净。
- 如果请求头是动态的，你仍然可以在 Apex 代码中通过 `req.setHeader('Header-Name', 'Header-Value')` 来设置。

总结与最佳实践

Named Credential 是 Salesforce 平台上一项革命性的功能，它彻底改变了我们作为集成工程师构建和管理 API 集成的方式。通过将端点和认证信息与业务逻辑代码分离，它极大地提升了集成的安全性、可维护性和可移植性。

以下是我在实践中总结的最佳实践：

杜绝硬编码：永远不要在代码或元数据中硬编码任何端点 URL 或凭证。这是集成的第一原则。始终使用 Named Credential。
优先使用新模式：对于所有新的集成项目，优先采用 External Credential + Named Credential 的组合模式，以获得更强的安全性和灵活性。
环境一致性：在所有环境（开发、测试、生产）中为同一个集成点使用完全相同的 Named Credential API 名称。这样可以确保你的代码无需任何修改即可在不同环境间迁移。只需在每个环境中配置该 Named Credential 指向正确的端点即可。
为 OAuth 2.0 拥抱 Named Credential：对于使用 OAuth 2.0 的集成，Named Credential 是无可替代的最佳选择。它将你从复杂的 Token 管理中解放出来，让你可以专注于核心业务。
实施全面的监控：结合强大的错误处理和日志记录，确保你对集成的健康状况有清晰的了解。当外部服务出现问题时，你能够第一时间发现并响应。

总之，熟练掌握和运用 Named Credential 是每一位 Salesforce 集成工程师的必备技能。它不仅能让你的工作更高效，更能帮助你构建出符合企业级标准的安全、稳健、可扩展的集成解决方案。

Salesforce中文网