Salesforce Named Credentials 深度解析：构建安全、简化的 API 集成

十月 26, 2025

背景与应用场景

作为一名 Salesforce 集成工程师，我的日常工作核心就是连接 Salesforce 与外部世界。无论是与公司内部的 ERP 系统同步数据，还是调用第三方的天气、支付、地图 API，可靠且安全的认证和连接机制是所有集成项目的基石。在早期，开发人员常常将 API 的终端点 (Endpoint URL) 和认证信息（如密码、API 密钥）硬编码在 Apex 代码中，或者存储在自定义设置 (Custom Settings) / 自定义元数据 (Custom Metadata) 中。这种方式存在诸多弊病：

安全风险：认证凭证以明文或易于访问的形式存储在代码或元数据中，一旦代码泄露或配置被未授权用户访问，将导致严重的安全漏洞。
维护困难：当外部系统的 URL 发生变更，或者 API 密钥需要轮换时，我们必须修改代码或元数据，然后经过完整的测试和部署流程。这在多环境（沙盒、生产）管理的场景下，会变得异常繁琐和易错。
缺乏灵活性：代码与配置紧密耦合，使得集成逻辑难以复用和扩展。例如，从沙盒切换到生产环境时，需要手动更改所有相关的终端点。

为了解决这些痛点，Salesforce 推出了 Named Credentials（命名凭证）这一强大功能。它允许我们将 API 终端点的 URL 和认证信息从代码中分离出来，通过 Salesforce UI 进行集中、安全的声明式管理。这彻底改变了我们构建集成的范式，使得 API 调用 (Callout) 变得前所未有的安全、简洁和易于维护。

应用场景包括但不限于：

连接到一个需要 Basic Authentication (用户名/密码) 的内部 RESTful 服务。
与支持 OAuth 2.0 协议的外部服务（如 Google, Microsoft, 或其他 Salesforce org）进行集成，Salesforce 会自动处理复杂的 token 获取和刷新流程。
调用公共的、无需认证的 API，同时利用 Named Credentials 统一管理所有外部服务的端点。
在不同环境下（开发、测试、生产）无缝切换 API 端点，无需修改任何一行 Apex 代码。

原理说明

Named Credentials 的核心思想是“解耦”——将“去哪里”（URL）和“如何证明我是谁”（Authentication）这两个问题从业务逻辑代码中剥离出来。它由两个紧密协作的部分组成：External Credential (外部凭证) 和 Named Credential (命名凭证)。

这是一个现代的设计，在旧版本中，认证信息直接配置在 Named Credential 上。现在，最佳实践是：

External Credential (外部凭证): 这是存储认证细节的地方。它定义了“如何认证”，包含了认证协议（如 OAuth 2.0, Basic Auth）以及所需的具体参数（如 Client ID, Client Secret, Username, Password, Scope 等）。它还定义了 Principal (主体)，即谁在使用这个凭证，这可以是整个组织（Named Principal），也可以是每个用户自己（Per User）。
Named Credential (命名凭证): 这是 Apex 代码中实际引用的标识符。它指向一个 External Credential 来获取认证方法，并定义了外部服务的根 URL。当你在 Apex 代码中使用 callout:My_Named_Credential 语法时，Salesforce 在后台执行以下操作：
1. 查找名为 `My_Named_Credential` 的 Named Credential 配置。
2. 获取其配置的根 URL。
3. 找到其关联的 External Credential。
4. 根据 External Credential 中定义的认证协议（例如 OAuth 2.0），自动处理认证流程。如果是一个 OAuth 2.0 凭证，Salesforce 会检查是否存在有效的 Access Token。如果没有或已过期，它会自动执行 Refresh Token 流程来获取一个新的 Access Token。
5. 将获取到的凭证（如 Access Token 或 Basic Auth 字符串）自动构建成一个标准的 Authorization HTTP Header。
6. 将所有这些信息与 Apex 代码中发起的 `HttpRequest` 合并，最终向目标地址发起一个经过完全认证的请求。

这个过程对开发人员是完全透明的。我们不再需要在代码中手动拼接 URL、管理密码或处理复杂的 OAuth 2.0 握手和 token 刷新逻辑。我们只需简单地告诉 Salesforce：“请使用 `My_Named_Credential` 去调用这个路径”，剩下的一切都由平台自动处理。

关键概念：

Identity Type (身份类型):
- Named Principal (指定主体): 整个组织共享一套认证凭证。适用于系统对系统的集成，例如 Salesforce 向一个公司内部的订单系统查询信息。
- Per User (每位用户): 每个 Salesforce 用户都需要独立向外部系统进行一次认证授权。适用于代表用户执行操作的场景，例如一个应用需要访问每个用户自己的 Google Drive 文件。
Authentication Protocol (认证协议):
- No Authentication: 用于公共 API。
- Password Authentication: 即 HTTP Basic Authentication，使用用户名和密码。
- OAuth 2.0: 行业标准的安全授权协议，支持多种授权流程 (Grant Types)。这是最推荐的方式，因为 Named Credentials 会自动管理 token 的生命周期。
- JWT (JSON Web Token) Bearer Flow 和 JWT Token Exchange: 更高级的认证流程，适用于特定的企业级集成场景。

示例代码

假设我们已经通过 Salesforce UI 创建了一个名为 `My_Legacy_API` 的 Named Credential，它指向的 URL 是 `https://api.example.com`，并配置了相应的认证信息。现在，我们想通过 Apex 调用该服务的 `/orders/123` 路径。

以下代码示例严格遵循 Salesforce 官方文档，展示了如何使用这个 Named Credential 发起一个 GET 请求。

发起一个 GET 请求

// 引用自 Salesforce 开发者文档 Apex Developer Guide
// 主题: Execute a Callout Using a Named Credential

// 1. 创建一个 HttpRequest 对象
HttpRequest req = new HttpRequest();

// 2. 设置终端点 (Endpoint)
//    这是 Named Credentials 的核心语法: 'callout:{Named Credential API Name}/{path}'
//    Salesforce 会自动将 'callout:My_Legacy_API' 替换为配置的 URL 'https://api.example.com'
//    最终请求的完整 URL 将是 'https://api.example.com/orders/123'
req.setEndpoint('callout:My_Legacy_API/orders/123');

// 3. 设置 HTTP 方法
req.setMethod('GET');

// 4. (可选) 设置请求头，注意：Authorization 头由 Salesforce 自动处理，无需手动设置
req.setHeader('Content-Type', 'application/json');

// 5. 创建 Http 对象实例，用于发送请求
Http http = new Http();

// 6. 发送请求并获取 HttpResponse 对象
//    在发送之前，Salesforce 会自动完成认证并添加 Authorization 头
HttpResponse res = http.send(req);

// 7. 处理响应
// 检查 HTTP 状态码是否为 200 (OK)
if (res.getStatusCode() == 200) {
    // 成功，处理响应体 (response body)
    System.debug('响应成功: ' + res.getBody());
    // 在实际应用中，这里应该是反序列化 JSON 并处理业务逻辑
    // Map results = (Map) JSON.deserializeUntyped(res.getBody());
} else {
    // 失败，记录错误信息
    System.debug('请求失败，状态码: ' + res.getStatusCode());
    System.debug('错误信息: ' + res.getBody());
}

正如你所见，代码中完全没有出现任何 URL、用户名、密码或 Token。代码非常干净，只关注于业务逻辑（调用哪个路径，发送什么数据），而将所有与环境和安全相关的配置都交给了 Salesforce 平台管理。

注意事项

作为集成工程师，在实施基于 Named Credentials 的解决方案时，必须考虑以下几点：

权限管理 (Permissions):
- 创建和修改 Named/External Credentials 需要特定的管理员权限，如 “Customize Application” 和 “Manage Named Credentials” / “Manage External Credentials”。
- 访问控制至关重要。通过 Profile (简档) 或 Permission Set (权限集) 中的 External Credential Principal Access 设置，可以精确控制哪些用户或用户组有权通过 Apex 代码使用特定的 Named Credential。这遵循了最小权限原则 (Principle of Least Privilege)。
API 限制 (API Limits):
- Named Credentials 极大地简化了调用过程，但它不会绕过 Salesforce 的 Governor Limits。每次 `http.send(req)` 仍然会消耗一个 Callout 限制（同步 Apex 中每个事务最多 100 次）。
- 请求超时（默认为 10 秒，最大 120 秒）和堆大小 (Heap Size) 等限制依然适用。
错误处理 (Error Handling):
- 集成项目中最容易被忽视但最关键的部分就是错误处理。网络可能中断，远端服务器可能宕机，认证凭证可能失效。
- 必须将 `http.send()` 调用包裹在 `try-catch` 块中，以捕获 `System.CalloutException`，这通常表示网络层面的问题（如 DNS 解析失败、连接超时）。
- 即使请求成功发送，也要仔细检查 `HttpResponse` 的状态码 (`getStatusCode()`)。状态码 401/403 通常表示认证/授权失败，404 表示资源未找到，5xx 系列表示服务器端错误。你的代码必须能够优雅地处理这些非 2xx 的响应。
命名空间 (Namespaces):
- 如果你在开发一个托管包 (Managed Package)，在引用 Named Credential 时需要包含命名空间前缀，格式为 `callout:namespace__Credential_Name/path`。
Callout from Triggers:
- Salesforce 禁止在触发器 (Trigger) 的同步执行上下文中直接进行 Callout。这是为了防止一个 DML 操作因为等待外部服务而长时间锁定数据库记录。
- 如果需要在触发器逻辑中执行 Callout，必须将其放入异步方法中，例如使用 `@future(callout=true)` 注解的方法，或者一个 Queueable Apex 作业。

总结与最佳实践

Named Credentials 是 Salesforce 平台上进行 API 集成的基石。它不仅仅是一个方便的工具，更是一种体现了安全、可维护和可扩展架构思想的最佳实践。

作为一名 Salesforce 集成工程师，我强烈推荐遵循以下最佳实践：

始终使用 Named Credentials: 彻底告别在代码或自定义元数据中硬编码 URL 和凭证的坏习惯。对于任何对外的 HTTP Callout，都应该通过 Named Credential 来管理。
优先使用 External Credentials: 拥抱最新的架构，将认证细节封装在 External Credential 中，让 Named Credential 专注于定义端点 URL。这提高了认证逻辑的复用性。
选择最安全的认证协议: 只要外部服务支持，就应优先选择 OAuth 2.0。它比 Basic Authentication 更安全，并且 Salesforce 会为你处理繁琐的 Token 管理。
构建弹性的集成逻辑: 你的代码必须假定外部调用随时可能失败。实现健壮的错误处理、日志记录和重试机制（在适合的场景下，例如使用 Queueable Apex）。
精细化权限控制: 不要向所有用户开放所有集成点。使用权限集来确保只有需要访问特定外部服务的用户才能使用对应的 Named Credential。

总之，熟练掌握和运用 Named Credentials，是每一位 Salesforce 专业人员，特别是我们集成工程师，构建企业级、安全可靠的集成解决方案的核心技能。它将配置与代码分离，让管理员可以轻松管理环境，让开发人员可以专注于业务逻辑，最终交付出更稳定、更安全的系统。

Salesforce中文网