@djvlc/openapi-client-core 1.0.0

package/README.md

@@ -0,0 +1,318 @@
+# @djvlc/openapi-client-core
+
+OpenAPI Client 公共运行时库，为 `@djvlc/openapi-*-client` 系列包提供核心功能。
+
+## 功能
+
+- **结构化错误类**：`DjvApiError`、`NetworkError`、`TimeoutError`、`AbortError`
+- **增强版 fetch**：超时、重试（支持 Retry-After）、取消支持
+- **Middleware 系统**：请求/响应拦截
+- **拦截器系统**：更灵活的请求/响应/错误处理
+- **请求去重**：避免相同 GET 请求重复发送
+- **指标收集**：请求级别的性能指标和统计
+- **日志系统**：可配置的请求日志
+- **客户端工厂**：简化客户端创建
+- **自动版本注入**：构建时自动从 package.json 注入版本号
+
+## 安装
+
+通常你不需要直接安装这个包，它会作为 client 包的依赖自动安装。
+
+```bash
+pnpm add @djvlc/openapi-client-core
+```
+
+## 错误处理
+
+```typescript
+import { DjvApiError, NetworkError, TimeoutError, AbortError } from '@djvlc/openapi-client-core';
+
+try {
+  await client.PageApi.resolvePage({ pageUid: 'xxx' });
+} catch (e) {
+  if (DjvApiError.is(e)) {
+    // 业务错误（服务器返回的错误响应）
+    console.log('业务错误:', e.code, e.message);
+    console.log('HTTP 状态码:', e.status);
+    console.log('追踪 ID:', e.traceId);
+    
+    // 增强方法
+    if (e.isAuthError()) {
+      // 认证错误 (401/403)
+      redirectToLogin();
+    } else if (e.isRateLimited()) {
+      // 限流错误 (429)
+      const retryAfter = e.getRetryAfter(); // 秒
+      console.log('请等待', retryAfter, '秒后重试');
+    } else if (e.isServerError()) {
+      // 服务端错误 (5xx)
+      console.log('服务器繁忙，请稍后重试');
+    }
+  } else if (TimeoutError.is(e)) {
+    console.log('请求超时', e.timeoutMs, 'ms');
+  } else if (AbortError.is(e)) {
+    console.log('请求已取消');
+  } else if (NetworkError.is(e)) {
+    console.log('网络错误:', e.message);
+  }
+}
+```
+
+### DjvApiError 增强方法
+
+| 方法 | 说明 |
+|---|---|
+| `isUnauthorized()` | 是否 401 未授权 |
+| `isForbidden()` | 是否 403 禁止访问 |
+| `isAuthError()` | 是否认证错误 (401/403) |
+| `isClientError()` | 是否客户端错误 (4xx) |
+| `isServerError()` | 是否服务端错误 (5xx) |
+| `isRateLimited()` | 是否限流 (429) |
+| `isNotFound()` | 是否未找到 (404) |
+| `isConflict()` | 是否冲突 (409) |
+| `isValidationError()` | 是否验证失败 (400/422) |
+| `getRetryAfter()` | 获取 Retry-After 头的值（秒） |
+| `getRetryDelayMs(default)` | 获取重试延迟（毫秒） |
+
+## 重试配置（支持 Retry-After）
+
+```typescript
+import { createUserClient } from '@djvlc/openapi-user-client';
+
+const client = createUserClient({
+  baseUrl: 'https://api.example.com',
+  retry: {
+    maxRetries: 3,             // 最大重试次数
+    retryDelayMs: 1000,        // 基础延迟
+    exponentialBackoff: true,  // 指数退避
+    maxDelayMs: 30000,         // 最大延迟
+    respectRetryAfter: true,   // 尊重 Retry-After 响应头（默认 true）
+    onRetry: (error, attempt, delayMs) => {
+      console.log('第', attempt, '次重试，延迟', delayMs, 'ms');
+    },
+  },
+});
+```
+
+当服务器返回 `429 Too Many Requests` 或 `503 Service Unavailable` 并带有 `Retry-After` 头时，SDK 会优先使用该值作为重试延迟。
+
+## 请求去重
+
+避免相同的 GET 请求并发执行多次：
+
+```typescript
+import { createRequestDeduper } from '@djvlc/openapi-client-core';
+
+const deduper = createRequestDeduper({
+  getOnly: true, // 只对 GET 请求去重（默认）
+});
+
+// 包装 fetch
+const dedupedFetch = deduper.wrap(fetch);
+
+// 相同的请求只会执行一次，结果共享
+const [r1, r2] = await Promise.all([
+  dedupedFetch('/api/user'),
+  dedupedFetch('/api/user'),
+]);
+// 只发送了 1 个请求！
+```
+
+## 指标收集
+
+```typescript
+import { 
+  createMetricsCollector, 
+  createMetricsMiddleware 
+} from '@djvlc/openapi-client-core';
+
+// 创建指标收集器
+const metrics = createMetricsCollector({
+  maxMetrics: 1000,        // 最大保留数量
+  ttlMs: 3600000,          // 1 小时过期
+  onMetrics: (m) => {
+    // 每次请求完成时回调
+    console.log(m.method, m.path, '-', m.durationMs, 'ms');
+  },
+});
+
+// 添加到客户端
+const client = createUserClient({
+  baseUrl: 'https://api.example.com',
+  middleware: [createMetricsMiddleware(metrics)],
+});
+
+// 获取指标摘要
+const summary = metrics.summary();
+console.log('总请求数:', summary.totalRequests);
+console.log('成功率:', (summary.successRate * 100).toFixed(1), '%');
+console.log('P50:', summary.p50Ms, 'ms');
+console.log('P95:', summary.p95Ms, 'ms');
+console.log('P99:', summary.p99Ms, 'ms');
+
+// 按路径查看
+const pageMetrics = metrics.getByPath('/api/resolve/page');
+
+// 清空并获取所有指标
+const allMetrics = metrics.flush();
+```
+
+### 指标字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `requestId` | string | 请求唯一标识 |
+| `url` | string | 完整 URL |
+| `path` | string | 路径（不含 query） |
+| `method` | string | HTTP 方法 |
+| `startTime` | number | 开始时间戳 |
+| `endTime` | number | 结束时间戳 |
+| `durationMs` | number | 耗时（毫秒） |
+| `status` | number | HTTP 状态码 |
+| `success` | boolean | 是否成功 (2xx) |
+| `retryCount` | number? | 重试次数 |
+| `traceId` | string? | 追踪 ID |
+
+## 请求取消
+
+```typescript
+const controller = new AbortController();
+
+// 在某个时机取消请求
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  await client.PageApi.resolvePage(
+    { pageUid: 'xxx' },
+    { signal: controller.signal }
+  );
+} catch (e) {
+  if (AbortError.is(e)) {
+    console.log('请求已取消');
+  }
+}
+```
+
+## 日志
+
+```typescript
+import { createConsoleLogger } from '@djvlc/openapi-client-core';
+
+const client = createUserClient({
+  baseUrl: 'https://api.example.com',
+  debug: true, // 开启调试日志
+  logger: createConsoleLogger({
+    prefix: '[MyApp-API]',
+    level: 'debug',
+    timestamp: true,
+  }),
+});
+```
+
+## 拦截器
+
+```typescript
+const client = createUserClient({
+  baseUrl: 'https://api.example.com',
+  interceptors: {
+    request: [
+      (context) => {
+        // 修改请求
+        context.init.headers = new Headers(context.init.headers);
+        context.init.headers.set('X-Custom', 'value');
+        return context;
+      },
+    ],
+    response: [
+      async (response, context) => {
+        // 处理响应
+        if (response.status === 401) {
+          // Token 刷新逻辑
+          const newToken = await refreshToken();
+          // 重试请求...
+        }
+        return response;
+      },
+    ],
+    error: [
+      (error, context) => {
+        // 统一错误上报
+        reportError(error);
+        throw error;
+      },
+    ],
+  },
+});
+```
+
+## Token 自动刷新
+
+```typescript
+import { createTokenRefreshInterceptor } from '@djvlc/openapi-client-core';
+
+const client = createUserClient({
+  baseUrl: 'https://api.example.com',
+  interceptors: {
+    response: [
+      createTokenRefreshInterceptor({
+        refreshToken: async () => {
+          const newToken = await authService.refresh();
+          return newToken;
+        },
+      }),
+    ],
+  },
+});
+```
+
+## API
+
+### 错误类
+
+| 类 | 说明 |
+|---|---|
+| `DjvApiError` | 业务错误（HTTP 非 2xx 响应） |
+| `NetworkError` | 网络层错误 |
+| `TimeoutError` | 超时错误 |
+| `AbortError` | 请求被取消 |
+
+### 工具函数
+
+| 函数 | 说明 |
+|---|---|
+| `isRetryableError(error)` | 判断错误是否可重试 |
+| `getRetryDelay(error, defaultMs)` | 获取错误的推荐重试延迟 |
+| `createConsoleLogger(opts)` | 创建控制台日志器 |
+| `createSilentLogger()` | 创建静默日志器 |
+| `createTokenRefreshInterceptor(opts)` | 创建 Token 刷新拦截器 |
+| `createRequestDeduper(opts)` | 创建请求去重器 |
+| `createMetricsCollector(opts)` | 创建指标收集器 |
+| `createMetricsMiddleware(collector)` | 创建指标收集中间件 |
+
+### 类型
+
+| 类型 | 说明 |
+|---|---|
+| `BaseClientOptions` | 客户端配置选项 |
+| `RetryOptions` | 重试配置 |
+| `Logger` | 日志接口 |
+| `Middleware` | 中间件接口 |
+| `Interceptors` | 拦截器配置 |
+| `RequestMetrics` | 请求指标 |
+| `MetricsSummary` | 指标摘要 |
+| `MetricsCollector` | 指标收集器接口 |
+
+## 版本信息
+
+SDK 版本在构建时自动注入：
+
+```typescript
+import { SDK_VERSION, SDK_NAME, getSdkInfo } from '@djvlc/openapi-client-core';
+
+console.log(SDK_NAME + '@' + SDK_VERSION);
+// 输出: @djvlc/openapi-client-core@1.0.0
+
+const info = getSdkInfo();
+console.log(info);
+// 输出: { name: '@djvlc/openapi-client-core', version: '1.0.0' }
+```