x-request

name	x-request
version	0.0.1
description	专注讲解 XRequest 的实际配置和使用，基于官方文档提供准确的配置说明

🎯 技能定位

本技能专注解决：如何正确配置 XRequest 来适配各种流式接口需求。

目录导航

• 🚀 快速开始 - 3分钟上手
  • 依赖管理
  • 基础配置
• 📦 技术栈概览
• 🔧 核心配置详解
  • 全局配置
  • 安全配置
  • 流式配置
• 🛡️ 安全指南
  • 环境安全配置
  • 认证方式对比
• 🔍 调试与测试
  • 调试配置
  • 配置验证
• 📋 使用场景
  • 独立使用
  • 配合其他技能
• 🚨 开发规则
• 🔗 参考资源
  • 📚 核心参考文档
  • 🌐 SDK官方文档
  • 💻 示例代码

🚀 快速开始

依赖管理

📋 系统要求

依赖包	版本要求	自动安装	作用
@antdv-next/x-sdk	≥2.2.2	✅	核心SDK，包含XRequest工具

🛠️ 一键安装

# 推荐使用 tnpm
tnpm install @antdv-next/x-sdk

# 或使用 npm
npm add @antdv-next/x-sdk

# 检查版本
npm ls @antdv-next/x-sdk

基础配置

最简单的使用方式

import { XRequest } from "@antdv-next/x-sdk";

// 最简配置：仅需提供API地址
const request = XRequest("https://api.example.com/chat");

// 如需手动控制（用于Provider场景）
const providerRequest = XRequest("https://api.example.com/chat", {
  manual: true, // 仅此项通常需要显式配置
});

💡 提示：XRequest 已内置合理的默认配置，大多数情况下只需提供API地址即可使用。

📦 技术栈概览

🏗️ 技术栈架构

graph TD
    A[XRequest] --> B[网络请求]
    A --> C[认证管理]
    A --> D[错误处理]
    A --> E[流式处理]
    B --> F[fetch封装]
    C --> G[Token管理]
    D --> H[重试机制]
    E --> I[Server-Sent Events]

🔑 核心概念

概念	角色定位	核心职责	使用场景
XRequest	🌐 请求工具	处理所有网络通信、认证、错误处理	统一请求管理
全局配置	⚙️ 配置中心	一次配置，多处使用	减少重复代码
流式配置	🔄 流式处理	支持SSE和JSON响应格式	AI对话场景

🔧 核心配置详解

核心功能参考内容 CORE.md

🛡️ 安全指南

环境安全配置

🌍 不同环境的安全策略

运行环境	安全等级	配置方式	风险说明
浏览器前端	🔴 高危	❌ 禁止配置密钥	密钥会直接暴露给用户
Node.js后端	🟢 安全	✅ 环境变量配置	密钥存储在服务器端
代理服务	🟢 安全	✅ 同域代理转发	密钥由代理服务管理

🔐 认证方式对比

认证方式	适用环境	配置示例	安全性
Bearer Token	Node.js	Bearer ${process.env.API_KEY}	✅ 安全
API Key Header	Node.js	X-API-Key: ${process.env.KEY}	✅ 安全
代理转发	浏览器	/api/proxy/service	✅ 安全
直接配置	浏览器	Bearer sk-xxx	❌ 危险

🔍 调试与测试

调试配置

🛠️ 调试模板

Node.js调试配置:

// 安全的调试配置（Node.js 环境）
const debugRequest = XRequest("https://your-api.com/chat", {
  headers: {
    Authorization: `Bearer ${process.env.DEBUG_API_KEY}`,
  },
  params: { query: "测试消息" },
});

前端调试配置:

// 安全的调试配置（前端环境）
const debugRequest = XRequest("/api/debug/chat", {
  params: { query: "测试消息" },
});

配置验证

✅ 安全检查工具

// 安全配置验证函数
const validateSecurity = (config: any) => {
  const isBrowser = typeof window !== "undefined";
  const hasAuth =
    config.headers?.Authorization || config.headers?.authorization;

  if (isBrowser && hasAuth) {
    throw new Error("❌ 前端环境禁止配置 Authorization，存在密钥泄漏风险！");
  }

  console.log("✅ 安全配置检查通过");
  return true;
};

// 使用示例
validateSecurity({
  headers: {
    // 不要包含 Authorization
  },
});

📋 使用场景

独立使用

🎯 直接发起请求

import { XRequest } from "@antdv-next/x-sdk";

// 测试接口可用性
const testRequest = XRequest("https://httpbin.org/post", {
  params: { test: "data" },
});

// 立即发送请求
const response = await testRequest();
console.log(response);

配合其他技能

🔄 技能协作流程

graph TD
    A[x-request] -->|配置请求| B[x-chat-provider]
    A -->|配置请求| C[use-x-chat]
    B -->|提供Provider| C
    A --> D[直接请求]

使用方式	配合技能	作用	示例
独立使用	无	直接发起网络请求	测试接口可用性
配合 x-chat-provider	x-chat-provider	为自定义 Provider 配置请求	配置私有 API
配合 use-x-chat	use-x-chat	为内置 Provider 配置请求	配置 OpenAI API
完整 AI 应用	x-request → x-chat-provider → use-x-chat	为整个系统配置请求	完整 AI 对话应用

⚠️ useXChat 集成安全警告

重要警告：useXChat 仅用于前端环境，XRequest 配置中禁止包含 Authorization！

❌ 错误配置（危险）:

// 极度危险：密钥会直接暴露给浏览器
const unsafeRequest = XRequest("https://api.openai.com/v1/chat/completions", {
  headers: {
    Authorization: "Bearer sk-xxxxxxxxxxxxxx", // ❌ 危险！
  },
  manual: true,
});

✅ 正确配置（安全）:

// 前端安全配置：使用代理服务
const safeRequest = XRequest("/api/proxy/openai", {
  params: {
    model: "gpt-3.5-turbo",
    stream: true,
  },
  manual: true,
});

🚨 开发规则

测试用例规则

• 如果用户没有明确需要测试用例，则不要添加测试文件
• 仅在用户明确要求时才创建测试用例

代码质量规则

• 完成编写后必须检查类型：运行 tsc --noEmit 确保无类型错误
• 保持代码整洁：移除所有未使用的变量和导入

✅ 配置检查清单

使用 XRequest 前请确认以下配置已正确设置：

🔍 配置检查清单

检查项	状态	说明
API 地址	✅ 必须配置	XRequest('https://api.xxx.com')
认证信息	⚠️ 环境相关	前端❌禁止，Node.js✅可用
manual配置	✅ Provider场景	在Provider中需要设为true，其他场景需要根据实际情况设置
其他配置	❌ 无需配置	已内置合理默认值
接口可用性	✅ 建议测试	使用调试配置验证

🛠️ 快速验证脚本

// 运行前检查配置
const checkConfig = () => {
  const checks = [
    {
      name: "全局配置",
      test: () => {
        // 检查是否已设置全局配置
        return true; // 根据实际情况检查
      },
    },
    {
      name: "安全配置",
      test: () => validateSecurity(globalConfig),
    },
    {
      name: "类型检查",
      test: () => {
        // 运行 tsc --noEmit
        return true;
      },
    },
  ];

  checks.forEach(check => {
    console.log(`${check.name}: ${check.test() ? "✅" : "❌"}`);
  });
};

🎯 技能协作

graph LR
    A[x-request] -->|配置请求| B[x-chat-provider]
    A -->|配置请求| C[use-x-chat]
    B -->|提供Provider| C

📊 技能使用对照表

使用场景	所需技能	使用顺序	完成时间
测试接口	x-request	直接使用	2分钟
私有API适配	x-request → x-chat-provider	先配置请求，再创建Provider	10分钟
标准AI应用	x-request → use-x-chat	先配置请求，再构建界面	15分钟
完整自定义	x-request → x-chat-provider → use-x-chat	完整工作流	30分钟

🔗 参考资源

📚 核心参考文档

• API.md - 完整的 API 参考文档
• EXAMPLES_SERVICE_PROVIDER.md - 各服务商配置示例

🌐 SDK官方文档

• useXChat 官方文档
• XRequest 官方文档
• Chat Provider 官方文档

💻 示例代码

• custom-provider-width-ui.tsx - 自定义 Provider 完整示例