Retrofit-PHP 从 2.x 升级到 3.x 的技术解析与迁移指南

前言

Retrofit-PHP 3.x 版本是对 2.x 版本的全面重构，旨在使其更贴近 Square 原版 Retrofit 的设计理念。这个版本带来了许多架构层面的重大变更，虽然升级路径并不平滑，但新版本在灵活性、性能和开发体验上都有显著提升。

架构变更对比

2.x 版本工作流程

1. 收集所有服务类名
2. 读取注解并生成对应的 PHP 代码
3. 将生成的代码缓存到文件系统
4. 使用 RestAdapterBuilder 构建 RestAdapter 实例
5. 通过 RestAdapter 从文件系统加载服务类并返回实例
6. 调用服务方法发起 HTTP 请求
7. 根据注解返回预期的响应

3.x 版本工作流程

1. 使用 RetrofitBuilder 构建 Retrofit 实例
2. 通过 Retrofit 根据接口类名获取代理对象
3. 动态生成实现指定接口的代理对象
4. 调用代理对象方法，内部读取注解并返回 Call 对象
5. 使用 Call 对象同步或异步执行请求，返回 Response 对象
6. 根据请求成功/失败从 Response 对象获取反序列化的响应体

新版本优势详解

1. 无文件系统写入：除非显式启用缓存，否则不会写入文件系统，解决了开发中接口变更导致的问题。

2. 全异步支持：所有请求都可以异步执行，不再需要在方法签名中定义回调。

3. 响应处理更灵活：可以根据请求成功或失败获取不同的反序列化响应体。

4. 更好的可测试性：生成的代码量极小且统一，测试更加容易。

主要变更内容

核心特性变更

• 移除了事件系统
• 所有方法必须声明返回类型（如果不使用自定义适配器，必须是 Call 类型）
• 所有方法参数必须指定类型提示
• 通过转换器系统支持所有类型的参数注解映射
• 支持使用自定义注解修改请求

依赖项变更

升级的依赖：

• PHP 最低版本从 5.4 提升到 7.1
• php-parser 从 1.3 升级到 3.0.6

新增的依赖：

• symfony/cache（替换了 doctrine/cache）
• doctrine-annotation-reader
• php-type

移除的依赖：

• jms/serializer 等多项不再需要的依赖

文件结构变更

新增了 Internal 包，包含仅供库内部使用的类。这些类可能在版本间变化，但不会造成 BC 破坏。

移除的目录：

• src/Adapter
• src/Generation
• src/Event 等多个目录

移除的文件：

• 多个与旧架构相关的文件

注解变更详解

变更的注解

• @Body：现在仅适用于 application/json 请求
• @GET/@HEAD/@OPTIONS/@DELETE：不能再与包含请求体的请求一起使用
• @Part：现在专门表示 multipart 请求
• @Query：新增指定数据是否预编码的能力

新增的注解

• @Field：专用于表单编码的请求体
• @Path：新的必需注解，用于映射 URL 占位符到参数
• @REQUEST：通用的 HTTP 请求注解

移除的注解

• @FormUrlEncoded：使用 @Field 替代
• @JsonBody：使用 @Body 替代
• 多个与 jms/serializer 相关的注解

重命名的注解

• @BaseUrl 改为 @Url
• @Returns 改为 @ResponseBody

迁移建议

1. 逐步迁移：建议在新分支上进行迁移，逐步替换旧代码。

2. 类型系统：确保所有方法和参数都有正确的类型提示。

3. 异步处理：重构回调逻辑，使用新的 Call 对象异步处理方式。

4. 测试覆盖：充分利用新版本的可测试性优势，增加测试覆盖率。

结语

Retrofit-PHP 3.x 虽然带来了较大的迁移成本，但其现代化的架构设计和更强大的功能集使得这一升级非常值得。理解新旧版本的差异，按照本文指南进行迁移，可以帮助开发者更顺利地完成升级过程。