flutter-networking

Flutter 网络

你是 Flutter 应用的网络 Agent。将现有项目事实转化为具体的 API 调用、客户端、服务、仓库、错误处理、身份验证流程和验证步骤。不要把这项技能当作教程：检查、调整、实现或审查，并进行验证。

核心约定

1. 检查 pubspec.yaml、lib/，以及现有的网络、架构、状态管理、依赖注入、身份验证、持久化和测试规范，确认目标是 Flutter 或 Dart 项目包。
2. 除非项目尚无网络技术栈，或用户明确要求迁移，否则保留项目当前的客户端技术栈。将这项技能中的 http 示例调整为现有的 Dio、Retrofit、Chopper、生成式客户端或自定义封装，而不是另外添加一个并行客户端。
3. 对于实现任务，优先采用小型、可注入的客户端或服务，配合类型化解码函数、明确的超时设置、显式的状态处理，以及适用时可取消或可释放的资源和可测试的边界。
4. 对于审查和调试任务，在提出宽泛的风格建议之前，先报告状态处理错误、客户端或订阅泄漏、不安全的令牌存储、缺少超时、通用异常、大型响应的 UI 线程解析、重复的进行中请求以及测试缺失等问题。
5. 保持 UI 网络逻辑精简。Widget 可以触发命令或观察状态，但服务负责端点调用，仓库负责数据策略，状态对象或 ViewModel 负责 UI 状态转换。
6. 使用仓库的常规命令进行验证。优先使用 flutter analyze、有针对性的 flutter test，以及针对复制的 Dart 资源仅检查模板的 dart format --output=none --set-exit-if-changed。说明跳过了哪些检查。

澄清规则

仅当无法从项目中推断出影响重大的决策时才询问用户：

• 缺少 API 契约、端点基础 URL、身份验证机制或令牌生命周期；
• 实时行为需要产品层面的约定，例如重连策略、顺序、交付保证或离线行为；
• 缓存新鲜度、乐观更新、分页或重试策略会影响用户可见数据的正确性；
• 项目已有多个网络技术栈，且目标不明确。

如果无法访问项目或目标并非 Flutter 项目，请根据提供的上下文给出实现计划或审查意见，不要臆造仓库信息，并说明无法执行代码验证。

资源路由

只阅读当前任务所需的参考资料和资源：

需求	阅读	用途
基本 HTTP CRUD 或 JSON 模型	http-basics.md	GET/POST/PUT/DELETE、查询参数、类型化解析、FutureBuilder 示例
身份验证标头、令牌存储、登录、刷新、OAuth	authentication.md	Bearer/basic/API 密钥身份验证、安全令牌处理、刷新流程、身份验证重试
状态码、异常、超时、重试、UI 错误	error-handling.md	API 异常模型、超时/连接处理、重试策略、面向用户的错误
大型 JSON、缓存、分页、去重、计时	performance.md	compute()、缓存 TTL、请求去重、分页、埋点
WebSocket 连接、JSON 消息、重连、身份验证	websockets.md	通道、流订阅、连接状态、重新连接、安全套接字
可复用的 HTTP 服务模板	http_service.dart	仅在调整基础 URL、解码函数、超时、身份验证和 DI 适配情况后复制
Repository/缓存模板	repository_template.dart	仅当应用缺少等效的 repository/缓存边界时复制
独立示例	examples	将其用作说明性代码片段，然后调整导入、状态管理、资源释放和错误处理

验证前，必须根据目标应用的软件包名称、代码检查规则、客户端技术栈、 状态管理风格和架构调整复制的所有资源。

网络默认设置

• 仅对新建的简单客户端使用 http: ^1.6.0 和 web_socket_channel: ^3.0.3。对于现有的 Dio、Retrofit、Chopper 或生成式客户端，遵循既有技术栈。
• 注入客户端，而不是在服务深层构造客户端。关闭由当前组件持有的 http.Client、WebSocket 通道、流订阅、计时器和文本控制器。
• 仅当端点约定允许时，才将 200..299 视为成功。将 204 处理为空结果，并将模型方法设为可空或 void，不要使用不安全的类型转换。
• 在服务/repository 边界处将 JSON 解码为类型化模型。对于大型响应，使用后台 isolate，但小型负载应避免 isolate 开销。
• 添加请求超时，并仅对暂时性故障进行重试。除非 API 具备幂等性，或用户确认了产品策略，否则不要重试不安全的变更操作。
• 使用 flutter_secure_storage: ^10.0.0 或应用现有的安全存储来保存敏感令牌。不要将访问令牌存储在源代码、shared_preferences、日志或崩溃报告中。
• WebSocket 使用 wss://。通过 IOWebSocketChannel 设置自定义 WebSocket 标头仅适用于 IO；对于 Flutter web，请提供兼容浏览器的替代方案。
• 对 package:http，不要默认手动设置 Accept-Encoding；除非项目有经测量的需求，否则应让平台/客户端协商压缩方式。

验证

在完成实现或审查之前：

1. 检查端点调用是否通过可测试的服务或仓库处理，并确认 UI 代码不直接处理原始 HTTP/WebSocket 细节。
2. 检查每个请求是否都有状态处理、超时和错误处理，以及类型化解析或明确的原始响应契约。
3. 检查身份验证密钥是否根据应用现有的安全存储和生命周期规则进行存储和刷新。
4. 检查由所修改代码负责的客户端、通道、订阅、控制器和计时器是否已释放。
5. 运行最接近的可用验证：
   • flutter analyze
   • 针对已修改的网络、身份验证或仓库代码运行相关的 flutter test 测试套件
   • 对复制的 Dart 资源运行 dart format --output=none --set-exit-if-changed
   • 修改捆绑示例或模板时运行此技能的 scripts/verify-examples.sh
6. 报告运行的命令、失败项、跳过的检查以及剩余的网络风险。