X Request

🎯 Skill Positioning

This skill focuses on solving: How to correctly configure XRequest to adapt to various streaming interface requirements.

Table of Contents

• 🚀 Quick Start - Get started in 3 minutes
• Dependency Management
• Basic Configuration
• 📦 Technology Stack Overview
• 🔧 Core Configuration Details
• Global Configuration
• Security Configuration
• Streaming Configuration
• 🛡️ Security Guide
• Environment Security Configuration
• Authentication Methods Comparison
• 🔍 Debugging and Testing
• Debug Configuration
• Configuration Validation
• 📋 Usage Scenarios
• Standalone Usage
• Integration with Other Skills
• 🚨 Development Rules
• 🔗 Reference Resources
• 📚 Core Reference Documentation
• 🌐 SDK Official Documentation
• 💻 Example Code

🚀 Quick Start

Dependency Management

📋 System Requirements

🛠️ One-click Installation

# 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

Basic Configuration

Simplest Usage

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
});

💡 Tip: XRequest has built-in reasonable default configurations. In most cases, you only need to provide the API URL to use it.

📦 Technology Stack Overview

🏗️ Technology Stack Architecture

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]

🔑 Core Concepts

🔧 Core Configuration Details

Core functionality reference content CORE.md

🛡️ Security Guide

Environment Security Configuration

🌍 Security Strategies for Different Environments

🔐 Authentication Methods Comparison

🔍 Debugging and Testing

Debug Configuration

🛠️ Debug Templates

Node.js Debug Configuration:

// 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' },
});

Frontend Debug Configuration:

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

Configuration Validation

✅ Security Check Tools

// 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
  },
});

📋 Usage Scenarios

Standalone Usage

🎯 Direct Request Initiation

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);

Integration with Other Skills

🔄 Skill Collaboration Workflow

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]

⚠️ useXChat Integration Security Warning

Important Warning: useXChat is only for frontend environments, XRequest configuration must not contain Authorization!

❌ Incorrect Configuration (Dangerous):

// 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,
});

✅ Correct Configuration (Safe):

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

🚨 Development Rules

Test Case Rules

• If the user does not explicitly need test cases, do not add test files
• Only create test cases when the user explicitly requests them

Code Quality Rules

• After completion, must check types: Run tsc --noEmit to ensure no type errors
• Keep code clean: Remove all unused variables and imports

✅ Configuration Checklist

Before using XRequest, please confirm the following configurations are correctly set:

🔍 Configuration Checklist

🛠️ Quick Verification Script

// 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() ? '✅' : '❌'}`);
  });
};

🎯 Skill Collaboration

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

📊 Skill Usage Comparison Table

🔗 Reference Resources

📚 Core Reference Documentation

• API.md - Complete API reference documentation
• EXAMPLES_SERVICE_PROVIDER.md - Configuration examples for various service providers

🌐 SDK Official Documentation

• useXChat Official Documentation
• XRequest Official Documentation
• Chat Provider Official Documentation

💻 Example Code

• custom-provider-width-ui.tsx - Complete example of custom Provider

XRequestFunction

```ts | pure type XRequestFunction<Input = Record<PropertyKey, any>, Output = Record<string, string>> = ( baseURL: string, options?: XRequestOptions<Input, Output>, ) => XRequestClass<Input, Output>;

### XRequestFunction

| Property | Description      | Type                             | Default | Version |
| -------- | ---------------- | -------------------------------- | ------- | ------- |
| baseURL  | API endpoint URL | string                           | -       | -       |
| options  | Request options  | XRequestOptions\<Input, Output\> | -       | -       |

### XRequestOptions

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| callbacks | Request callback handlers | XRequestCallbacks\<Output\> | - | - |
| params | Request parameters | Input | - | - |
| headers | Additional request headers | Record\<string, string\> | - | - |
| timeout | Request timeout configuration (time from sending request to connecting to service), unit: ms | number | - | - |
| streamTimeout | Stream mode data timeout configuration (time interval for each chunk return), unit: ms | number | - | - |
| fetch | Custom fetch object | `typeof fetch` | - | - |
| middlewares | Middlewares for pre- and post-request processing | XFetchMiddlewares | - | - |
| transformStream | Stream processor | XStreamOptions\<Output\>['transformStream'] \| ((baseURL: string, responseHeaders: Headers) => XStreamOptions\<Output\>['transformStream']) | - | - |
| streamSeparator | Stream separator, used to separate different data streams. Does not take effect when transformStream has a value | string | \n\n | 2.2.0 |
| partSeparator | Part separator, used to separate different parts of data. Does not take effect when transformStream has a value | string | \n | 2.2.0 |
| kvSeparator | Key-value separator, used to separate keys and values. Does not take effect when transformStream has a value | string | : | 2.2.0 |
| manual | Whether to manually control request sending. When `true`, need to manually call `run` method | boolean | false | - |
| retryInterval | Retry interval when request is interrupted or fails, in milliseconds. If not set, automatic retry will not occur | number | - | - |
| retryTimes | Maximum number of retry attempts. No further retries will be attempted after exceeding this limit | number | - | - |

### XRequestCallbacks

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| onSuccess | Success callback. When used with Chat Provider, additionally gets the assembled message | (chunks: Output[], responseHeaders: Headers, message: ChatMessage) => void | - | - |
| onError | Error handling callback. `onError` can return a number indicating the retry interval (in milliseconds) when a request exception occurs. When both `onError` return value and `options.retryInterval` exist, the `onError` return value takes precedence. When used with Chat Provider, additionally gets the assembled fail back message | (error: Error, errorInfo: any, responseHeaders?: Headers, message: ChatMessage) => number \| void | - | - |
| onUpdate | Message update callback. When used with Chat Provider, additionally gets the assembled message | (chunk: Output, responseHeaders: Headers, message: ChatMessage) => void | - | - |

### XRequestClass

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| abort | Cancel request | () => void | - | - |
| run | Manually execute request (effective when `manual=true`) | (params?: Input) => void | - | - |
| isRequesting | Whether currently requesting | boolean | - | - |

### setXRequestGlobalOptions

type setXRequestGlobalOptions<Input, Output> = ( options: XRequestGlobalOptions<Input, Output>, ) => void;

### XRequestGlobalOptions

type XRequestGlobalOptions<Input, Output> = Pick< XRequestOptions<Input, Output>, 'headers' | 'timeout' | 'streamTimeout' | 'middlewares' | 'fetch' | 'transformStream' | 'manual' >;

### XFetchMiddlewares

interface XFetchMiddlewares { onRequest?: (...ags: Parameters<typeof fetch>) => Promise<Parameters<typeof fetch>>; onResponse?: (response: Response) => Promise<Response>; }

## FAQ

### When using transformStream in XRequest, it causes stream locking issues on the second input request. How to solve this?

onError TypeError: Failed to execute 'getReader' on 'ReadableStream': ReadableStreamDefaultReader constructor can only accept readable streams that are not yet locked to a reader

The Web Streams API stipulates that a stream can only be locked by one reader at the same time. Reuse will cause an error. Therefore, when using TransformStream, you need to pay attention to the following points:

1. Ensure that the transformStream function returns a new ReadableStream object, not the same object.
2. Ensure that the transformStream function does not perform multiple read operations on response.body.

**Recommended Writing**

const [provider] = React.useState( new CustomProvider({ request: XRequest(url, { manual: true, // Recommended: transformStream returns a new instance with a function transformStream: () => new TransformStream({ transform(chunk, controller) { // Your custom processing logic controller.enqueue({ data: chunk }); }, }), // Other configurations... }), }), );

const request = XRequest(url, { manual: true, transformStream: new TransformStream({ ... }), // Do not persist in Provider/useState });

1. Built-in Default Configuration

XRequest has built-in reasonable default configurations, no additional configuration needed to use.

Built-in Default Values:

• method: 'POST'
• headers: { 'Content-Type': 'application/json' }

2. Security Configuration

🔐 Authentication Configuration Comparison

🛡️ Security Configuration Templates

Node.js Environment Security Configuration:

const nodeConfig = {
  baseURL: 'https://api.openai.com/v1',
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
  },
};

Frontend Environment Security Configuration:

const browserConfig = {
  baseURL: '/api/proxy/openai', // Through same-origin proxy
};

3. Basic Usage

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

// ⚠️ Note: The following examples apply to Node.js environment
// Frontend environments should use proxy services to avoid token leakage
const request = XRequest('https://your-api.com/chat', {
  headers: {
    Authorization: 'Bearer your-token', // ⚠️ Only for Node.js environment
  },
  params: {
    query: 'Hello',
  },
  manual: true, // ⚠️ Must be set to true when used in provider
  callbacks: {
    onSuccess: (messages) => {
      setStatus('success');
      console.log('onSuccess', messages);
    },
    onError: (error) => {
      setStatus('error');
      console.error('onError', error);
    },
    onUpdate: (msg) => {
      setLines((pre) => [...pre, msg]);
      console.log('onUpdate', msg);
    },
  },
});

⚠️ Important Reminder: When XRequest is used in x-chat-provider or use-x-chat provider, manual: true is a required configuration, otherwise the request will be sent immediately instead of waiting for invocation.

````

With URL Parameters

const request = XRequest('https://your-api.com/chat', {
  method: 'GET',
  params: {
    model: 'gpt-3.5-turbo',
    max_tokens: 1000,
  },
});

4. Streaming Configuration

🔄 Streaming Response Configuration

// Streaming response configuration (AI conversation scenarios)
const streamConfig = {
  params: {
    stream: true, // Enable streaming response
    model: 'gpt-3.5-turbo',
    max_tokens: 1000,
  },
  manual: true, // Manual control of requests
};

// Non-streaming response configuration (regular API scenarios)
const jsonConfig = {
  params: {
    stream: false, // Disable streaming response
  },
};

5. Dynamic Request Headers

// ❌ Unsafe: Frontend directly exposes API key
// const request = XRequest('https://your-api.com/chat', {
//   headers: {
//     'Authorization': `Bearer ${apiKey}`, // Don't do this!
//   },
//   params: {
//     messages: [{ role: 'user', content: 'Hello' }],
//   },
// });

// ✅ Safe: Node.js environment uses environment variables
const request = XRequest('https://your-api.com/chat', {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`, // Safe for Node.js environment
  },
  params: {
    messages: [{ role: 'user', content: 'Hello' }],
  },
});

// ✅ Safe: Frontend uses proxy service
const request = XRequest('/api/proxy/chat', {
  headers: {
    // No Authorization needed, handled by backend proxy
  },
  params: {
    messages: [{ role: 'user', content: 'Hello' }],
  },
});

6. Custom Stream Transformers

When AI service providers return non-standard formats, use transformStream for custom data transformation.

Basic Example

const request = XRequest('https://api.example.com/chat', {
  params: { message: 'Hello' },
  transformStream: () =>
    new TransformStream({
      transform(chunk, controller) {
        // TextDecoder converts binary data to string
        const text = new TextDecoder().decode(chunk);
        const lines = text.split('\n');

        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const data = line.slice(6);
            if (data !== '[DONE]') {
              // TextEncoder converts string back to binary
              controller.enqueue(new TextEncoder().encode(data));
            }
          }
        }
      },
    }),
});

Common Transformation Templates

// OpenAI format
const openaiStream = () =>
  new TransformStream({
    transform(chunk, controller) {
      const text = new TextDecoder().decode(chunk);
      const data = JSON.parse(text);
      const content = data.choices?.[0]?.delta?.content || '';
      controller.enqueue(new TextEncoder().encode(content));
    },
  });

// Usage example
const request = XRequest(url, {
  params: { message: 'Hello' },
  transformStream: openaiStream,
});

⚠️ Note: ReadableStream can only be locked by one reader, avoid reusing the same instance.

🔍 TextDecoder/TextEncoder Explanation

When are they needed?

Practical Usage Suggestions:

transformStream: () =>
  new TransformStream({
    transform(chunk, controller) {
      // Safe approach: check type first
      const text = typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);

      // Now text is definitely a string
      controller.enqueue(text);
    },
  });

1️⃣ OpenAI Standard Format

Node.js Environment (Safe)

const openAIRequest = XRequest('https://api.example-openai.com/v1/chat/completions', {
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`, // Node.js environment variable
  },
  params: {
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: 'Hello' }],
    stream: true,
  },
});

Frontend Environment (Using Proxy)

// ❌ Dangerous: Do not configure token directly in frontend
// const openAIRequest = XRequest('https://api.example-openai.com/v1/chat/completions', {
//   headers: {
//     'Authorization': 'Bearer sk-xxxxxxxx', // ❌ Will expose key
//   },
// });

// ✅ Safe: Through same-origin proxy
const openAIRequest = XRequest('/api/proxy/openai', {
  params: {
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: 'Hello' }],
    stream: true,
  },
});

2️⃣ Alibaba Cloud Bailian (Tongyi Qianwen)

const bailianRequest = XRequest(
  'https://api.example-aliyun.com/api/v1/services/aigc/text-generation/generation',
  {
    headers: {
      Authorization: 'Bearer API_KEY',
    },
    params: {
      model: 'qwen-turbo',
      input: {
        messages: [{ role: 'user', content: 'Hello' }],
      },
      parameters: {
        result_format: 'message',
        incremental_output: true,
      },
    },
  },
);

3️⃣ Baidu Qianfan (Wenxin Yiyan)

const qianfanRequest = XRequest(
  'https://api.example-baidu.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions',
  {
    params: {
      messages: [{ role: 'user', content: 'Hello' }],
      stream: true,
    },
  },
);

4️⃣ Zhipu AI (ChatGLM)

const zhipuRequest = XRequest('https://api.example-zhipu.com/api/paas/v4/chat/completions', {
  headers: {
    Authorization: 'Bearer API_KEY',
  },
  params: {
    model: 'glm-4',
    messages: [{ role: 'user', content: 'Hello' }],
    stream: true,
  },
});

5️⃣ Xunfei Spark

const sparkRequest = XRequest('https://api.example-spark.com/v1/chat/completions', {
  headers: {
    Authorization: 'Bearer API_KEY',
  },
  params: {
    model: 'generalv3.5',
    messages: [{ role: 'user', content: 'Hello' }],
    stream: true,
  },
});

6️⃣ ByteDance Doubao

const doubaoRequest = XRequest('https://api.example-doubao.com/api/v3/chat/completions', {
  headers: {
    Authorization: 'Bearer API_KEY',
  },
  params: {
    model: 'doubao-lite-4k',
    messages: [{ role: 'user', content: 'Hello' }],
    stream: true,
  },
});

7️⃣ Local Private API

const localRequest = XRequest('http://localhost:3000/api/chat', {
  headers: {
    'X-API-Key': 'your-local-key',
  },
  params: {
    prompt: 'Hello',
    max_length: 1000,
    temperature: 0.7,
  },
});