以下是对 gc-qa-rag-frontend/src/services/ApiService.ts 文件的详细 Markdown 文档说明：

文档：`ApiService.ts` 代码详解

文件概述

本文件是前端与后端服务交互的核心接口层，封装了与 AI 问答、检索、思考流、用户反馈等相关的 HTTP 请求。通过统一的 API 服务模块，前端页面可以方便地调用后端能力，实现如智能检索、流式对话、思考推理和用户反馈收集等功能。该文件不仅提升了代码的复用性和可维护性，也为前后端解耦提供了良好基础。

主要接口说明

1. `getSearchResult`

该函数用于向后端 /search/ 接口发送检索请求。它接收关键词、模式、产品标识、会话 ID 和会话索引等参数，组装成请求体后以 POST 方式发送。请求头指定为 application/json，确保后端能正确解析。返回值为后端响应的 JSON 数据，通常包含检索结果列表。该接口适用于用户在搜索框输入关键词后，获取相关知识或文档的场景。

2. `getChatResult`

该函数实现了与后端 /chat_streaming/ 接口的流式对话能力。其核心流程如下：

组装请求体，包括当前关键词、历史消息数组（messages）、产品标识等。
创建 AbortController，用于后续中断请求（如用户主动取消）。
发送 POST 请求，获取响应流（response.body）。
通过 ReadableStreamDefaultReader 逐步读取后端返回的数据块（chunk），每读取到一块数据就通过回调 callback 实时传递给前端页面，实现流式输出体验。
当流结束或被中断时，回调会收到结束信号（end: true），前端可据此关闭加载动画等。

这种流式处理方式极大提升了用户体验，使得 AI 回复可以边生成边展示，减少等待时间。

3. `getThinkResult`

该函数与 getChatResult 类似，但请求的后端接口为 /think_streaming/。它用于 AI 的“思考流”场景，通常是让 AI 在给出最终答案前，先展示推理或思考过程。实现方式与 getChatResult 基本一致，区别仅在于接口路径和业务语义。通过流式回调，前端可以实时展示 AI 的推理过程，增强交互性和透明度。

4. `getFeedbackResult`

该函数用于收集用户对 AI 问答结果的反馈。它向 /feedback/ 接口发送包含问题、答案、评分、评论和产品标识的 POST 请求。后端可据此统计用户满意度、收集改进建议等。该接口的设计有助于持续优化 AI 服务质量，形成用户-产品-AI 的闭环反馈机制。

实现原理与设计考虑

1. 统一的 URL 管理

所有接口均以 URL_ROOT 为前缀，便于后续切换后端服务地址或支持多环境部署。当前配置为线上地址，也预留了本地开发的注释代码，方便开发调试。

2. 类型安全与参数校验

所有请求参数均有明确类型声明（如 MessageItem[]），提升了代码的可读性和类型安全性，减少了运行时错误。

3. 流式处理与用户体验

对于需要实时输出的 AI 对话和思考流，采用了 ReadableStream 的分块读取和回调机制。这样可以让用户在 AI 生成长文本时，逐步看到内容，显著提升了交互体验。通过 AbortController，用户还可以随时中断请求，增强了前端的灵活性和响应性。

4. 错误处理与健壮性

每个流式请求都对网络异常、响应体为空等情况进行了显式抛错，便于前端捕获并友好提示用户，提升了系统的健壮性。

5. 代码复用与解耦

所有 API 请求均封装为独立的异步函数，便于在不同页面和组件中复用。通过参数和回调灵活传递上下文和处理逻辑，实现了前后端的良好解耦。

应用场景

该模块适用于智能问答、知识检索、AI 对话、推理展示、用户反馈等多种场景。通过统一的 API 服务层，前端可以高效、灵活地调用后端 AI 能力，快速实现复杂的交互式 AI 应用。

代码示例

// 检索
getSearchResult("表格控件", "default", "forguncy", "session123", 0).then(
    (res) => {
        console.log(res);
    }
);

// 流式对话
getChatResult(
    "如何使用API？",
    [{ role: "user", content: "如何使用API？" }],
    "forguncy",
    (chunk, end) => {
        if (!end) {
            // 实时追加内容
            console.log(chunk);
        } else {
            // 结束处理
            console.log("对话结束");
        }
    },
    (controller) => {
        // 可用于中断请求
        // controller.abort();
    }
);

// 反馈
getFeedbackResult(
    "什么是API？",
    "API是应用程序接口。",
    5,
    "很有帮助",
    "forguncy"
).then((res) => {
    console.log(res);
});

总结

ApiService.ts 通过类型安全、流式处理、统一接口和健壮的错误处理，为前端与 AI 后端的高效交互提供了坚实基础。其设计兼顾了易用性、扩展性和用户体验，是现代智能前端应用不可或缺的服务层模块。

文档：ApiService.ts 代码详解