@tianyio/quality-helper/templates/configs/docs/工具包使用示例.md

A comprehensive quality helper tool for project scaffolding and management

# 工具包使用示例

本文档展示了如何在项目中使用 @tianyio/quality-helper 和 @tianyio/fast-util-lib 工具包。

## 1. 质量工具包使用 (@tianyio/quality-helper)

### 1.1 CLI 命令使用

```
# 创建新项目
npx quality-helper create my-project

# 更新项目配置文件
npx quality-helper update-config

# 更新项目依赖
npx quality-helper update-deps

# 检查依赖状态
npx quality-helper check-deps
```

### 1.2 Vite 插件集成

在 vite.config.ts 中集成版本信息插件：

```typescript
import { defineConfig } from 'vite'
import { versionInfoPlugin } from '@tianyio/quality-helper/version-plugin'

export default defineConfig({
  plugins: [
    versionInfoPlugin({
      // 开发模式下提供API接口
      injectGitInfo: true,
      injectBuildTime: true,
      // 生产构建时生成版本文件
      generateFile: true,
      outputPath: 'dist/version.json',
    }),
  ],
})
```

在 Vue 组件中使用版本信息：

```
<template>
  <div class="version-info">
    <p>版本: {{ versionInfo.version }}</p>
    <p>构建时间: {{ versionInfo.buildTime }}</p>
    <p>Git提交: {{ versionInfo.gitCommitShort }}</p>
  </div>
</template>

<script setup lang="ts">
import versionInfo from 'virtual:version-info'
</script>
```

## 2. 工具库使用 (@tianyio/fast-util-lib)

### 2.1 事件系统

```
import { useEvent } from '@tianyio/fast-util-lib'

const { on, off, emit } = useEvent()

// 监听事件
const listenerId = on('user-login', (data) => {
  console.log('用户登录:', data)
})

// 触发事件
emit('user-login', { userId: 123, username: 'john' })

// 取消监听
off('user-login', listenerId)
```

### 2.2 日志模块

```
import { useLogger } from '@tianyio/fast-util-lib'

const logger = useLogger({
  level: 'debug',
  prefix: '[MyApp]'
})

logger.debug('调试信息')
logger.info('普通信息')
logger.warn('警告信息')
logger.error('错误信息')
```

### 2.3 网络模块

```
import { useFetch } from '@tianyio/fast-util-lib'

// 发送 GET 请求
const { data, error, loading } = useFetch('/api/users')

// 发送 POST 请求
const { data: postData, error: postError } = useFetch('/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'John' })
})
```

### 2.4 性能监控

```
import { PerformanceMonitor } from '@tianyio/fast-util-lib'

// 初始化性能监控
const monitor = new PerformanceMonitor()

// 标记性能事件
monitor.mark('app-start')

// 测量性能
monitor.measure('app-load', 'app-start', 'app-end')

// 获取性能数据
const metrics = monitor.getMetrics()
console.log(metrics)
```

### 2.5 错误处理

```
import { initGlobalErrorHandler, ERROR_TYPE } from '@tianyio/fast-util-lib'

// 初始化全局错误处理
initGlobalErrorHandler((error, type, context) => {
  console.error(`错误类型: ${type}`, error)

  // 根据错误类型处理
  switch (type) {
    case ERROR_TYPE.JAVASCRIPT:
      // 处理 JavaScript 错误
      break
    case ERROR_TYPE.PROMISE:
      // 处理 Promise 错误
      break
    case ERROR_TYPE.RESOURCE:
      // 处理资源加载错误
      break
  }
})
```

## 3. 配置文件使用

### 3.1 ESLint 配置

项目使用统一的 ESLint 配置，无需额外配置。

### 3.2 Prettier 配置

项目使用统一的 Prettier 配置，无需额外配置。

### 3.3 Commitlint 配置

项目使用统一的 Commitlint 配置，支持以下提交类型：

- `update` - 新功能
- `defect` - 修复bug
- `docs` - 文档更新
- `style` - 代码格式化
- `refactor` - 重构
- `perf` - 性能优化
- `test` - 测试相关
- `build` - 构建相关
- `ci` - CI/CD相关
- `chore` - 其他杂项
- `revert` - 回滚
- `wip` - 进行中的工作
- `release` - 发布版本
- `hotfix` - 热修复
- `security` - 安全修复

## 4. 最佳实践

1. **工具包版本管理**: 使用 `workspace:*` 协议确保使用工作区内的最新版本
2. **按需导入**: 只导入需要的模块，利用 Tree Shaking 减少打包体积
3. **类型安全**: 充分利用 TypeScript 类型定义
4. **错误处理**: 合理使用错误处理模块捕获和处理异常
5. **性能监控**: 在关键路径添加性能监控点