微服务SDK需明确通信协议与序列化格式、动态服务发现、分层错误处理、内置mock模式及受控可观测性。必须显式声明依赖、通过接口解耦服务解析、区分Network/Protocol/Business异常、mock时全链路绕过真实调用并屏蔽日志监控。
微服务SDK必须明确通信协议和序列化格式
微服务调用 SDK 不是普通工具包，它直接决定服务间能否正确收发数据。硬编码 HTTP + JSON 是最常见起点，但别默认假设对方用 cURL 或 Guzzle —— 你得在 composer.json 的 require 里显式声明依赖，比如 "guzzlehttp/guzzle": "^7.5"。如果目标服务走 gRPC，就得引入 grpc/grpc 和 google/protobuf，并提前确认 PHP 扩展 grpc 和 protobuf 已启用。
序列化也容易踩坑：PHP 的 json_encode() 默认不处理 DateTime 对象，直接传会抛 TypeError；若服务要求 ISO8601 时间字符串，得统一在请求前调用 $dt->format('c')。同理，空数组 vs 空对象、null 字段是否透传，都得在 SDK 初始化时通过配置项控制，而不是写死。
服务发现与地址管理不能写死在类里
把服务地址写成 https://user-service:8080 这种字符串，等于给 SDK 判了“死刑”。真实环境里，服务可能注册在 Nacos、Consul 或 Eureka，IP 和端口动态变化。正确做法是预留接口，比如定义一个 ServiceResolverInterface：
interface ServiceResolverInterface
{
public function resolve(string $serviceName): string; // 返回 http://ip:port
}
用户可自行实现，或提供开箱即用的 Consul 实现（需额外 require php-http/curl-client 和 consul-php-sdk）。同时，SDK 构造函数应接受该 resolver 实例，而非自己 new 出来 —— 否则无法 Mock 测试，也无法切换策略。
- 不要在
__construct()里直接调用file_get_contents("http://consul:8500/v1/health/service/user") - 避免使用全局变量或静态方法读取配置，这会让单元测试隔离失败
- 若项目用 Laravel，可绑定 resolver 到容器，让 SDK 自动注入
错误处理必须区分网络层、协议层、业务层
微服务调用失败有三层原因：DNS 解析失败（网络层）、HTTP 502（网关层）、JSON 响应里 "code":500（业务层）。SDK 如果只抛一个 Exception，上层根本没法做针对性重试或降级。
建议分三类异常类：NetworkException、ProtocolException、BusinessException，全部继承自统一基类 MicroserviceException。再配合返回值结构体，例如：
class ApiResponse
{
public int $httpCode;
public ?array $body = null;
public ?string $error = null;
public ?MicroserviceException $exception = null;
}
这样调用方能清晰判断：HTTP 状态码非 2xx 就是协议问题；$response->body['code'] !== 200 才是业务错误；而 $response->exception instanceof NetworkException 就该触发熔断。
本地开发调试时必须支持 mock 模式
没连通真实微服务前，你不可能靠改 hosts 或起一堆 Docker 容器来跑通 SDK。必须内置 mock 开关，比如构造函数加一个 $mock = false 参数，为 true 时跳过所有网络请求，直接返回预设响应：
$sdk = new UserServiceSdk($resolver, mock: true); $user = $sdk->getUser(123); // 返回固定数组，不发 HTTP 请求
这个开关要贯穿整个调用链：mock 模式下，服务发现、HTTP 客户端、序列化、反序列化全 bypass。否则某处漏掉一个 new DateTime()，就可能因时区或格式报错，干扰真实逻辑验证。
最容易被忽略的是日志和监控埋点 —— mock 模式下这些代码仍会执行，可能往 ELK 写脏数据、向 Prometheus 上报假指标。务必检查所有可观测性代码是否受 mock 开关控制。
