yx_net_inspector_flutter/README.md

# YX Net Inspector 🕵️‍♂️

一个功能强大的Flutter网络检查器，带有悬浮调试球。实时监控HTTP请求、响应并调试网络问题。

[![pub package](https://img.shields.io/pub/v/yx_net_inspector.svg)](https://pub.dev/packages/yx_net_inspector)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 功能特性

- 🎯 **悬浮调试球**：非侵入式悬浮球，显示网络统计信息
- 📊 **实时监控**：监控所有HTTP请求和响应
- 🔍 **详细检查**：查看请求/响应头、正文和时间信息
- 📱 **移动端优化**：专为移动端调试设计
- 🎨 **可自定义UI**：可配置的主题和外观
- 🚀 **零依赖**：纯Flutter实现，无外部依赖
- 🔧 **轻松集成**：一行代码集成到现有应用

## 📱 截图预览

| 悬浮球 | 请求列表 | 请求详情 |
|:---:|:---:|:---:|
| ![悬浮球](screenshots/floating_ball.png) | ![请求列表](screenshots/request_list.png) | ![请求详情](screenshots/request_details.png) |

## 🚀 快速开始

### 安装

将以下内容添加到你的 `pubspec.yaml` 文件中：

```yaml
dependencies:
  yx_net_inspector: ^1.0.0
```

### 基本用法

用 `YxNetInspector` 包装你的应用，就可以开始使用了！

```dart
import 'package:yx_net_inspector/yx_net_inspector.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return YxNetInspector(
      child: MaterialApp(
        title: '我的应用',
        home: MyHomePage(),
      ),
    );
  }
}
```

### 高级配置

```dart
YxNetInspector(
  showFloatingBall: true, // 显示悬浮调试球
  ballSize: 60.0, // 悬浮球大小
  ballColor: Colors.blue, // 悬浮球颜色
  showInDebugMode: true, // 仅在调试模式下显示
  showInReleaseMode: false, // 在发布模式下隐藏
  maxLogs: 1000, // 保持的最大日志数量
  child: MaterialApp(
    // 你的应用
  ),
)
```

### Dio 拦截器集成（推荐）

如果你使用 Dio 进行网络请求，可以创建一个自定义拦截器自动记录所有请求：

```dart
// 1. 添加 dio 依赖到 pubspec.yaml
dependencies:
  dio: ^5.0.0
  yx_net_inspector: ^1.0.0

// 2. 创建自定义拦截器
import 'package:dio/dio.dart';
import 'package:yx_net_inspector/yx_net_inspector.dart';

class YxNetInspectorDioInterceptor extends Interceptor {
  final YxNetInspectorController _controller = YxNetInspectorController.instance;

  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    final requestId = '${DateTime.now().millisecondsSinceEpoch}_${options.hashCode}';
    options.extra['yx_request_id'] = requestId;
    options.extra['yx_request_start_time'] = DateTime.now();

    _controller.logRequest(
      id: requestId,
      method: options.method,
      url: options.uri.toString(),
      headers: options.headers.map((k, v) => MapEntry(k, v.toString())),
      requestData: options.data,
      queryParameters: options.queryParameters.isNotEmpty ? options.queryParameters : null,
    );

    super.onRequest(options, handler);
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
    final requestId = response.requestOptions.extra['yx_request_id'] as String?;
    final startTime = response.requestOptions.extra['yx_request_start_time'] as DateTime?;
    
    if (requestId != null) {
      final duration = startTime != null ? DateTime.now().difference(startTime) : null;
      
      _controller.logResponse(
        id: requestId,
        statusCode: response.statusCode,
        responseData: response.data,
        duration: duration,
      );
    }

    super.onResponse(response, handler);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    final requestId = err.requestOptions.extra['yx_request_id'] as String?;
    final startTime = err.requestOptions.extra['yx_request_start_time'] as DateTime?;
    
    if (requestId != null) {
      final duration = startTime != null ? DateTime.now().difference(startTime) : null;
      
      _controller.logError(
        id: requestId,
        error: err.message ?? '未知错误',
        statusCode: err.response?.statusCode,
        duration: duration,
      );
    }

    super.onError(err, handler);
  }
}

// 3. 使用拦截器
final dio = Dio();
dio.interceptors.add(YxNetInspectorDioInterceptor());

// 4. 正常使用 Dio，所有请求都会自动记录
final response = await dio.get('https://api.example.com/users');
```

### 手动网络日志记录

你也可以手动记录网络请求：

```dart
// 记录请求
YxNetInspectorController.instance.logRequest(
  id: 'unique-request-id',
  method: 'GET',
  url: 'https://api.example.com/users',
  headers: {'Authorization': 'Bearer token'},
);

// 记录响应
YxNetInspectorController.instance.logResponse(
  id: 'unique-request-id',
  statusCode: 200,
  responseData: {'users': []},
  duration: Duration(milliseconds: 500),
);

// 记录错误
YxNetInspectorController.instance.logError(
  id: 'unique-request-id',
  error: '网络超时',
  duration: Duration(seconds: 10),
);
```

## 🎨 自定义配置

### 主题设置

```dart
YxNetInspector(
  theme: YxNetInspectorTheme(
    primaryColor: Colors.purple,
    backgroundColor: Colors.white,
    textColor: Colors.black,
    errorColor: Colors.red,
    successColor: Colors.green,
  ),
  child: YourApp(),
)
```

### 悬浮球配置

```dart
YxNetInspector(
  floatingBallConfig: YxFloatingBallConfig(
    size: 80.0,
    position: Offset(20, 100),
    draggable: true,
    showBadge: true,
    autoHide: false,
  ),
  child: YourApp(),
)
```

## 📚 API 参考

### YxNetInspector

包装你的应用并提供网络检查功能的主要组件。

| 属性 | 类型 | 默认值 | 说明 |
|----------|------|---------|-------------|
| `child` | Widget | 必需 | 你的应用组件 |
| `showFloatingBall` | bool | true | 是否显示悬浮调试球 |
| `ballSize` | double | 60.0 | 悬浮球大小 |
| `ballColor` | Color? | null | 悬浮球颜色 |
| `showInDebugMode` | bool | true | 在调试模式下显示检查器 |
| `showInReleaseMode` | bool | false | 在发布模式下显示检查器 |
| `maxLogs` | int | 1000 | 保持的最大日志数量 |

### YxNetInspectorController

用于手动网络日志记录和配置的控制器。

```dart
// 获取实例
final controller = YxNetInspectorController.instance;

// 显示/隐藏悬浮球
controller.showFloatingBall();
controller.hideFloatingBall();

// 清空日志
controller.clearLogs();

// 获取统计信息
final stats = controller.getStatistics();
```

## 🤝 贡献

我们欢迎贡献！请查看我们的[贡献指南](CONTRIBUTING.md)了解详细信息。

## 📄 许可证

此项目使用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- 受网页开发中的网络调试工具启发
- 为 Flutter 社区用 ❤️ 构建

## 📞 支持

如果你喜欢这个包，请在 [GitHub](https://github.com/your-username/yx_net_inspector) 上给它一个 ⭐！

如有问题和功能请求，请使用 [GitHub Issues](https://github.com/your-username/yx_net_inspector/issues) 页面。