api-integration

用途：为 iOS/tvOS 项目的 API 集成提供架构决策框架，而非基础 API 用法教学。Claude 已了解 URLSession 与 Codable，本技能补充的是取舍判断与缓存策略。

主要能力：

1. REST 与 GraphQL 取舍：固定端点选 REST（缓存简单、HTTP 语义原生）；按屏变化查询选 GraphQL；实时订阅可用 GraphQL subscriptions 或 WebSocket+REST；离线优先同步场景 REST 更易做冲突解决。
2. 版本化策略：稳定 API 初期可不版本化；预期破坏性变更用 URL 路径版本（/v1/、/v2/）；渐进迁移用请求头版本（Accept-Version: v2）；多版本并存维护成本高，需谨慎。
3. 缓存策略：静态数据激进缓存（URLCache+ETag，max-age=86400）；用户数据带校验缓存；频繁变化数据短 TTL 或不缓存；支付等实时关键数据不缓存（no-store）。
4. 离线优先：按离线重要程度选择内存缓存、持久化缓存（Core Data/Realm/SQLite）或完整离线优先架构（本地写入、同步队列、冲突解决）。

使用方式：以决策树形式引导选择，并给出服务层、错误处理、分页、重试等模式。核心规范包括：ViewModel 不直接调用 NetworkManager，需经服务层；DTO 不越过服务层，需映射为领域模型；base URL 不硬编码，按环境配置；不向用户展示原始错误，需映射为友好文案；按错误类型分别处理（取消、未授权、无连接）；敏感数据不缓存；缓存需校验新鲜度；分页按需加载，可变列表用游标分页而非 offset；写操作可用幂等键配合重试；后台抓取需配置 UIBackgroundModes 与最小抓取间隔。

适用场景：iOS/tvOS 应用的网络层架构设计、缓存与离线方案选型、API 演进规划。

限制：资料未提供具体安装命令、收费方式、支持平台版本或效果数据，暂未提供。