test-api-client 0.0.1

package/README.md

@@ -0,0 +1,587 @@
+## **1. 项目概述**
+
+本项目是一个使用 TSUP 作为构建工具，使用TypeScript、Axios 和 Crypto-JS 等技术构建的 ApiClient SDK库，提供了一套完整的客户端解决方案，包括 API 请求处理、sign签名机制、Token 管理、日志记录和错误处理等功能，最终通过npm打包为私有库供客户端使用，包名待确认（api-client、http-client）。
+
+## **2. 功能介绍**
+
+### **2.1 核心功能**
+
+| 功能模块     | 描述                                                         |
+| ------------ | ------------------------------------------------------------ |
+| API 请求处理 | 封装了 Axios 库，提供统一的请求接口                          |
+| 签名机制     | 自动生成请求签名，确保接口安全性                             |
+| Token 管理   | 支持 Token 存储、获取和自动刷新                              |
+| 日志记录     | 提供多级别的日志记录功能，支持自定义日志输出                 |
+| 业务错误映射 | 基于后端错误码文档实现完整的错误码映射，支持 HTTP 状态码和业务错误码的统一处理 |
+| 错误处理     | 统一的错误类型定义和错误回调机制                             |
+
+### **2.2 扩展功能**
+
+\- **日志级别控制**：支持  `ALL`、`ERROR`、`FATAL` 、`INFO` 、`TRACE`、`DEBUG`、`WARN`、`OFF` 8个级别的日志控制（采用业界通用的日志标准体系，例如[Sentry](https://docs.sentry.io/platforms/javascript/logs/)/[Log4j](https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/Level.html)等通用日志框架）
+
+\- **自定义日志****回调**：支持将日志输出到外部系统，可以将格式化后的日志通过事件发送至公司统一的日志管理平台
+
+## **3. 技术选型与分析**
+
+### **3.1 核心技术栈**
+
+| 技术/库           | 版本  | 用途                    | 选型理由                                                     |
+| ----------------- | ----- | ----------------------- | ------------------------------------------------------------ |
+| TypeScript        | 5.4.5 | 开发语言                | 提供类型安全，增强代码可维护性和可读性                       |
+| Axios             | 1.6.7 | HTTP 客户端             | 成熟稳定，支持浏览器和 Node.js 环境，提供丰富的拦截器功能    |
+| Crypto-JS         | 4.2.0 | 加密库                  | 用于生成请求签名，支持 MD5 等多种加密算法                    |
+| ESLint            | 9.3.0 | 代码质量检查            | 提供强大的代码质量检查能力，支持自定义规则，社区生态丰富     |
+| TypeScript ESLint | 8.0.0 | TypeScript 代码检查规则 | 为 TypeScript 设计，与 ESLint 无缝集成，提供针对 TypeScript 语法的专业检查规则 |
+| tsup              | 8.0.2 | 构建工具                | 基于 ESBuild，构建速度极快，配置简单，原生支持 TypeScript 和多格式输出 |
+
+## **4. 架构设计**
+
+### **4.1 整体架构**
+
+#### **4.1.1 目录结构**
+
+```Plain
+src/
+├── api/                  # API 接口层 - 业务接口封装
+│   └── v1/               # API 版本 v1
+│       ├── airline.ts    # 航线相关接口
+│       ├── auth.ts       # 认证相关接口
+│       ├── fence.ts      # 围栏相关接口
+│       └── index.ts      # API 入口文件，导出所有 v1 接口
+├── client/               # 客户端核心层 - 基础功能实现
+│   ├── error-codes.ts    # 错误码映射，包含 HTTP 状态码和业务错误码的映射关系
+│   ├── http.ts           # HTTP 请求处理，包含拦截器、请求/响应处理
+│   ├── logger.ts         # 日志记录功能，支持多级别日志
+│   ├── sign.ts           # 签名生成与验证
+│   ├── state.ts          # 状态管理，存储配置等
+│   └── token.ts          # Token 存储与管理
+├── types/                # 类型定义层 - TypeScript 类型定义
+│   └── v1/               # API 版本 v1 类型定义
+│       ├── airline.ts    # 航线相关类型
+│       ├── auth.ts       # 认证相关类型
+│       ├── fence.ts      # 围栏相关类型
+│       └── index.ts      # 类型入口文件，导出所有 v1 类型
+├── index.ts              # SDK 主入口，导出所有公开 API
+└── types.ts              # 核心类型定义，包含 SDK 配置、错误类型等
+```
+
+### **4.2 核心流程**
+
+#### **4.2.1 API 请求流程**
+
+```mermaid
+sequenceDiagram
+    participant App as 应用程序
+    participant API as API 方法
+    participant Request as requestData 函数
+    participant Client as HTTP 客户端
+    participant Interceptor as 请求拦截器
+    participant Server as 服务器
+    participant ResponseInterceptor as 响应拦截器
+    
+    App->>API: 调用 API 方法
+    API->>Request: 调用 requestData
+    Request->>Client: 获取 HTTP 客户端实例
+    Client->>Interceptor: 执行请求
+    
+    Note over Interceptor: 请求拦截器处理流程
+    Interceptor->>Interceptor: 1. 生成时间戳和随机 nonce
+    Interceptor->>Interceptor: 2. 设置 Token 到请求头
+    Interceptor->>Interceptor: 3. 生成请求签名并设置到请求头
+    
+    Interceptor->>Server: 发送 HTTP 请求
+    Server-->>ResponseInterceptor: 返回响应
+    
+    Note over ResponseInterceptor: 响应拦截器处理流程
+    ResponseInterceptor->>ResponseInterceptor: 1. 记录请求日志
+    ResponseInterceptor->>ResponseInterceptor: 2. 检查业务状态码
+    
+    alt 业务状态码正常
+        ResponseInterceptor-->>Request: 返回响应数据
+        Request-->>API: 返回数据
+        API-->>App: 返回数据
+    else 业务状态码错误
+        ResponseInterceptor->>ResponseInterceptor: 3. 生成 ApiError 并抛出
+        ResponseInterceptor-->>Request: 抛出错误
+        Request-->>API: 抛出错误
+        API-->>App: 抛出错误
+    end
+    
+    alt 401 错误 (Token 过期)
+        ResponseInterceptor->>ResponseInterceptor: 2. Token 自动刷新
+        ResponseInterceptor-->>Request: 重新执行请求
+    else 其他 HTTP 错误
+        ResponseInterceptor->>ResponseInterceptor: 3. 生成 ApiError 并抛出
+        ResponseInterceptor-->>Request: 抛出错误
+        Request-->>API: 抛出错误
+        API-->>App: 抛出错误
+    end
+```
+
+#### **4.2.2 Token 刷新流程**
+```mermaid
+flowchart TD
+    A[检测到 401 错误] --> B{是否正在刷新 Token?}
+    
+    B -->|是| C[将当前请求加入 pending 队列]
+    C --> D[等待刷新完成]
+    
+    B -->|否| E[设置 isRefreshing = true]
+    E --> F[调用 /auth/v1/refresh 接口]
+    
+    F --> G{刷新成功?}
+    
+    G -->|是| H[更新 Token 存储]
+    H --> I[记录 Token 刷新日志]
+    I --> J[处理 pending 队列中的请求]
+    J --> K[设置 isRefreshing = false]
+    K --> L[清空 refreshPromise]
+    L --> M[返回新 Token]
+    
+    G -->|否| N[处理 pending 队列中的请求]
+    N --> K
+    L --> O[抛出错误]
+    
+    D --> M
+    
+    classDef process fill:#cdf,stroke:#333,stroke-width:1px;
+    classDef decision fill:#ff9,stroke:#333,stroke-width:1px;
+    classDef action fill:#bbf,stroke:#333,stroke-width:1px;
+    
+    class A,C,D,E,F,H,I,J,K,L,M,N,O process;
+    class B,G decision;
+```
+
+
+## **5. 核心模块设计与实现**
+
+### **5.1 HTTP 客户端模块 (client/http.ts)**
+
+#### **5.1.1 主要功能**
+
+- 创建和配置 Axios 实例
+- 请求拦截器：添加签名、Token 等
+- 响应拦截器：处理业务错误、Token 刷新等
+- 提供统一的请求方法
+
+#### **5.1.2 核心代码结构**
+
+```TypeScript
+// 创建 HTTP 客户端
+export function createHttpClient(config: ApiClientConfig): AxiosInstance
+
+// 初始化 Api 客户端
+export function initApiClient(config: ApiClientConfig): void
+
+// 获取 HTTP 客户端实例
+export function getHttpClient(): AxiosInstance
+
+// 请求数据
+export async function requestData<TData>(
+  cfg: AxiosRequestConfig,
+  apiName?: string
+): Promise<TData>
+
+// 刷新 Token
+async function refreshToken(instance: AxiosInstance, config: ApiClientConfig): Promise<string>
+```
+
+### **5.2 签名模块 (client/sign.ts)**
+
+#### **5.2.1 签名算法**
+
+按[对外接口签名方案](https://d78exgr9mw.feishu.cn/wiki/EsJpw0QbkiIIgGk2j9Scux8wnTC?fromScene=spaceOverview)对接口进行加密签名，为保障接口通信安全，所有请求必须进行签名验证。签名基于请求参数、时间戳、随机数和密钥生成，用于验证请求的合法性和完整性。
+
+#### **5.2.2 签名生成步骤**
+
+1. **参数收集**：收集 URI、时间戳、nonce、查询参数和请求体
+2. **参数过滤**：移除 null、undefined 和空字符串值
+3. **参数排序**：按参数名ASCII 码升序排序
+4. **拼接签名字符串**：格式为 `key1=value1&key2=value2&secret=secret`
+5. **加密**：使用 MD5 算法，加盐加密
+
+#### **5.2.2 核心代码**
+
+```TypeScript
+function generateSignature(params: Record<string, unknown>, secret: string, salt: string) {
+  // 1. 按key排序并拼接字符串
+  const sortedKeys = Object.keys(params).sort();
+  const paramString = sortedKeys
+    .map(key => `${key}=${params[key]}`)
+    .join('&') + `&secret=${secret}`;
+  
+  // 2. 转为小写并使用盐值进行MD5
+  const strToSign = paramString.toLowerCase();
+  const signature = CryptoJS.MD5(strToSign + salt).toString();
+  
+  return signature;
+}
+```
+
+### **5.3 Token 管理模块 (client/token.ts)**
+
+#### **5.3.1 主要功能**
+
+- Token 的存储和获取
+- 支持 Token 失效自动刷新重试
+
+#### **5.3.2 核心代码**
+
+```TypeScript
+export function setApiToken(token: string | undefined): void
+export function getApiToken(): string | undefined
+```
+
+### **5.4 日志模块 (client/logger.ts)**
+
+#### **5.4.1 主要功能**
+
+- 日志级别顺序（TRACE < DEBUG < INFO < WARN < ERROR < FATAL），ALL和OFF是用于配置的特殊级别：
+  - ALL：启用所有级别的日志记录
+  - TRACE：最详细的日志信息
+  - DEBUG：调试信息，有助于诊断问题
+  - INFO：程序正常运行时的信息
+  - WARN：潜在问题或非预期情况，但系统仍能正常运行
+  - ERROR：错误事件影响单个操作，但系统整体仍可用
+  - FATAL：导致应用程序完全终止的严重错误
+  - OFF: 关闭所有日志记录
+- 日志格式，按照对接ELK、Splunk等主流分析日志系统的实际格式标准（1：JSON格式，2：传统JSON格式）：
+
+JSON格式：
+
+| 字段        | 类型   | 说明                              | 示例                          |
+| ----------- | ------ | --------------------------------- | ----------------------------- |
+| timestamp   | string | ISO 8601 格式时间戳（精确到毫秒） | "2024-04-09T13:36:39.947Z"    |
+| level       | string | 日志级别（标准值）                | "INFO"                        |
+| module      | string | 代码模块（业务逻辑分组）          | "api-client"                  |
+| event       | string | 事件类型（业务语义）              | "request"                     |
+| request     | object | 请求详情                          | 包含 URL、方法、headers、body |
+| response    | object | 响应详情                          | 包含 status、headers、body    |
+| duration_ms | number | 请求耗时（毫秒）                  | 125                           |
+| message     | string | 消息描述                          | login post /c2/auth/v1/login  |
+
+```SQL
+{
+  "timestamp": "2026-01-23T02:37:42.257Z",
+  "level": "INFO",
+  "module": "api-client",
+  "event": "request",
+  "message": "login post /c2/auth/v1/login",
+  "request": {
+    "url": "/c2/auth/v1/login",
+    "method": "post",
+    "headers": {
+      "Accept": "application/json, text/plain, */*",
+      "Content-Type": "application/json",
+      "X-Timestamp": "1769135861970",
+      "X-Nonce": "mkq9tbkjdrx989ako2k",
+      "X-Sign": "543f1e0e3b4cc16909faf420affd8d09"
+    },
+    "body": "{\"username\":\"admin\",\"password\":\"admin\"}"
+  },
+  "response": {
+    "status": 200,
+    "body": {
+      "code": 200,
+      "msg": "登录成功",
+      "sub_code": 0,
+      "sub_msg": "成功",
+      "data": {
+        "token": "b814b844-a822-4bf2-b920-700cafe05131",
+        "expires_in": 1209568,
+        "nickName": "管理员",
+        "avatar": "admin.png"
+      }
+    }
+  },
+  "duration_ms": 286
+}
+```
+
+2：传统格式
+
+时间戳 [日志级别] [代码模块] [事件类型] [耗时][消息描述] 
+
+```Bash
+2026-01-23T02:40:13.791Z [INFO] [api-client] [request] [duration: 38ms] - login post /c2/auth/v1/login
+  Request: post /c2/auth/v1/login
+  Headers: {"Accept":"application/json, text/plain, */*","Content-Type":"application/json","X-Timestamp":"1769136013753","X-Nonce":"mkq9wkopau6o8mzns5","X-Sign":"0f161e7138a9be5cf7c36a0d69d7fc71"}
+  Body: "{\"username\":\"admin\",\"password\":\"admin\"}"
+  Response: 200
+  Body: {"code":200,"msg":"登录成功","sub_code":0,"sub_msg":"成功","data":{"token":"2f0173cd-4515-4203-9b34-7438b4fd5f20","expires_in":1209569,"nickName":"管理员","avatar":"admin.png"}}
+```
+
+目前主流日志系统集成均支持JSON格式，传统格式为预留
+
+| 日志系统     | 配置方式             | 解析效果                                  |
+| ------------ | -------------------- | ----------------------------------------- |
+| ELK Stack    | 默认 JSON 解析       | 自动提取 timestamp、level、service 等字段 |
+| Grafana Loki | json 解析器          | 无需配置，直接按字段索引                  |
+| Splunk       | JSON 解析器          | 字段自动映射到 level、service 等          |
+| 阿里云 SLS   | 选择 "JSON" 解析模式 | 字段自动识别，可直接创建索引              |
+
+- 日志输出（控制台和自定义回调）
+
+#### **5.4.2 核心代码**
+
+```TypeScript
+/**
+ * 生成结构化日志
+ * @param config - Api客户端配置
+ * @param level - 日志级别
+ * @param event - 事件类型
+ * @param message - 日志消息
+ * @param httpLog - HTTP日志结构（可选）
+ * @param meta - 其他元数据（可选）
+ * @returns 结构化日志对象
+ */
+function generateStructuredLog(
+  config: ApiClientConfig | undefined,
+  level: ApiLogLevel,
+  event: string,
+  message: string,
+  httpLog?: ApiStructuredHttpLog,
+  meta?: unknown
+): ApiStructuredLog {
+  const structuredLog: ApiStructuredLog = {
+    timestamp: new Date().toISOString(),
+    level,
+    module: 'api-client',
+    event,
+    message
+  };
+
+  // 添加HTTP相关信息
+  if (httpLog) {
+    if (httpLog.url && httpLog.method) {
+      structuredLog.request = {
+        url: httpLog.url,
+        method: httpLog.method,
+        headers: httpLog.headers as Record<string, string>,
+        body: formatSensitiveData(httpLog.request)
+      };
+    }
+    
+    if (httpLog.response && typeof httpLog.response === 'object') {
+      const responseObj = httpLog.response as any;
+      structuredLog.response = {
+        status: responseObj.status || responseObj.code || 0,
+        body: responseObj
+      };
+    }
+    if (httpLog.durationMs) {
+      structuredLog.duration_ms = httpLog.durationMs;
+    }
+  }
+  // 添加其他元数据
+  if (meta) {
+    Object.assign(structuredLog, meta);
+  }
+
+  return structuredLog;
+}
+```
+
+### **5.5 状态管理模块 (client/state.ts)**
+
+#### **5.5.1 主要功能**
+
+- 存储 SDK 配置
+- 存储 Axios 实例
+- 存储 Token
+
+#### **5.5.2 核心代码**
+
+```TypeScript
+export interface ApiClientState {
+  config?: ApiClientConfig;
+  axios?: AxiosInstance;
+  token?: string;
+}
+```
+
+## **6.**  **类型定义**
+
+### **6.1 核心类型**
+
+#### **6.1.1 ApiClientConfig**
+
+```TypeScript
+export interface ApiClientConfig {
+  baseUrl: string;           // API 基础 URL
+  secret: string;            // 密钥
+  salt: string;              // 加密盐值
+  logLevel?: ApiLogLevel;     // 日志等级
+  logger?: (line: string, level: Exclude<ApiLogLevel, 'all'>, meta?: unknown) => void;  // 自定义日志输出
+  businessErrorMessageMap?: Record<number, string>;  // 业务错误码映射
+  tokenRefreshMaxRetries?: number;//Token失效时的最大重试次数，设置为0则一直重试
+}
+```
+
+#### **6.1.2 ApiApiResponse**
+
+```TypeScript
+export interface ApiApiResponse<T> {
+  code: number;              // 响应状态码
+  msg?: string;              // 响应消息（短）
+  message?: string;          // 响应消息（长）
+  sub_code?: number;         // 子错误码
+  sub_msg?: string;          // 子错误消息
+  data?: T;                  // 响应数据
+}
+```
+
+### **6.3 日志级别**
+
+```TypeScript
+export type ApiLogLevel = 'ALL' | 'ERROR' | 'FATAL ' | 'INFO ' | 'TRACE' | 'DEBUG' | 'WARN' | 'OFF
+```
+
+### 6.4 **错误级别枚举**
+
+```TypeScript
+/**
+ * HTTP状态码映射
+ */
+export const HTTP_STATUS_MAP: Record<number, string> = {
+  200: '请求成功',
+  400: '参数列表错误',
+  401: '未授权',
+  403: '访问受限，授权过期',
+  404: '资源或服务未找到',
+  405: '不允许的HTTP方法',
+  408: '请求超时',
+  500: '系统内部错误',
+  501: '未实现',
+  503: '服务不可用'
+};
+export enum FunctionModule {
+  GENERAL = '00',        // 通用/系统
+  USER_AUTH = '01',      // 用户认证
+  SELF_CHECK = '02',     // 自检维护
+  AIRLINE = '03',        // 航线管理
+  FENCE = '04',          // 电子围栏
+  REAL_TIME_DATA = '05', // 实时数据
+  VIDEO_STREAM = '06',   // 视频流
+  AUDIO_STREAM = '07',   // 音频流
+  MEDIA_SERVICE = '08',  // 流媒体服务
+  AV_CONTROL = '09',     // 音视频控制
+  LOG_FILE = '10',       // 日志文件
+  REMOTE_CONTROL = '11', // 遥控指令
+  FLIGHT_STATUS = '12'   // 飞行状态
+}
+```
+
+## **7. API 设计**
+
+### **7.1 初始化 API**
+
+```TypeScript
+export function initApiClient(config: ApiClientConfig): void
+```
+
+### **7.2 Token 管理 API**
+
+```TypeScript
+export function setApiToken(token: string | undefined): void
+export function getApiToken(): string | undefined
+```
+
+### **7.3 业务 API**
+
+#### **7.3.1 认证相关 API**
+
+```TypeScript
+export function loginApi(params: LoginParams): Promise<LoginResponse>
+export function refreshTokenApi(): Promise<RefreshTokenResponse>
+export function logoutApi(): Promise<LogoutResponse>
+```
+
+#### **7.3.2 航线相关 API**
+
+```TypeScript
+export function airlineAddApi(params: AirlineAddParams): Promise<AirlineAddResponse>
+export function airlineListApi(params: AirlineListParams): Promise<AirlineListResponse>
+export function airlineQueryApi(params: AirlineQueryParams): Promise<AirlineQueryResponse>
+export function airlineUpdateApi(params: AirlineUpdateParams): Promise<AirlineUpdateResponse>
+```
+
+#### **7.3.3 围栏相关 API**
+
+```TypeScript
+export function fenceAddApi(params: FenceAddParams): Promise<FenceAddResponse>
+export function fenceListApi(params: FenceListParams): Promise<FenceListResponse>
+export function fenceQueryApi(params: FenceQueryParams): Promise<FenceQueryResponse>
+export function fenceUpdateApi(params: FenceUpdateParams): Promise<FenceUpdateResponse>
+```
+
+## **8. 使用方法**
+
+### **8.1 安装**
+
+```Bash
+npm install xxx
+```
+
+### **8.2 初始化**
+
+```TypeScript
+import { initApiClient, setApiToken } from 'api-client';
+
+// 初始化 SDK
+initApiClient({
+  baseUrl: 'https://api.example.com',// 基础路径
+  secret: 'your-secret',// 密钥
+  salt: 'your-salt',// 盐值
+  debug: true,// 是否开启调试模式
+  logLevel: 'ALL',// 日志级别
+  logFormat: 2,// 日志格式
+  logOutput: [1,2],// 日志输出
+  // 自定义日志记录器
+  logger: (log: object | string, level: ApiLogLevel, meta?: unknown) => {
+     console.log(log, level, meta)
+  },
+  // 自定义错误处理
+  onError: (error: ApiError) => {
+     console.error(error)
+  },
+  // 自定义业务错误消息映射
+  businessErrorMessageMap: {
+    1001: '用户名或密码错误',
+    1002: '验证码过期'
+  }，
+  // 自定义刷新token最大重试次数  
+  tokenRefreshMaxRetries: 10
+});
+
+// 设置初始 Token
+setApiToken('initial-token');
+```
+
+### **8.3 调用 API**
+
+```TypeScript
+import { loginApi, airlineListApi } from 'xxx';
+
+// 登录
+try {
+  const loginResult = await loginApi({
+    username: 'admin',
+    password: 'password'
+  });
+  console.log('Login success:', loginResult);
+} catch (error) {
+  console.error('Login failed:', error);
+}
+
+// 获取航线列表
+try {
+  const airlines = await airlineListApi({
+    page: 1,
+    pageSize: 10
+  });
+  console.log('Airlines:', airlines);
+} catch (error) {
+  console.error('Failed to get airlines:', error);
+}
+```