现代化 WidgetKit 项目工程实践
概述
WidgetKit 让小组件以后台快照形式展示数据，但现代化项目需要在模块拆分、工程化工具、刷新预算与测试之间做取舍。
WidgetKit 小组件是后台快照而非实时视图
WidgetKit 在后台调用 TimelineProvider 生成一组 TimelineEntry，系统按策略将其渲染为静态快照并按时间线展示。 小组件没有 ViewModel 生命周期，除点击跳转宿主应用外不响应用户交互。 因此 MVVM 的观察与命令语义在 Widget Extension 中并不适用，状态只能通过 Entry 传递，视图应保持为纯函数式渲染。
见：WidgetKit | Apple Developer Documentation
用 Local Swift Package 承载宿主应用与扩展的共享代码
Widget Extension 与宿主应用共享模型、Provider 与网络协议时，应避免手动维护 Compile Sources 成员关系。
将共享代码抽成 Local Swift Package，两个 target 通过 .package(path:) 依赖同一产物，可以统一 public 访问级别、独立版本演进，
并直接在 Xcode 测试 target 中 @testable import 验证。
见：Organizing Your Code with Local Packages | Apple Developer Documentation
WidgetKit 项目的工程化工具链组合
现代化 WidgetKit 项目通常需要：Tuist 生成 .xcodeproj 以避免手动维护 target 与 entitlements；SwiftLint 与 SwiftFormat 统一风格并捕获常见错误；
Makefile 封装 build/test/lint/format/generate/i18n 等本地指令；BartyCrouch 同步 NSLocalizedString 到 .strings 文件。
这套组合把重复配置收敛到 manifest 与脚本中，降低多人协作时工程结构漂移的风险。
见：Tuist
Observable Macro 的收益应落在宿主应用而非小组件扩展
@Observable 适合管理宿主应用配置表单的多字段状态与副作用。
Widget Extension 没有 ViewModel 生命周期，也不存在用户交互驱动状态变化，引入 Observable 层只会增加无意义的 ceremony。
小组件的数据流应保持单一：配置文件 → TimelineProvider → Provider.fetchUsage → Entry → View。
见：Managing Model Data in Your App | Apple Developer Documentation
WidgetKit 刷新预算决定 Timeline 周期不能过短
macOS 对 reloadAllTimelines() 与 Timeline policy 驱动的刷新有系统级预算，约 40 次/天。
设置 10 分钟周期在理想情况下每天 144 次，但会被系统节流；过短的周期反而增加被静默降级的风险。
临近重置窗口时可考虑自适应缩短间隔，但实时提醒应通过宿主应用的本地通知而非小组件刷新实现。
见：Keeping a Widget Up to Date | Apple Developer Documentation
Widget Extension 的配置共享需要原子写入与沙盒例外
宿主应用写入配置文件后，扩展通过沙盒临时例外读取。由于扩展可能在后台快照时并发读取，
保存应使用 data.write(to:options:.atomic) 避免读到截断 JSON。
长期应迁移到 App Group 容器或文件选择器，当前文件系统方案在项目规模有限时是简单折中。
见：App Sandbox | Apple Developer Documentation
WidgetKit 项目的测试应聚焦行为而非 UI 快照
WidgetKit 快照测试面临 family × appearance × locale 组合爆炸，工程化初期不宜投入。 优先测试可验证行为：Provider JSON 解析、配置编解码、颜色阈值、utilization 钳制、Timeline policy。 网络层通过协议注入 mock，避免真实请求；Widget Extension 本身的超时与内存预算也应在设计时考虑，但不必在单元测试中模拟。
见：Testing Your App | Apple Developer Documentation
Widget Extension 的凭证应避免随配置文件明文分发
Widget Extension 与宿主应用共享配置时，不应把 API key、OAuth token 或 session cookie 等凭证以明文形式放在双方都能读取的配置 JSON 中。 macOS 上长期应使用 Keychain（可配合 shared access group）或 App Group 内的安全封装存储；本地开发若临时使用文件，应设置 0600 权限并尽快迁移。
见：Keychain Services | Apple Developer Documentation
WidgetKit 数据流应保持单向与可注入
配置文件变更后，宿主应用调用 WidgetCenter.shared.reloadAllTimelines() 触发刷新。
TimelineProvider 读取配置、分发到当前选中的 Provider、将结果转换为 TimelineEntry。
错误信息应通过 Entry.error 展示给用户，而非仅写入日志。
整个链路中，网络层与配置加载器应通过协议注入，以便在单元测试中替换为 mock 或临时路径。