xn-fe-tools

xn-fe-tools

基于 Vue 3 Composition API 的工具库，提供 HTTP 请求工具 toAwaitFetch 和 Sentry 统一初始化工具集等能力。

✨ 特性

• 双模式：链式调用与解构 [data, error, success]
• 完整错误处理：HTTP / 业务 / 网络 / 超时，支持钩子与抑制抛错
• 重试与超时：内置重试策略、可自定义 shouldRetry，支持超时与取消
• 多种请求/响应类型：JSON、FormData、Blob
• 全局配置：baseURL、headers、validateStatus、validateResponse、transformResponse 等
• TypeScript 全量类型定义，零外部依赖（基于原生 Fetch）
• Sentry 统一初始化：支持 Vue 3 / Vue 2 / React / 纯浏览器，零安装成本，主包体积不受影响

📦 安装

# npm
npm install xn-fe-tools
# pnpm
pnpm add xn-fe-tools
# yarn
yarn add xn-fe-tools

🚀 快速使用

解构模式

import { sendGet, sendPost } from 'xn-fe-tools'

const [list, listError, ok] = await sendGet('/api/users')
const [created] = await sendPost('/api/users', { name: 'John' })

链式模式

import { toAwaitFetch } from 'xn-fe-tools'

toAwaitFetch
  .sendGet('/api/users')
  .catchHttp((err) => console.error('HTTP 错误', err))
  .catchBusiness((err) => console.error('业务错误', err))
  .catchNetwork((err) => console.error('网络/超时错误', err))

创建实例并统一配置（推荐）

import { createInstance } from 'xn-fe-tools'

const http = createInstance({
  baseURL: '',
  timeout: 5000,
  headers: ({ url, method }) => ({
    Authorization: `Bearer ${localStorage.getItem('token') || ''}`,
    'X-Request-Path': url,
    'X-Request-Method': method || 'GET',
  }),
  validateResponse: (res) => res.code === 200,
  transformResponse: (res) => res.data,
  retry: {
    enabled: true,
    maxRetryCount: 3,
    delay: 1000,
    shouldRetry: async (attempt, fetchError) => {
      if (fetchError.type === 'business' && fetchError.response?.code === 401) {
        return false
      }
      return true
    },
  },
  mode: 'cors',
  credentials: 'include',
})

const [data] = await http.sendGet('/api/users', undefined, { timeout: 2000 })

取消请求

import { sendGet } from 'xn-fe-tools'

const request = sendGet('/api/users', undefined, { timeout: 8000 })
request.cancel()
const [, error, success] = await request // 被取消时 error.type === 'timeout' 或 'network'

🛡️ Sentry 集成

通过独立子路径引入，主包体积不受影响，Sentry SDK 已内置打包无需额外安装：

// Vue 3（支持 Vue Router 路由追踪）
import { toVue3SentrySetup } from 'xn-fe-tools/sentry/vue3'

toVue3SentrySetup({
  dsn: 'https://xxx@sentry.io/xxx',
  app,    // Vue 3 应用实例，必填
  router, // Vue Router，可选
})

// Vue 2 / React / 纯浏览器
import { toVue2SentrySetup } from 'xn-fe-tools/sentry/vue2'
import { toReactSentrySetup } from 'xn-fe-tools/sentry/react'
import { toSentrySetup } from 'xn-fe-tools/sentry/browser'

返回值提供运行时控制能力：

const { isInitialized, captureException, captureMessage, setUser } = toVue3SentrySetup({ ... })

简化配置参数（无需了解 Sentry 集成 API）：

toVue3SentrySetup({
  dsn: '...',
  app,
  enableTracing: true,   // 控制 browserTracingIntegration，默认 true
  enableReplay: false,   // 控制 replayIntegration，默认 true
  breadcrumbs: { console: false }, // 控制面包屑行为
})

Vite Source Map 上传配置辅助：

// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin' // 需单独安装为 devDependency
import { getSentryViteConfig } from 'xn-fe-tools/sentry/browser'

export default defineConfig({
  plugins: [sentryVitePlugin(getSentryViteConfig({
    org: 'my-org',
    project: 'my-project',
    authToken: process.env.SENTRY_AUTH_TOKEN,
  }))],
  build: { sourcemap: true },
})

📦 版本信息

import { VERSION, getVersion } from 'xn-fe-tools'

console.log(VERSION)
console.log(getVersion())

🤖 MCP 支持（AI 助手集成）

xn-fe-tools 内置了 MCP（Model Context Protocol） 服务端，安装后 AI 助手可以自动获取所有 Hook 的 API 信息、使用文档、最佳实践和代码模板，帮助你正确使用最新功能。

配置

在项目中创建 MCP 配置文件：

注意： xn-fe-tools-mcp 是 xn-fe-tools 包内注册的 bin 命令，不是独立的 npm 包。必须通过 -p 参数指定包名。

Kiro — .kiro/settings/mcp.json：

{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "npx",
      "args": ["-p", "xn-fe-tools", "xn-fe-tools-mcp"]
    }
  }
}

Cursor — .cursor/mcp.json：

{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "npx",
      "args": ["-p", "xn-fe-tools", "xn-fe-tools-mcp"]
    }
  }
}

Claude Code — .mcp.json：

{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "npx",
      "args": ["-p", "xn-fe-tools", "xn-fe-tools-mcp"]
    }
  }
}

如果项目已安装 xn-fe-tools，也可以直接指向本地文件：

{
  "mcpServers": {
    "xn-fe-tools": {
      "command": "node",
      "args": ["node_modules/xn-fe-tools/dist/mcp/server.mjs"]
    }
  }
}

配置完成后，AI 助手即可通过以下工具获取信息：

📄 License

MIT