npm package: @kivii.com/bridge
Description: Kivii Bridge - A comprehensive toolkit library with request handling, logging, and utility functions
Author: Kivii Team
Latest version: 1.1.11

# Kivii Bridge

一个轻量级的综合性工具库，提供请求处理、日志记录、配置管理等常用功能，支持依赖注入和模块化设计。

## ✨ 特性

- 🚀 **轻量级**：核心库体积小，按需加载
- 🔧 **依赖注入**：支持模块替换和扩展
- 🪝 **Hook 钩子**：灵活的事件钩子系统，支持请求拦截和响应处理
- 📦 **多格式支持**：UMD、ESM、CommonJS
- 🌐 **跨平台**：支持浏览器和 Node.js 环境
- � **Type\*Script**：完整的类型定义
- 🛠️ **可扩展**：模块化设计，易于扩展
- 🎭 **Mock 支持**：内置 Mock 请求模块，轻松切换到测试数据
- 📥 **文件下载**：支持进度监控、自动下载、表单下载、错误处理
- 🔗 **打开标签页**：支持新标签页打开、自定义实现

## 📦 安装

### pnpm

```bash
pnpm add "@kivii.com/bridge"
```

## 🚀 快速开始

### 浏览器环境

```html
<!-- 使用 UMD 格式 -->
<script src="https://unpkg.com/@kivii.com/bridge/dist/kivii.bridge.min.js"></script>
<script>
  // 访问全局 Kivii 实例
  kivii.logger.info('应用已加载');
</script>
```

### Vue 3 插件方式

```javascript
import { createApp } from 'vue';
import App from './App.vue';
import { kivii } from '@kivii.com/bridge'; // 直接引入就能用，内部已经做全局声明window.kivii

const app = createApp(App);

app.mount('#app');
```

在组件中使用：

```vue
<script setup>
  // 发送请求
  const response = await kivii.request.send({
    url: '/api/data',
    method: 'GET',
  });

  // 下载文件
  const downloadFile = async () => {
    const result = await kivii.downloader.download({
      url: 'https://example.com/file.pdf',
      onProgress: progress => {
        console.log(`下载进度: ${progress.percentage}%`);
      },
    });
    console.log('下载完成:', result.filename);
  };
</script>
```

## 📁 目录结构

```
src/
├── core/                    # 核心模块
│   ├── Config.ts           # 配置管理器
│   └── Kivii.ts            # 主应用类
├── interfaces/             # 接口定义
│   ├── ILogger.ts          # 日志接口
│   ├── IRequest.ts         # 请求接口
│   └── index.ts            # 接口导出
├── modules/                # 实现模块
│   ├── AxiosRequest.ts     # Axios 请求实现
│   ├── MockRequest.ts      # Mock 请求实现
│   ├── Downloader.ts       # 文件下载实现
│   ├── ConsoleLogger.ts    # 控制台日志实现
│   ├── OpenTab.ts         # 打开标签页实现
│   └── index.ts            # 模块导出
├── config/                 # 默认配置
│   ├── logger.ts           # 日志配置
│   ├── request.ts          # 请求配置
│   └── index.ts            # 配置导出
├── utils/                  # 工具函数
├── examples/               # 使用示例
├── docs/                   # 文档
└── index.ts                # 入口文件
```

## 📚 核心功能

### 配置管理

```javascript
// 初始化配置
kivii.config.init({
  request: {
    baseURL: 'https://api.example.com',
    timeout: 5000,
  },
  logger: {
    enabled: true,
    level: 'info',
  },
});

// 单独设置配置
kivii.config.set('version', '1.0.0');

// 获取配置
const baseURL = kivii.config.get('request.baseURL');
const appName = kivii.config.get('name');
```

**📖 详细文档：[配置管理 API](./src/docs/config.md)**

### 网络请求

```javascript
// 示例一
kivii.request
  .send({
    url: 'ai/chat/test',
    method: 'POST',
    data: { message: 'Hello, world!' },
  })
  .then((res: any) => {
    console.log(res);
  })
  .catch((err: any) => {
    console.error(err);
  });

// 示例二
const response = await kivii.request.get('ai/chat/test');
console.log(response);

// 示例三 封装成方法后必须使用async
const getChatTest = async () => {
  return await kivii.request.get('ai/chat/test');
};
const response3 = await getChatTest(); // 或 getChatTest().then((res: any) => { console.log(res); })
console.log(response3);
```

### 错误处理（Request 模块）

当使用 `kivii.request.send(...)` 或 `kivii.request.get/post/...` 时，库在遇到服务器返回非 2xx 状态码时会通过 Promise reject 抛出错误。为了兼顾标准 `Error` 语义与实用性，抛出的 `Error` 实例会在自身上附带服务端响应的详细信息，调用方可以直接访问这些字段来获取服务端返回体和状态。

当存在服务器响应时，Error 实例上通常会包含以下字段：

- `status`：HTTP 状态码（例如 `404`）
- `statusText`：状态文本（例如 `Not Found`）
- `data`：服务端返回的响应体（通常为 JSON）
- `headers`：响应头（已转换为普通对象）
- `config`：请求的部分配置信息（`url`、`method`、`timeout`）

注意：浏览器 DevTools 在打印 `Error` 时默认只展示 `message` 与 `stack`，不会自动把这些附加字段展开显示。调试时可以用下面的方式查看完整信息：

```javascript
kivii.request.send({...})
  .then(res => console.log('Request response:', res))
  .catch(err => {
    // 以对象形式查看 Error，包含附加字段
    console.dir(err);
    // 或展开为普通对象以便控制台一目了然
    console.log('as plain obj', { ...err });
    console.log('status:', err.status);
    console.log('data:', err.data);
  });
```

**📖 详细文档：[Request 模块 API](./src/docs/request.md)**

### 日志记录

```javascript
kivii.logger.debug('调试信息', { userId: 123 });
kivii.logger.info('应用启动成功');
kivii.logger.warn('警告信息');
kivii.logger.error('错误信息', new Error('Something went wrong'));
```

**📖 详细文档：[Logger 模块 API](./src/docs/logger.md)**

### Hook 钩子系统

```javascript
// 配置式注册钩子
kivii.config.init({
  hooks: {
    // 请求前：添加认证令牌
    'request.before': config => {
      const token = localStorage.getItem('token');
      if (token) {
        config.headers = config.headers || {};
        config.headers.Authorization = `Bearer ${token}`;
      }
      return config;
    },

    // 响应后：处理 404
    'request.error.status:404': response => {
      response.data.message = '页面未找到';
      return response;
    },

    // 错误处理
    'request.error': error => {
      console.error('请求失败:', error.message);
      return error;
    },
  },
});

// 编程式注册钩子
kivii.hook.register('request.before', config => {
  console.log('发送请求:', config.method, config.url);
  return config;
});

kivii.hook.register('request.response', response => {
  console.log('响应已接收:', response.status);
  return response;
});
```

**📖 详细文档：[Hook 模块 API](./src/docs/hook.md)**

### Mock 请求

```javascript
// main.ts
import kivii from '@kivii.com/bridge';
import { MockRequest, AxiosRequest } from '@kivii.com/bridge';

// 注册 MockRequest 模块
kivii.register(new MockRequest());

// 配置 mock 数据
kivii.config.set('mock', {
  api: {
    users: [
      { id: 1, name: 'John Doe', email: 'john@example.com' },
      { id: 2, name: 'Jane Doe', email: 'jane@example.com' },
    ],
    test: ({ method, params, data }) => {
      // 自定义方法
    },
  },
});

// 使用 mock 数据发送请求
const response = await kivii.request.get('/api/users');
console.log(response.data); // [{ id: 1, name: 'John Doe', ... }, ...]

// 切换到真实请求直接在main.ts里注释 kivii.register(new MockRequest());
```

**📖 详细文档：[Mock 模块 API](./src/docs/mock.md)**

### 文件下载

```javascript
// 简单下载
const result = await kivii.downloader.download({
  url: 'https://example.com/file.pdf',
});

// 完整示例
const result = await kivii.downloader.download({
  url: '/Storages/Zip',
  method: 'POST',
  header: {
    Authorization: 'Bearer ',
  },
  params: {
    Kvids: '14D96D8B-E187-4DD3-99D2-AECD38695DA7',
    FolderPath: '/Certificate/Check/Files',
  },
  filename: '自定义文件名.zip', // 自定义文件名
  timeout: 30000, // 超时设置
  autoDownload: true, // 是否自动下载
  onProgress: progress => {
    console.log(`进度: ${progress.percentage}%`);
    console.log(`速度: ${progress.speed} bytes/s`);
  },
  onSuccess: result => {
    console.log(result);
  },
  onError: error => {
    console.log(error);
  },
});

// 表单方式下载（适用于需要 POST 数据的场景）
kivii.downloader.form({
  url: '/api/files/download', // 支持相对路径，会自动拼接 baseUrl
  method: 'POST',
  header: {
    Authorization: 'Bearer your-token-here',
  },
  data: {
    Kvids: '14D96D8B-E187-4DD3-99D2-AECD38695DA7',
    FolderPath: '/Certificate/Check/Files',
  },
});
```

**📖 详细文档：[Downloader 模块 API](./src/docs/downloader.md)**

### 打开标签页

```javascript
// 在新标签页打开 URL
kivii.openTab.open('https://example.com');

// 打开相对路径
kivii.openTab.openPath('/dashboard');

// 自定义实现
class CustomOpenTab extends IOpenTab {
  open(url, options) {
    // 自定义打开逻辑
    console.log('自定义打开:', url);
    return true;
  }
}

// 注册自定义实现
kivii.register(new CustomOpenTab());
```

### 依赖注入

```javascript
import kivii from '@kivii.com/bridge';

// 自定义请求模块
class CustomRequest extends IRequest {
  async send(config) {
    const response = await fetch(config.url, {
      method: config.method,
      headers: config.headers,
      body: JSON.stringify(config.data),
    });
    return await response.json();
  }
}

// 注册自定义模块
kivii.register(new CustomRequest());
```

## 🧪 测试

项目使用 Jest 进行单元测试，测试覆盖率达到 **95.61%**。

### 运行测试

```bash
# 运行所有测试
pnpm test

# 运行测试并生成覆盖率报告
pnpm test -- --coverage

# 监听模式运行测试
pnpm test:watch
```

详细测试文档请查看 [测试文档](./tests/README.md)

## 📖 文档索引

### 核心文档

- [Request 模块文档](./src/docs/request.md) - HTTP 请求、拦截器、错误处理
- [Hook 模块文档](./src/docs/hook.md) - 钩子系统、请求拦截、响应处理
- [Mock 模块文档](./src/docs/mock.md) - Mock 请求、测试数据、开发调试
- [Logger 模块文档](./src/docs/logger.md) - 日志记录、自定义日志器
- [Downloader 模块文档](./src/docs/downloader.md) - 文件下载、进度监控、自动下载
- [OpenTab 模块文档](./src/docs/opentab.md) - 打开标签页、自定义实现
- [Config 模块文档](./src/docs/config.md) - 配置管理、环境配置、配置验证
- [测试文档](./tests/README.md) - 测试说明、覆盖率报告

### 快速链接

- [安装指南](#-安装)
- [快速开始](#-快速开始)
- [核心功能](#-核心功能)
- [目录结构](#-目录结构)
- [测试](#-测试)
- [导出说明](#-导出说明)