111 lines
4.8 KiB
TypeScript
111 lines
4.8 KiB
TypeScript
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
|
||
}
|