SaloonPHP v3.11.0 版本发布：类型提示请求断言与响应资源处理增强

项目简介

SaloonPHP 是一个优雅的 PHP HTTP 客户端库，专为构建与 API 交互的应用而设计。它提供了简洁的语法和强大的功能，使开发者能够轻松地创建、发送 HTTP 请求并处理响应。SaloonPHP 特别适合需要与多个 RESTful API 集成的项目，通过其直观的接口和丰富的功能，显著提升了开发效率。

版本亮点

1. 类型提示请求断言

在测试 API 集成时，断言请求是否按预期发送是一个常见需求。v3.11.0 版本引入了对类型提示请求的支持，使得测试代码更加清晰和类型安全。

改进前：

$mockClient->assertSent(function (Request $request) {
    return $request instanceof GetUserRequest;
});

改进后：

$mockClient->assertSent(GetUserRequest::class);

这一改进不仅减少了样板代码，还通过类型系统提供了更好的代码提示和错误检查。开发者现在可以直接传入请求类的类名作为参数，使测试意图更加明确。

2. 响应资源处理方法

新版本为响应对象添加了 resource() 方法，这是一个对处理二进制数据（如图片、PDF 等）特别有用的功能。

使用示例：

$response = $connector->send(new DownloadImageRequest);
$imageResource = $response->resource();

// 可以将资源保存到文件
file_put_contents('image.jpg', $response->resource());

此方法返回响应内容的 PHP 资源流，特别适合处理大文件或需要流式处理的数据，避免了将整个响应内容加载到内存中，提高了内存使用效率。

3. 模拟响应数据合并功能

在测试场景中，经常需要模拟 API 响应。v3.11.0 增强了模拟响应功能，允许开发者合并数据到预定义的模拟响应中。

使用场景：

$mockClient->addMockResponse('get-user', [
    'status' => 200,
    'body' => ['id' => 1, 'name' => 'Sam'],
]);

// 测试中可以覆盖特定字段
$response = $connector->send(new GetUserRequest)->mergeData([
    'name' => 'Sammyjo20'
]);

这个功能使得测试更加灵活，开发者可以在保持大部分模拟数据不变的情况下，只覆盖需要测试的特定字段，减少了测试代码的重复。

技术深度解析

类型提示请求断言实现原理

SaloonPHP 通过反射机制实现了类型提示请求断言。当开发者传入一个类名时，框架会：

1. 检查该类是否是 Saloon\Http\Request 的子类
2. 在请求历史中查找匹配的请求实例
3. 使用 instanceof 操作符进行类型比较

这种方法比回调函数方式更高效，因为减少了闭包创建和调用的开销。

响应资源处理的内存优化

resource() 方法内部使用了 PHP 的流包装器，特别是 php://temp 流。当响应体较大时，SaloonPHP 会自动将内容写入临时流而不是保存在内存中，这种方式：

• 减少了内存占用
• 允许处理超大文件（超过内存限制）
• 支持流式操作（如逐行读取或分块处理）

模拟响应合并的优先级机制

数据合并功能采用了深度合并策略，遵循以下规则：

1. 数字键数组会被替换而不是合并
2. 字符串键数组会递归合并
3. 标量值（字符串、数字等）会被覆盖
4. 空值不会覆盖已存在的非空值

这种策略确保了测试数据可以灵活地部分覆盖模拟响应，同时保持未指定字段的默认值。

升级建议

对于现有项目，升级到 v3.11.0 是平滑的，因为新功能都是向后兼容的增强。建议开发者：

1. 在测试代码中逐步替换回调断言为类型提示断言
2. 对于处理大文件的请求，考虑使用新的 resource() 方法
3. 重构测试用例，利用数据合并功能减少模拟响应定义

总结

SaloonPHP v3.11.0 通过引入类型提示请求断言、响应资源处理和模拟数据合并等功能，进一步提升了 API 集成的开发体验和测试便利性。这些改进不仅使代码更加简洁清晰，还提供了更好的性能和灵活性，特别是对于处理大型数据或复杂测试场景的项目。