X Request

🎯 技能定位

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

目录导航

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

🚀 快速开始

依赖管理

📋 系统要求

🛠️ 一键安装

# 推荐使用 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]

🔑 核心概念

🔧 核心配置详解

核心功能参考内容 CORE.md

🛡️ 安全指南

环境安全配置

🌍 不同环境的安全策略

🔐 认证方式对比

🔍 调试与测试

调试配置

🛠️ 调试模板

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[直接请求]

⚠️ 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 前请确认以下配置已正确设置：

🔍 配置检查清单

🛠️ 快速验证脚本

// 运行前检查配置
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

📊 技能使用对照表

🔗 参考资源

📚 核心参考文档

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

🌐 SDK官方文档

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

💻 示例代码

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