深入理解tebru/retrofit-php的高级用法

Retrofit-PHP是一个强大的REST客户端库，它简化了与HTTP API的交互过程。在前一篇文章中我们已经介绍了基本用法，本文将深入探讨Retrofit-PHP的高级特性，帮助开发者更好地定制和优化API调用。

缓存机制优化

默认情况下，Retrofit-PHP不会进行任何文件系统缓存。但在生产环境中，启用缓存可以显著提升性能表现。

Retrofit::builder()
    ->setCacheDir(__DIR__.'/cache')  // 设置缓存目录
    ->enableCache();                 // 启用缓存功能

技术要点：

• 缓存目录需要有可写权限
• 缓存策略遵循HTTP标准缓存控制头
• 缓存可以有效减少重复请求的网络开销

自定义数据转换器

Retrofit-PHP默认只能处理字符串类型和PSR-7的StreamInterface。通过自定义转换器，我们可以扩展支持更多数据类型。

Retrofit::builder()
    ->addConverterFactory(new CustomConverterFactory());

转换器实现要求：

1. 必须实现Tebru\Retrofit\ConverterFactory接口
2. 需要处理三种转换场景：
   • 将任意类型转换为字符串
   • 将请求体转换为流
   • 将响应流转换为目标类型
3. 通过返回null可以让系统跳过当前转换器

类型识别： 转换器会接收到TypeToken对象，开发者可以通过它来判断参数的具体类型。

现有解决方案： 目前官方提供了Gson转换器，可以处理更复杂的数据结构转换：

composer require tebru/retrofit-php-converter-gson

自定义HTTP客户端

Retrofit-PHP本身不包含HTTP请求实现，需要开发者自行集成。目前官方支持Guzzle 6客户端：

composer require tebru/retrofit-php-http-guzzle6

集成方式：

Retrofit::builder()
    ->setHttpClient(new Guzzle6HttpClient(new Client()));

客户端要求：

• 必须实现Tebru\Retrofit\HttpClient接口
• 需要支持同步和异步请求方式
• 使用PSR-7请求对象作为参数

自定义调用适配器

默认情况下，Retrofit-PHP会直接返回Call对象。通过自定义调用适配器，我们可以改变服务方法的返回类型。

实现步骤：

1. 创建实现Tebru\Retrofit\CallAdapter接口的适配器
2. 创建实现Tebru\Retrofit\CallAdapterFactory接口的工厂类

示例场景： 假设我们想集成RxPHP，可以这样定义服务接口：

/**
 * @GET("/")
 */
public function test(): Observable;

然后配置适配器工厂：

Retrofit::builder()
    ->addCallAdapterFactory(new RxCallAdapterFactory());

工厂类实现要点：

• supports()方法判断是否支持目标类型
• create()方法返回对应的适配器实例

适配器负责将Call对象包装成目标类型（如Observable）并返回。

自定义代理实现

在某些特殊场景下，我们可能需要修改默认的HTTP请求行为：

1. 测试环境需要模拟API响应
2. API尚未开发完成，需要从其他来源获取数据
3. 需要添加统一的请求/响应处理逻辑

实现方式：

Retrofit::builder()
    ->addProxyFactory(new CustomProxyFactory());

代理要求：

• 必须实现服务接口
• 可以选择性实现\Tebru\Retrofit\DefaultProxyFactoryAware接口
  • 这样可以获取默认代理实现
  • 只覆盖特定方法，其余委托给默认代理

典型应用场景：

• 单元测试中的API模拟
• 开发环境下的假数据生成
• 请求/响应的统一日志记录
• API调用的性能监控

总结

Retrofit-PHP通过灵活的可扩展设计，为开发者提供了丰富的定制能力。无论是数据转换、HTTP客户端集成、返回类型适配还是代理控制，都可以通过简单的接口实现来满足各种复杂场景的需求。掌握这些高级用法，将帮助开发者构建更加健壮和高效的API客户端应用。