import { businessErrorMessages, configurationErrorText, userFacingText } from './user-facing-text' /** HTTP 错误携带状态码与后端细节,供页面区别空数据、校验错误与网络故障。 */ export class ApiError extends Error { constructor( message: string, public readonly status: number, public readonly details?: unknown, /** 同步接口的顶层业务错误码;普通 400 或网络错误可缺省。 */ public readonly code?: string ) { super(message) this.name = 'ApiError' } } /** 请求选项;长工作流显式关闭超时,不自动重试任何 POST。 */ export interface RequestOptions { method?: 'GET' | 'POST' | 'PUT' | 'DELETE' body?: unknown signal?: AbortSignal timeoutMs?: number } /** 判断可安全访问键的 JSON 对象。 */ function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) } /** * 解析公开响应及顶层同步错误码,不自动重试写入。 * @param path 不含统一 API 前缀的正式路径 * @param options 方法、请求体及取消信号 * @returns 解包后的公开响应 */ export async function request(path: string, options: RequestOptions = {}): Promise { const base = (import.meta.env.VITE_API_BASE_URL || '/api').replace(/\/$/, '') const multipart = typeof FormData !== 'undefined' && options.body instanceof FormData const body: BodyInit | undefined = options.body === undefined ? undefined : multipart ? (options.body as FormData) : JSON.stringify(options.body) const controller = new AbortController() const timeoutMs = options.timeoutMs ?? 30_000 const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : undefined const abort = () => controller.abort() options.signal?.addEventListener('abort', abort, { once: true }) if (options.signal?.aborted) controller.abort() try { const response = await fetch(base + path, { method: options.method ?? 'GET', headers: { Accept: 'application/json', ...(options.body === undefined || multipart ? {} : { 'Content-Type': 'application/json' }) }, body, signal: controller.signal }) const text = await response.text() let data: unknown try { data = text ? JSON.parse(text) : undefined } catch { throw new ApiError('服务暂时无法返回有效结果,请稍后重试。', response.status) } if (!response.ok) { const message = isRecord(data) && typeof data.message === 'string' ? data.message : `请求失败(${response.status})` throw new ApiError( message, response.status, isRecord(data) ? (data.details ?? data.issues ?? data.error) : data, isRecord(data) && typeof data.code === 'string' ? data.code : undefined ) } return (isRecord(data) && 'data' in data ? data.data : data) as T } catch (error) { if (error instanceof ApiError) throw error if (options.signal?.aborted) throw error if (controller.signal.aborted) throw new ApiError('请求等待超时。后台任务可能仍在运行,请先刷新状态,不要重复提交。', 0) throw new ApiError('暂时无法连接服务,请检查网络后重试;已提交的任务可能仍在运行。', 0) } finally { clearTimeout(timer) options.signal?.removeEventListener('abort', abort) } } /** 仅允许指定的“尚无 checkpoint”404 视为缺省,不吞掉 500 或网络错误。 */ export async function optionalResource(promise: Promise): Promise { try { return await promise } catch (error) { if (error instanceof ApiError && error.status === 404) return null throw error } } /** * 页面统一显示业务原因,原始错误与详情仍保留供程序判断和导出。 * @param error 原始请求或操作错误 * @returns 普通用户可理解的原因和处理建议 */ export function errorMessage(error: unknown): string { const fallback = '操作失败,请刷新后重试。' if (error instanceof ApiError) { const configurationMessage = configurationErrorText(error.code) ?? configurationErrorText(isRecord(error.details) ? error.details.code : undefined) if (configurationMessage) return configurationMessage return ( [ ...new Set( [userFacingText(error.message, fallback), ...businessErrorMessages(error.details)].filter(Boolean) ) ].join(';') || fallback ) } return error instanceof Error ? userFacingText(error.message, fallback) || fallback : fallback }