x-request

🎯 技能定位

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

目录

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

🚀 快速开始

依赖管理

📋 系统要求

软件包	版本要求	自动安装	用途
@ant-design/x-sdk	≥2.2.2	✅	核心 SDK，包含 XRequest 工具

🛠️ 一键安装

# Recommended to use tnpm
tnpm install @ant-design/x-sdk

# Or use npm
npm add @ant-design/x-sdk

# Check version
npm ls @ant-design/x-sdk

基本配置

最简用法

import { XRequest } from '@ant-design/x-sdk';

// Minimal configuration: only need to provide API URL
const request = XRequest('https://api.example.com/chat');

// For manual control (used in Provider scenarios)
const providerRequest = XRequest('https://api.example.com/chat', {
  manual: true, // Usually only this needs explicit configuration
});

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

📦 技术栈概览

🏗️ 技术栈架构

graph TD
    A[XRequest] --> B[Network Requests]
    A --> C[Authentication Management]
    A --> D[Error Handling]
    A --> E[Streaming Processing]
    B --> F[fetch Wrapper]
    C --> G[Token Management]
    D --> H[Retry Mechanism]
    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 调试配置：

// Safe debug configuration (Node.js environment)
const debugRequest = XRequest('https://your-api.com/chat', {
  headers: {
    Authorization: `Bearer ${process.env.DEBUG_API_KEY}`,
  },
  params: { query: 'test message' },
});

前端调试配置：

// Safe debug configuration (frontend environment)
const debugRequest = XRequest('/api/debug/chat', {
  params: { query: 'test message' },
});

配置验证

✅ 安全检查工具

// Security configuration validation function
const validateSecurity = (config: any) => {
  const isBrowser = typeof window !== 'undefined';
  const hasAuth = config.headers?.Authorization || config.headers?.authorization;

  if (isBrowser && hasAuth) {
    throw new Error(
      '❌ Frontend environment prohibits Authorization configuration, risk of key leakage!',
    );
  }

  console.log('✅ Security configuration check passed');
  return true;
};

// Usage example
validateSecurity({
  headers: {
    // Do not include Authorization
  },
});

📋 使用场景

独立使用

🎯 直接发起请求

import { XRequest } from '@ant-design/x-sdk';

// Test interface availability
const testRequest = XRequest('https://httpbin.org/post', {
  params: { test: 'data' },
});

// Send request immediately
const response = await testRequest();
console.log(response);

与其他技能集成

🔄 技能协作工作流

graph TD
    A[x-request] -->|Configure Request| B[x-chat-provider]
    A -->|Configure Request| C[use-x-chat]
    B -->|Provide Provider| C
    A --> D[Direct Request]

使用方式	协作技能	用途	示例
独立使用	无	直接发起网络请求	测试接口可用性
配合 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！

❌ 错误配置（危险）：

// Extremely dangerous: keys will be directly exposed to browser
const unsafeRequest = XRequest('https://api.openai.com/v1/chat/completions', {
  headers: {
    Authorization: 'Bearer sk-xxxxxxxxxxxxxx', // ❌ Dangerous!
  },
  manual: true,
});

✅ 正确配置（安全）：

// Frontend security configuration: use proxy service
const safeRequest = XRequest('/api/proxy/openai', {
  params: {
    model: 'gpt-3.5-turbo',
    stream: true,
  },
  manual: true,
});

🚨 开发规则

测试用例规则

• 如果用户未明确要求测试用例，请勿添加测试文件
• 只有在用户明确要求时才创建测试用例

代码质量规则

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

✅ 配置检查清单

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

🔍 配置检查清单

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

🛠️ 快速验证脚本

// Check configuration before running
const checkConfig = () => {
  const checks = [
    {
      name: 'Global Configuration',
      test: () => {
        // Check if global configuration has been set
        return true; // Check according to actual situation
      },
    },
    {
      name: 'Security Configuration',
      test: () => validateSecurity(globalConfig),
    },
    {
      name: 'Type Check',
      test: () => {
        // Run tsc --noEmit
        return true;
      },
    },
  ];

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

🎯 技能协作

graph LR
    A[x-request] -->|Configure Request| B[x-chat-provider]
    A -->|Configure Request| C[use-x-chat]
    B -->|Provide 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 的完整示例