@wapri/ghermes 0.0.0-stage → 3.0.0-beta.0

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './interceptor';

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export * from "./common";
+export * from "./interceptor";

package/dist/types/interceptor.d.ts

@@ -0,0 +1,13 @@
+import { InternalAxiosRequestConfig } from 'axios';
+export type HermesCustomizeInterceptor = (config: InternalAxiosRequestConfig<unknown>) => void;
+export type CustomizeInterceptor = {
+    request?: HermesCustomizeInterceptor;
+};
+/** 请求统一响应格式 */
+export type HermesResponse<T> = {
+    code: number;
+    message: string;
+    data: T;
+    /** 部分网关以 success 标记替代 code 判定 */
+    success?: boolean;
+};

package/dist/types/interceptor.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/error.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file error
+ * @description 请求错误处理纯函数
+ * - 保持 hermes「不绑定 UI 库」的设计：只负责提取文案与打标记
+ * - 提示由业务层自行决定（element-plus / antd / 自研组件均可）
+ */
+/** 请求层抛出的错误：带通知标记与追踪信息，业务 catch 可据此避免重复提示 */
+export type HermesRequestError = Error & {
+    /** 是否已在请求层提示过（用于避免业务 catch 再弹一遍） */
+    __notified?: boolean;
+    /** 业务错误码 */
+    code?: string | number;
+    /** 链路追踪 ID */
+    traceId?: string;
+    /** 原始响应体（可选） */
+    response?: unknown;
+};
+/**
+ * 解析错误响应体，兼容「对象」与「JSON 字符串」两种形态。
+ */
+export declare function normalizeErrorPayload(data: unknown): Record<string, unknown> | null;
+/**
+ * 标记「请求层已提示」的错误，附带 code / traceId。
+ */
+export declare function markNotifiedError(message: string, extra?: {
+    code?: string | number;
+    traceId?: string;
+}): HermesRequestError;
+/**
+ * 提取可展示的请求错误文案。
+ * 过滤 `error` / `cancel` / `invalid` 及 `Request failed with status code` 等泛化文案。
+ *
+ * @param error 任意错误对象
+ * @param fallback 无法提取时的兜底文案
+ */
+export declare function resolveRequestErrorMessage(error: unknown, fallback?: string): string;
+/**
+ * 判断错误是否已在请求层提示过（业务 catch 可直接据此跳过重复提示）。
+ */
+export declare function isNotifiedError(error: unknown): boolean;

package/dist/utils/error.js

@@ -0,0 +1,66 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+/**
+ * @file error
+ * @description 请求错误处理纯函数
+ * - 保持 hermes「不绑定 UI 库」的设计：只负责提取文案与打标记
+ * - 提示由业务层自行决定（element-plus / antd / 自研组件均可）
+ */
+
+/** 请求层抛出的错误：带通知标记与追踪信息，业务 catch 可据此避免重复提示 */
+
+/**
+ * 解析错误响应体，兼容「对象」与「JSON 字符串」两种形态。
+ */
+export function normalizeErrorPayload(data) {
+  if (!data) return null;
+  if (_typeof(data) === 'object') return data;
+  if (typeof data === 'string' && data) {
+    try {
+      var parsed = JSON.parse(data);
+      return parsed && _typeof(parsed) === 'object' ? parsed : null;
+    } catch (_unused) {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * 标记「请求层已提示」的错误，附带 code / traceId。
+ */
+export function markNotifiedError(message) {
+  var extra = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var err = new Error(message);
+  err.__notified = true;
+  if (extra.code !== undefined) err.code = extra.code;
+  if (extra.traceId !== undefined) err.traceId = extra.traceId;
+  return err;
+}
+
+/**
+ * 提取可展示的请求错误文案。
+ * 过滤 `error` / `cancel` / `invalid` 及 `Request failed with status code` 等泛化文案。
+ *
+ * @param error 任意错误对象
+ * @param fallback 无法提取时的兜底文案
+ */
+export function resolveRequestErrorMessage(error) {
+  var _err$response;
+  var fallback = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : '操作失败';
+  if (!error || error === 'error' || error === 'cancel') return fallback;
+  var err = error;
+  if (err.message === 'invalid') return '';
+  var payload = normalizeErrorPayload((_err$response = err.response) === null || _err$response === void 0 ? void 0 : _err$response.data);
+  var biz = payload && (payload.message || payload.msg) || err.message;
+  if (biz && typeof biz === 'string' && biz !== 'error' && !biz.includes('Request failed with status code')) {
+    return biz;
+  }
+  return fallback;
+}
+
+/**
+ * 判断错误是否已在请求层提示过（业务 catch 可直接据此跳过重复提示）。
+ */
+export function isNotifiedError(error) {
+  return Boolean(error && error.__notified);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './snowflake';
+export * from './error';

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from "./snowflake";
+export * from "./error";

package/dist/utils/snowflake.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file snowflake
+ * @description 雪花 Long 精度保护
+ * - 后端雪花 ID 通常为 19 位，超出 JS Number.MAX_SAFE_INTEGER（2^53-1）
+ * - 若以 JSON 数字返回，会在 JSON.parse 阶段丢精度
+ * - 因此：响应侧在 parse 前改写为字符串；请求侧把 ID 字段收成字符串
+ */
+/** 视为长整型的最小位数 */
+export declare const LONG_DIGIT_MIN = 16;
+/**
+ * 将 JSON 文本中「未加引号」的超长整数改为字符串，再 parse。
+ * 已在引号内的内容（含 URL）不会被改写。
+ */
+export declare function parseJsonSafeLong(text: string): unknown;
+/**
+ * axios transformResponse：安全解析 JSON，解析失败或其他类型原样返回。
+ */
+export declare function axiosTransformSafeLong(data: unknown): unknown;
+/**
+ * 递归处理请求 payload：把可能丢精度的 ID 字段强制转为字符串。
+ * - null/undefined 原样返回
+ * - 数组逐项递归
+ * - 对象递归每个字段；FormData / Blob / File 直接跳过
+ * - 叶子字段命中 ID 规则且为 16 位及以上数字时转字符串
+ */
+export declare function stringifySnowflakeFields(value: unknown, key?: string): unknown;

package/dist/utils/snowflake.js

@@ -0,0 +1,79 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+/**
+ * @file snowflake
+ * @description 雪花 Long 精度保护
+ * - 后端雪花 ID 通常为 19 位，超出 JS Number.MAX_SAFE_INTEGER（2^53-1）
+ * - 若以 JSON 数字返回，会在 JSON.parse 阶段丢精度
+ * - 因此：响应侧在 parse 前改写为字符串；请求侧把 ID 字段收成字符串
+ */
+
+/** 视为长整型的最小位数 */
+export var LONG_DIGIT_MIN = 16;
+
+/**
+ * 将 JSON 文本中「未加引号」的超长整数改为字符串，再 parse。
+ * 已在引号内的内容（含 URL）不会被改写。
+ */
+export function parseJsonSafeLong(text) {
+  if (typeof text !== 'string') return text;
+  var trimmed = text.trim();
+  if (!trimmed || trimmed[0] !== '{' && trimmed[0] !== '[') {
+    return text;
+  }
+  var quoted = trimmed.replace(/"(?:\\.|[^"\\])*"|(-?\d{16,})/g, function (match, num) {
+    return num != null ? "\"".concat(num, "\"") : match;
+  });
+  return JSON.parse(quoted);
+}
+
+/**
+ * axios transformResponse：安全解析 JSON，解析失败或其他类型原样返回。
+ */
+export function axiosTransformSafeLong(data) {
+  if (typeof data !== 'string' || !data) return data;
+  try {
+    return parseJsonSafeLong(data);
+  } catch (_unused) {
+    return data;
+  }
+}
+
+/** 命中 ID 语义的字段名（首尾 Id/ID，或 fileId/id） */
+function looksLikeIdField(key) {
+  return /(?:^|Id|ID)$/.test(key) || key === 'fileId' || key === 'id';
+}
+
+/**
+ * 递归处理请求 payload：把可能丢精度的 ID 字段强制转为字符串。
+ * - null/undefined 原样返回
+ * - 数组逐项递归
+ * - 对象递归每个字段；FormData / Blob / File 直接跳过
+ * - 叶子字段命中 ID 规则且为 16 位及以上数字时转字符串
+ */
+export function stringifySnowflakeFields(value, key) {
+  if (value == null) return value;
+  if (Array.isArray(value)) {
+    return value.map(function (item) {
+      return stringifySnowflakeFields(item);
+    });
+  }
+  if (_typeof(value) === 'object') {
+    if (value instanceof FormData || value instanceof Blob || value instanceof File) {
+      return value;
+    }
+    var out = {};
+    Object.keys(value).forEach(function (k) {
+      out[k] = stringifySnowflakeFields(value[k], k);
+    });
+    return out;
+  }
+  // 叶子值：命中 ID 规则且为超长数字时转字符串
+  if (key && looksLikeIdField(key) && (typeof value === 'number' || typeof value === 'string')) {
+    // 已丢精度的 Number 再 String 也无法恢复，只能告警
+    if (typeof value === 'number' && !Number.isSafeInteger(value)) {
+      console.error('[hermes:snowflake] 请求字段已丢精度，无法恢复:', key, value);
+    }
+    if (/^\d{16,}$/.test(String(value))) return String(value);
+  }
+  return value;
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@wapri/ghermes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.0-beta.0",
+  "description": "公共请求库,维护了统一请求与不同模块的请求",
+  "keywords": [],
+  "license": "UNLICENSED",
+  "author": "wa",
+  "sideEffects": false,
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "axios": "^1.16.1",
+    "@wapri/gbase": "^1.0.1-beta.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependenciesMeta": {},
+  "scripts": {
+    "build": "father build",
+    "dev": "father dev"
+  }
 }