在 Flutter 项目中实现、修复或审查网络层时…

当需要为 Flutter/Dart 应用添加或加固网络请求、鉴权、WebSocket 实时通信、缓存与错误处理时，先勘察项目现状再适配实现并验证。

适用场景

解决思路

1. 通过检查 `pubspec.yaml`、`lib/` 以及现有的网络、架构、状态管理、依赖注入、鉴权、持久化和测试约定，确认目标是 Flutter 或 Dart 包。
2. 除非项目尚无网络栈或用户明确要求迁移，否则保留项目当前的客户端栈；把本技能的 `http` 示例适配到已有的 Dio、Retrofit、Chopper、生成式客户端或自定义封装上，而不是新增一个并行客户端。
3. 实现任务中，优先采用小型可注入的 client/service，配合类型化解码函数、明确的超时、显式状态码处理、可取消或可释放的资源，以及可测试的边界。
4. 审查和调试任务中，优先报告：状态码处理缺陷、泄漏的 client 或订阅、不安全的 token 存储、缺失超时、泛化异常、在 UI 线程解析大响应、重复的进行中请求、缺失测试，然后再给宽泛的风格建议。
5. 保持 UI 网络层轻薄：Widget 可以触发命令或观察状态，但 service 负责端点调用，repository 负责数据策略，state 对象/ViewModel 负责 UI 状态转换。
6. 用仓库的常规命令验证：优先 `flutter analyze`、针对性的 `flutter test`，以及对复制的 Dart 资产使用 `dart format --output=none --set-exit-if-changed`；并说明跳过了哪些检查。
7. 仅在项目无法推断出高影响决策时才向用户提问：缺少 API 契约、端点 base URL、鉴权机制或 token 生命周期；实时行为需要产品语义（重连策略、顺序、投递保证、离线行为）；缓存新鲜度、乐观更新、分页或重试策略会改变用户可见的数据正确性；项目已有多个网络栈且目标不明确。
8. 若项目不可用或不是 Flutter 项目，基于给定上下文给出实现计划或审查，不臆造仓库事实，并声明无法执行代码验证。
9. 按需只读取当前任务所需的参考与资产：基础 HTTP CRUD/JSON 模型读 `references/http-basics.md`；鉴权头、token 存储、登录、刷新、OAuth 读 `references/authentication.md`；状态码、异常、超时、重试、UI 错误读 `references/error-handling.md`；大 JSON、缓存、分页、去重、计时读 `references/performance.md`；WebSocket 连接、JSON 消息、重连、鉴权读 `references/websockets.md`；可复用 HTTP service 模板读 `assets/code-templates/http_service.dart`；repository/缓存模板读 `assets/code-templates/repository_template.dart`；独立示例读 `assets/examples/`。
10. 每个复制的资产都必须先适配目标应用的包名、lint、客户端栈、状态管理风格和架构，然后再验证。
11. 仅在新建简单客户端时使用 `http: ^1.6.0` 和 `web_socket_channel: ^3.0.3`；对已有的 Dio、Retrofit、Chopper 或生成式客户端，遵循既有技术栈。
12. 注入 client，而不是在 service 深处构造；关闭自己拥有的 `http.Client`、WebSocket channel、stream subscription、timer 和 text controller。
13. 仅当端点契约允许时才把 `200..299` 视为成功；把 `204` 当作空处理，方法建模为可空或 `void`，而不是使用不安全的强制转换。
14. 在 service/repository 边界把 JSON 解码为类型化模型；大响应用后台 isolate，但小负载避免 isolate 开销。
15. 添加请求超时，并只对瞬时失败重试；除非 API 幂等或用户确认产品策略，否则不要重试不安全的变更操作。
16. 用 `flutter_secure_storage: ^10.0.0` 或应用已有的安全存储保存敏感 token；不要把 access token 存入源码、`shared_preferences`、日志或崩溃报告。
17. WebSocket 使用 `wss://`；通过 `IOWebSocketChannel` 设置自定义 WebSocket 头仅限 IO，需为 Flutter web 提供浏览器兼容的替代方案。
18. 不要用 `package:http` 手动把 `Accept-Encoding` 设为默认值；除非项目有实测需求，否则让平台/客户端协商压缩。
19. 完成实现或审查前检查：端点调用位于可测试的 service 或 repository 之后，UI 代码不持有原始 HTTP/WebSocket 细节。
20. 检查每个请求都有状态码处理、超时/错误处理，以及类型化解析或显式的原始响应契约。
21. 检查鉴权密钥按应用已有的安全存储和生命周期规则进行存储与刷新。
22. 检查被改动代码所拥有的 client、channel、subscription、controller 和 timer 都在适当时机释放。
23. 运行最接近的可用验证：`flutter analyze`；针对改动的网络/鉴权/repository 代码运行聚焦的 `flutter test` 套件；对复制的 Dart 资产运行 `dart format --output=none --set-exit-if-changed`；改动捆绑示例或模板时运行本技能的 `scripts/verify-examples.sh`。
24. 报告运行的命令、失败项、跳过的检查和残留的网络风险。

适用边界 · 注意事项

• 项目不可用或不是 Flutter/Dart 项目时，无法执行代码验证，只能给出计划或审查。
• 项目已有多个网络栈且目标不明确时，不应擅自选择或新增客户端。
• 缺少 API 契约、base URL、鉴权机制或 token 生命周期等高影响信息时，不应臆造事实直接实现。