代码实现
/**
* Modern fetch wrapper for POSTing JSON to ExampleAI text generation API
* - Bearer token auth
* - Timeout with AbortController
* - Exponential backoff retries for transient errors (429/5xx, network)
* - Robust error normalization and response parsing (JSON/text)
*
* Works in modern browsers and Node.js >= 18 (built-in fetch).
*/
/** @typedef {{status:number, statusText:string, url:string, method:string, requestId?:string, headers:Record<string,string>, body?:unknown}} HTTPErrorMeta */
class HTTPError extends Error {
/**
* @param {string} message
* @param {HTTPErrorMeta} meta
*/
constructor(message, meta) {
super(message);
this.name = 'HTTPError';
this.status = meta.status;
this.statusText = meta.statusText;
this.url = meta.url;
this.method = meta.method;
this.headers = meta.headers;
this.requestId = meta.requestId;
this.body = meta.body;
}
}
/**
* Safe JSON parse with fallback to text.
* @param {Response} res
* @returns {Promise<{ data: any, rawText?: string }>}
*/
async function parseBody(res) {
const contentType = res.headers.get('content-type') || '';
const isJSON = contentType.includes('application/json');
if (isJSON) {
try {
const data = await res.json();
return { data };
} catch (e) {
// Fallthrough to text if JSON malformed
}
}
const rawText = await res.text();
let data = rawText;
if (isJSON) {
// If declared as JSON but failed to parse, preserve text for diagnostics
data = { parseError: true, raw: rawText };
}
return { data, rawText };
}
/**
* Normalize response headers to a simple object.
* @param {Headers} headers
*/
function headersToObject(headers) {
const obj = {};
headers.forEach((v, k) => {
obj[k.toLowerCase()] = v;
});
return obj;
}
/**
* Determine if an HTTP status is transient and worth retrying.
* @param {number} status
*/
function isTransientStatus(status) {
// 429 Too Many Requests, 408 Request Timeout, 5xx Server Errors
return status === 429 || status === 408 || (status >= 500 && status < 600);
}
/**
* Parse Retry-After header to milliseconds if present.
* @param {Headers} headers
*/
function parseRetryAfterMs(headers) {
const v = headers.get('retry-after');
if (!v) return undefined;
const seconds = Number(v);
if (!Number.isNaN(seconds)) return Math.max(0, seconds * 1000);
const date = new Date(v).getTime();
if (!Number.isNaN(date)) {
const ms = date - Date.now();
return ms > 0 ? ms : 0;
}
}
/**
* Sleep helper with optional jitter.
* @param {number} ms
* @param {boolean} jitter
*/
function sleep(ms, jitter = true) {
if (ms <= 0) return Promise.resolve();
const jittered = jitter ? Math.round(ms * (0.8 + Math.random() * 0.4)) : ms;
return new Promise((r) => setTimeout(r, jittered));
}
/**
* Connect a user-provided AbortSignal to our controller, so either can cancel.
* @param {AbortController} controller
* @param {AbortSignal | undefined} userSignal
* @returns {() => void} cleanup
*/
function linkAbortSignals(controller, userSignal) {
if (!userSignal) return () => {};
const onAbort = () => {
if (!controller.signal.aborted) {
try {
controller.abort(userSignal.reason ?? new DOMException('Aborted', 'AbortError'));
} catch {
controller.abort();
}
}
};
if (userSignal.aborted) onAbort();
userSignal.addEventListener('abort', onAbort, { once: true });
return () => userSignal.removeEventListener('abort', onAbort);
}
/**
* Core fetch with timeout + retry.
* @param {string} url
* @param {RequestInit & { method?: string }} options
* @param {{ timeoutMs?: number, retries?: number, backoffBaseMs?: number, backoffFactor?: number }} cfg
* @returns {Promise<Response>}
*/
async function fetchWithTimeoutAndRetry(url, options, cfg = {}) {
const {
timeoutMs = 15000,
retries = 2,
backoffBaseMs = 400,
backoffFactor = 2,
} = cfg;
let attempt = 0;
let lastError;
while (attempt <= retries) {
const controller = new AbortController();
const cleanupLink = linkAbortSignals(controller, options.signal);
const timeoutId = setTimeout(() => {
// Timeout: abort request
try {
controller.abort(new DOMException('Timeout', 'AbortError'));
} catch {
controller.abort();
}
}, timeoutMs);
try {
const res = await fetch(url, { ...options, signal: controller.signal });
clearTimeout(timeoutId);
cleanupLink();
if (res.ok) return res;
// Non-OK: read body safely and maybe retry if transient
const { data } = await parseBody(res);
if (isTransientStatus(res.status) && attempt < retries) {
const retryAfter = parseRetryAfterMs(res.headers);
const delay = retryAfter ?? backoffBaseMs * Math.pow(backoffFactor, attempt);
await sleep(delay, true);
attempt += 1;
continue;
}
const meta = {
status: res.status,
statusText: res.statusText,
url,
method: (options.method || 'GET').toUpperCase(),
requestId: res.headers.get('x-request-id') || res.headers.get('x-requestid') || undefined,
headers: headersToObject(res.headers),
body: data,
};
const message = `HTTP ${meta.status} ${meta.statusText} for ${meta.method} ${meta.url}`;
throw new HTTPError(extractErrorMessage(data) || message, meta);
} catch (err) {
clearTimeout(timeoutId);
cleanupLink();
// Abort or network errors might be retryable
const isAbort = err && typeof err === 'object' && err.name === 'AbortError';
const isNetwork = err instanceof TypeError && !isAbort; // fetch network error in browsers/Node often TypeError
const canRetry = (isAbort || isNetwork) && attempt < retries;
lastError = err;
if (canRetry) {
const delay = backoffBaseMs * Math.pow(backoffFactor, attempt);
await sleep(delay, true);
attempt += 1;
continue;
}
throw err;
}
}
// Exceeded attempts
throw lastError;
}
/**
* Try to extract a meaningful error message from server payload.
* @param {any} data
*/
function extractErrorMessage(data) {
if (!data) return '';
if (typeof data === 'string') return data.slice(0, 500);
if (typeof data.message === 'string') return data.message;
if (data.error && typeof data.error === 'object') {
if (typeof data.error.message === 'string') return data.error.message;
if (typeof data.error.code === 'string') return `${data.error.code}`;
}
return '';
}
/**
* Build headers for JSON request with Bearer auth.
* @param {string} token
* @param {Record<string, string>} [extra]
*/
function buildJSONHeaders(token, extra = {}) {
const headers = new Headers(extra);
if (token) headers.set('Authorization', `Bearer ${token}`);
headers.set('Accept', 'application/json');
headers.set('Content-Type', 'application/json');
return headers;
}
/**
* Safe JSON stringify that drops undefined and functions.
* @param {any} obj
*/
function safeStringify(obj) {
return JSON.stringify(
obj,
(_, v) => {
if (typeof v === 'function' || typeof v === 'undefined') return undefined;
if (typeof v === 'bigint') return v.toString();
return v;
}
);
}
/**
* Generate text via ExampleAI API.
* @param {{
* token: string, // Bearer token (do not hardcode in client)
* payload: Record<string, any>, // Request JSON body expected by the API
* timeoutMs?: number,
* retries?: number,
* fetchOptions?: Partial<RequestInit> // e.g., { signal, integrity, referrerPolicy }
* }} params
* @returns {Promise<{ data: any, response: Response }>}
*/
export async function generateText({ token, payload, timeoutMs = 15000, retries = 2, fetchOptions = {} }) {
if (!token || typeof token !== 'string') {
throw new Error('Missing Bearer token. Provide a valid token via "token" parameter.');
}
if (!payload || typeof payload !== 'object') {
throw new Error('Invalid payload. Provide a JSON-serializable object in "payload".');
}
const url = 'https://api.exampleai.com/v1/text/generate';
const options = {
method: 'POST',
// Never cache POST requests with credentials; rely on server-side caching if any
cache: 'no-store',
credentials: 'omit', // Since we use Bearer token, do not send cookies by default
redirect: 'follow',
keepalive: false,
headers: buildJSONHeaders(token, fetchOptions.headers || {}),
body: safeStringify(payload),
// Allow caller-provided options like signal, referrerPolicy, integrity
...fetchOptions,
// Ensure our headers/body override fetchOptions in case of conflicts
headers: buildJSONHeaders(token, fetchOptions.headers || {}),
body: safeStringify(payload),
};
const res = await fetchWithTimeoutAndRetry(url, options, {
timeoutMs,
retries,
backoffBaseMs: 400,
backoffFactor: 2,
});
const { data } = await parseBody(res);
return { data, response: res };
}
// Optional: small convenience wrapper that returns only parsed data
export async function generateTextData(params) {
const { data } = await generateText(params);
return data;
}
参数说明
- token
- 类型：string
- 说明：用于认证的 Bearer Token。请从安全来源注入（例如服务端下发、环境变量），不要在前端源码中硬编码。
- payload
- 类型：Record<string, any>
- 说明：API 请求体（JSON）。字段应遵循 ExampleAI 的接口定义（如 prompt、model、max_tokens、temperature 等）。
- timeoutMs
- 类型：number，默认 15000
- 说明：请求超时时间（毫秒）。到达超时会自动中止请求并按策略重试。
- retries
- 类型：number，默认 2
- 说明：瞬时错误（429/408/5xx、网络故障、超时）时的最大重试次数。
- fetchOptions
- 类型：Partial
- 说明：透传给 fetch 的可选项（如 signal、referrerPolicy、integrity、headers 等）。注意：headers、body 会由库正确覆盖以确保 JSON 和鉴权一致。
- 内置头部
- Authorization: Bearer
- Content-Type: application/json
- Accept: application/json
- 其他请求选项
- cache: 'no-store'：避免对 POST 请求进行浏览器缓存
- credentials: 'omit'：不发送 cookie，避免与 Bearer 混用造成风险
- redirect: 'follow'：遵循重定向
- keepalive: false：避免在页面卸载时的遗留请求问题
使用示例
import { generateTextData } from './exampleai.js';
// token 由服务端安全下发（例如通过 HTTP-only Cookie 换取临时 Bearer，或在 SSR 中注入）
const token = window.__EXAMPLEAI_TOKEN__;
const data = await generateTextData({
token,
payload: {
model: 'exampleai-text-1',
prompt: 'Write a haiku about autumn wind.',
max_tokens: 128,
temperature: 0.7,
// user: 'user-123', // 如 API 支持用户追踪，可传
},
timeoutMs: 12000,
retries: 2,
});
console.log('Generated:', data);
import { generateText } from './exampleai.js';
const token = process.env.EXAMPLEAI_API_KEY; // 不要硬编码在代码仓库
try {
const { data, response } = await generateText({
token,
payload: {
model: 'exampleai-text-1',
prompt: 'Summarize the benefits of typed JavaScript.',
max_tokens: 200,
temperature: 0.4,
},
timeoutMs: 15000,
retries: 3,
fetchOptions: {
// 可选：绑定外部取消信号
// signal: abortController.signal,
referrerPolicy: 'no-referrer',
},
});
console.log('status:', response.status);
console.log('result:', data);
} catch (err) {
// 详见下方“错误处理”
console.error(err);
}
const ac = new AbortController();
const p = generateTextData({
token,
payload: { model: 'exampleai-text-1', prompt: '...' },
fetchOptions: { signal: ac.signal },
});
setTimeout(() => ac.abort(), 3000); // 3 秒后主动取消
await p; // 将抛出 AbortError
注意事项
- 认证与安全
- 不要在前端仓库硬编码 API Key。推荐由后端安全签发临时 Token 或通过服务端代理调用。
- 使用 Bearer Token 时设置 credentials: 'omit'，避免携带 Cookie 混淆身份。
- CORS
- 浏览器环境下，跨域请求需服务端正确设置 Access-Control-Allow-Origin 等 CORS 头。代码不会绕过 CORS。
- 超时与重试
- 已对 429/408/5xx、网络错误与超时启用指数退避重试；非幂等接口请谨慎评估是否开启重试。
- 若服务端返回 Retry-After，将优先遵循该延迟。
- 数据序列化
- 自动以 application/json 发送请求体；undefined、function 将被安全丢弃，BigInt 转为字符串。
- 资源清理
- 超时和用户取消都会触发 AbortController，避免悬挂请求。
- 兼容性
- 需要现代浏览器或 Node.js >= 18（内置 fetch/AbortController）。
错误处理
- 错误类型
- HTTPError：服务器返回非 2xx
- 属性：status、statusText、url、method、headers、requestId、body（解析后的错误负载或文本）
- 典型场景：400 参数错误、401/403 鉴权失败、404 资源不存在、429 限流、5xx 服务器错误
- AbortError：请求被超时或手动取消
- TypeError：网络故障（DNS、连接中断等，浏览器/Node 常用）
- 建议的捕获与分支
try {
const { data } = await generateText({ token, payload });
// 使用 data
} catch (err) {
if (err instanceof HTTPError) {
// 服务器返回的详细错误
console.error('HTTPError:', {
status: err.status,
requestId: err.requestId,
body: err.body,
});
if (err.status === 401 || err.status === 403) {
// 引导刷新凭证或跳转登录
} else if (err.status === 429) {
// 可提示用户稍后重试
}
} else if (err && err.name === 'AbortError') {
console.warn('Request aborted (timeout or user cancel)');
} else {
// 网络错误或其他未知异常
console.error('Network/Unknown error:', err);
}
}
- 日志与追踪
- 如果服务端提供 X-Request-ID，请记录 err.requestId 以便问题排查。
- 在生产环境避免把完整 token 打到日志。只记录必要的元数据。
