FetchApiService ​

FetchApiService 是 @qxs-bns/utils 里基于 ky 的请求封装，适合需要统一错误处理、流式响应和双调用形态的场景。

请求调用链路 ​

这页最重要的不是某个孤立参数，而是先理解 FetchApiService 的调用顺序：先定义地址对象，再决定用 useApi 还是 apiClient，最后统一处理错误。
先把这条链路理解清楚，再看后面的不同调用写法就不会乱。

基础用法 ​

import { FetchApiService, ApiError } from '@qxs-bns/utils'

按 FetchApiService 的实际用法准备对应请求依赖即可，例如 ky。

useApi：返回 { res, error } ​

useApi 适合列表页、容错页和需要把错误统一收口到业务层的场景。
它有两种主用法：

• 单参数调用时，直接透传 ky 的 searchParams / json。
• 双参数调用时，会自动按 GET -> searchParams、非 GET -> json 的规则映射请求数据。

apiClient：直接返回数据或抛错 ​

apiClient 适合需要直接拿数据继续串联逻辑、或者明确希望在 try / catch 中处理异常的场景。
和 useApi 一样，它也支持单参数和双参数两种调用形态；差别在于失败时会直接抛出错误。

特殊场景：流式响应 ​

如果接口返回的是 text/event-stream，FetchApiService 不会帮你提前消费响应体，而是把 ReadableStream 直接放进 res 或直接作为返回值交给宿主。
也就是说，真正的分段读取、拼接和渲染仍然在业务侧完成。

规则总结 ​

使用建议 ​

• 页面想统一判断 error，优先用 useApi。
• 业务链路要直接 await 数据并走 try / catch，优先用 apiClient。
• 单参数调用不要再写 params / data，而是直接使用 ky 的 searchParams / json。
• 双参数调用更适合业务层封装，能少写一层 searchParams / json 判断。

相关文档 ​

• Utils 安装
• useApi
• Utils 总览