Files
short-drama-agent-front/src/lib/http.ts
T

111 lines
4.8 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
/**
* 解析公开响应及顶层同步错误码,不自动重试写入。
* @param path 不含统一 API 前缀的正式路径
* @param options 方法、请求体及取消信号
* @returns 解包后的公开响应
*/
export async function request<T>(path: string, options: RequestOptions = {}): Promise<T> {
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<T>(promise: Promise<T>): Promise<T | null> {
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
}