为什么要重构

最近我把一个老的 App Store Connect API 项目做了完整重构。
这个项目最初是“能用就行”的风格：每个接口一个脚本，逻辑直连，改动快，但随着需求增多，维护成本急剧上升。

当我准备继续扩展功能时，发现继续在旧结构上“打补丁”已经不划算了。
于是我做了一个决定：不做小修小补，直接做一次结构性重构。

重构前的核心问题

重构前主要有这几个痛点：

• 接口实现分散，很多脚本都在重复相似代码
• 请求 Apple API 的逻辑分布在多个地方，错误处理不统一
• 鉴权方式不一致，安全边界模糊
• 参数校验薄弱，调用失败时错误信息不稳定
• 新增接口的成本高，容易复制粘贴出隐性 Bug
• 项目几乎没有测试和规范文档，协作门槛高

一句话总结：功能能跑，但系统不可持续演进。

重构目标

这次重构的目标很明确：

1. 统一为 REST 风格，建立清晰路由体系
2. 建立分层结构，拆分控制器、服务、HTTP 基础能力
3. 强化鉴权策略，只允许 Authorization Bearer 方式
4. 增强参数校验和错误返回，保证接口行为可预期
5. 一次性扩展更多 App Store Connect 能力
6. 补齐 OpenAPI 和测试基线，让项目“可交付、可协作、可演进”

重构方案：从脚本堆叠到分层架构

重构后的项目采用的是“单入口 + 路由 + 控制器 + 服务层”的结构。

1) 入口与路由统一

所有请求先进入统一入口，再由路由分发到对应控制器。
这样做的价值是：

• 入口层可以集中处理请求 ID、错误兜底、响应格式
• 路由表成为 API 能力总览，定位功能更快
• 新接口只需要“加路由 + 加控制器方法”，扩展路径清晰

2) 控制器只做协议转换

控制器层只负责：

• 读取请求参数
• 做必要校验
• 调用服务层
• 返回标准响应

业务细节不堆在控制器里，后续维护明显更轻松。

3) 服务层承接核心能力

服务层拆成几个关键模块：

• Apple API Client：统一封装对上游 API 的调用
• JWT 服务：统一生成 App Store Connect JWT
• 签名服务：专门负责 ES256 签名逻辑
• Validation：集中参数规范与校验规则

这一步把原来“到处散落的逻辑”变成了“单一职责组件”。

4) 响应与错误统一

我统一了成功和失败的返回结构，并引入请求 ID。
价值很直接：

• 前端和调用方处理逻辑更简单
• 排查问题时可以按请求 ID 快速追踪
• 错误码和错误信息更稳定，不再“看心情返回”

功能扩展：不仅重构，还补齐能力

这次不是只“搬家”，而是边重构边扩容。
我把常见的 App Store Connect 操作都纳入了统一网关，包括：

• Token 生成
• Apps 查询与版本查询
• Devices 增删改查
• Bundle IDs 增删改查
• Certificates 查询与删除
• Profiles 查询、创建、删除
• TestFlight 相关查询
• App Store Version Localizations 查询、创建、更新

这意味着项目从“少量脚本接口”升级为“可扩展的 API 网关底座”。

工程化补齐：从可用到可交付

除了业务代码，我还补了三块关键能力：

• OpenAPI 规范：让接口能力可视化、可协作
• PHPUnit 测试基线：先把最关键的校验逻辑跑起来
• Composer 依赖管理与忽略规则：让环境和仓库更干净

这一步的核心价值不是“看起来专业”，而是后续每次改动都更可控。

一个明确的取舍：直接升级，不保留旧兼容层

我这次选择了“直接升级”路线，没有保留旧的脚本接口兼容层。
原因是：

• 旧接口设计本身已经限制后续演进
• 继续兼容会把复杂度长期留在系统里
• 团队当前阶段更需要干净架构，而不是历史包袱

所以这次是一次明确的破坏性重构。
我也在文档里补了旧到新的迁移映射，降低迁移成本。

重构过程里踩过的坑

重构过程中最大的非代码问题是环境：

• 本机 Composer 不可用
• 证书路径配置异常导致安装失败

最终通过本地 Composer 方案和证书路径修正解决。
这个过程也提醒我：工程化不仅是代码结构，也包括可复现的开发环境。

最终效果

项目从“脚本集合”变成了“可持续演进的 API 产品”。

最明显的变化：

• 新增接口变快了
• 代码定位变清晰了
• 错误排查变直接了
• 协作沟通成本降低了
• 后续接 CI、加集成测试、做版本化都更顺畅