Apex 集成与工具完全指南：Callouts、命名凭据、WSDL2Apex、Mock 测试

集成与 Apex 工具

Apex 通过 callout 集成外部 SOAP 和 REST Web 服务。提供 JSON/XML/ZIP 数据格式工具、Crypto 数据安全类、EncodingUtil 编码方法和 Pattern/Matcher 正则表达式工具。

集成能力概览

三种 Callout 类型：SOAP（WSDL 自动生成代理类——WSDL2Apex——强类型封装）、HTTP（GET/POST/PUT/DELETE——RESTful 服务）、异步 Callout（Continuations——避免阻塞 Visualforce 界面）。

前置条件——Remote Site Settings：任何 Apex callout 调用外部站点前，该站点必须注册——否则 callout 失败。Setup → Remote Site Settings → New——输入站点名称和 URL。例外：命名凭据端点不需要远程站点设置。

Callout 基础与远程站点设置

命名凭据：集中管理端点 URL 和认证参数。支持 Basic/API Key/OAuth/JWT/AWS Signature V4 等协议。代码不需要手动设置 Authorization 头部——Salesforce 自动处理。Identity Type：Per User（每个用户自己的凭据）vs Named Principal（共享凭据）。

传统 vs 命名凭据：

// 传统——手动管理认证 + 远程站点
req.setEndpoint('https://api.example.com/data');
req.setHeader('Authorization', 'Bearer ' + getOAuthToken());

// 命名凭据——Salesforce 自动处理
req.setEndpoint('callout:MyCredential/data');

命名凭据：自定义头部与 Merge Fields

自定义头部和请求体：命名凭据支持预配置自定义头部。Generate Authorization Header 自动生成认证头部。Merge Fields：在 URL/头部/请求体中使用 {!sObjectField} 动态引用字段值——如 /api/orders/{!Order.OrderNumber}。运行时自动替换——支持跨对象引用（{!Order.Account.Name}）。注意：不应编码包含 merge fields 的请求体——卡号/CVV 被编码后无法正确替换。最多 100 个 merge fields 每个 callout。

WSDL2Apex：从 WSDL 生成 Apex 类

Setup → Apex Classes → Generate from WSDL。Salesforce 自动生成：请求/响应封装类（complexType → Apex 内部类）、SOAP 端口类（Port.endpoint_x——端点 URL、Port.timeout_x——毫秒、Port.methodName()——调用操作）。

支持：Document/Literal 和 RPC/Encoded 绑定、SOAP 1.1、HTTP 头部（inputHttpHeaders_x / outputHttpHeaders_x）、wsdl:import 和 xsd:import。不支持：SOAP 1.2、MTOM 附件、多端口类型、RPC/Literal、WSDL 2.0、超过 10 层嵌套 complexType。特殊字符转下划线、保留字加 _x 后缀。

测试 SOAP Callouts：WebServiceMock

Test.setMock(WebServiceMock.class, new MyMock()) + 实现 doInvoke——检查 request 参数并设置 response 返回值。DML 可在 Mock 前后执行。异步 Apex 中的 Mock 在 startTest/stopTest 内同步执行。

HTTP Callouts：GET/POST/测试

核心类：Http（send）、HttpRequest（setEndpoint/setMethod/setHeader/setBody/setTimeout/setClientCertificateName）、HttpResponse（getBody/getStatusCode/getHeaders）。HttpCalloutMock：实现 respond(HttpRequest) 返回模拟 HttpResponse。三种方式：自定义类 / StaticResourceCalloutMock（单端点）/ MultiStaticResourceCalloutMock（多端点）。Mock 前后均可 DML。

HttpRequest req = new HttpRequest();
req.setEndpoint('https://api.example.com/data');
req.setMethod('GET');
HttpResponse res = new Http().send(req);
Map data = (Map) JSON.deserializeUntyped(res.getBody());

证书与 Callout 限制

证书：Setup → Certificates and Keys。双向 TLS——Port.clientCertName_x（SOAP）/ req.setClientCertificateName()（HTTP）。Callout 限制：100 个/事务、120s 累计超时、10s 默认单次超时（1-120s 可调）、6MB 同步/12MB 异步大小限制。只读模式期间 callout 仍可用。

异步 Callouts：Continuations

用于 Visualforce——避免长时间 callout 阻塞 UI。流程：创建 Continuation → addHttpRequest(req) 最多 3 个并行 callout → 返回给页面 → 异步完成后回调方法通过 continuation.getResponse(index) 获取响应。State 属性传递上下文。每个 callout 独立 60s 超时。测试：Test.setContinuationResponse() + Test.invokeContinuationMethod()。限制：仅 Visualforce 控制器、不能从触发器/batch/Future 中使用。回调中 controller 变量不自动保留——用 state 对象传递。

从 Remote Site Settings 到命名凭据和 WSDL2Apex——从 Mock 测试到证书管理和 Continuation——Apex 提供完整且安全的工具集来集成外部系统。