@ahoo-wang/fetcher-decorator 2.9.2 → 2.9.5

package/README.md

@@ -156,9 +156,9 @@ Defines API metadata for a class.
 
 - `basePath`: Base path for all endpoints in the class
 - `metadata`: Additional metadata for the API
-    - `headers`: Default headers for all requests in the class
-    - `timeout`: Default timeout for all requests in the class
-    - `fetcher`: Name of the fetcher instance to use (default: 'default')
+  - `headers`: Default headers for all requests in the class
+  - `timeout`: Default timeout for all requests in the class
+  - `fetcher`: Name of the fetcher instance to use (default: 'default')
 
 **Example:**
 
@@ -207,9 +207,9 @@ Defines an OPTIONS endpoint.
 
 - `path`: Path for the endpoint (relative to class base path)
 - `metadata`: Additional metadata for the endpoint
-    - `headers`: Headers for the request
-    - `timeout`: Timeout for the request
-    - `fetcher`: Name of the fetcher instance to use
+  - `headers`: Headers for the request
+  - `timeout`: Timeout for the request
+  - `fetcher`: Name of the fetcher instance to use
 
 **Example:**
 
@@ -291,6 +291,87 @@ class UserService {
 }
 ```
 
+## 🪝 Lifecycle Hooks
+
+The `ExecuteLifeCycle` interface allows you to hook into the request execution lifecycle and modify the `FetchExchange` before and after it is processed by interceptors. This provides a way to customize the behavior of API calls at specific points in the execution flow.
+
+### ExecuteLifeCycle Interface
+
+```typescript
+import { ExecuteLifeCycle } from '@ahoo-wang/fetcher-decorator';
+
+interface ExecuteLifeCycle {
+  beforeExecute?(exchange: FetchExchange): void | Promise<void>;
+  afterExecute?(exchange: FetchExchange): void | Promise<void>;
+}
+```
+
+### Lifecycle Methods
+
+#### `beforeExecute(exchange: FetchExchange)`
+
+Called before the `FetchExchange` is processed by interceptors. Users can inspect or modify the exchange before processing, such as adding headers, modifying the request body, or setting up logging.
+
+**Parameters:**
+
+- `exchange`: The `FetchExchange` object representing the request and response
+
+#### `afterExecute(exchange: FetchExchange)`
+
+Called after the `FetchExchange` is processed by interceptors. Users can inspect or modify the exchange after processing, such as handling response data, logging results, or performing cleanup.
+
+**Parameters:**
+
+- `exchange`: The `FetchExchange` object representing the request and response
+
+### Usage Example
+
+```typescript
+import { api, get, path, ExecuteLifeCycle } from '@ahoo-wang/fetcher-decorator';
+import { FetchExchange } from '@ahoo-wang/fetcher';
+
+@api('/users')
+class UserService implements ExecuteLifeCycle {
+  @get('/{id}')
+  getUser(@path() id: number): Promise<User> {
+    throw autoGeneratedError(id);
+  }
+
+  async beforeExecute(exchange: FetchExchange): Promise<void> {
+    // Add custom headers before request execution
+    exchange.request.headers.set('X-Custom-Header', 'value');
+
+    // Log the request
+    console.log('Executing request:', exchange.request.url);
+  }
+
+  async afterExecute(exchange: FetchExchange): Promise<void> {
+    // Log the response status
+    console.log('Response status:', exchange.response?.status);
+
+    // Handle specific error codes
+    if (exchange.response?.status === 401) {
+      // Handle unauthorized access
+      console.warn('Unauthorized access detected');
+    }
+  }
+}
+
+const userService = new UserService();
+const user = await userService.getUser(123); // Lifecycle hooks will be called automatically
+```
+
+### Execution Flow
+
+When a decorated method is called, the execution follows this sequence:
+
+1. **Parameter Resolution**: Method arguments are resolved into request configuration
+2. **Exchange Creation**: A `FetchExchange` object is created
+3. **Before Execute Hook**: `beforeExecute` is called if implemented
+4. **Interceptor Processing**: The exchange is processed through the interceptor chain
+5. **After Execute Hook**: `afterExecute` is called if implemented
+6. **Result Extraction**: The final result is extracted and returned
+
 ## 🛠️ Advanced Usage
 
 ### Inheritance Support

package/README.zh-CN.md

@@ -286,6 +286,87 @@ class UserService {
 }
 ```
 
+## 🪝 生命周期钩子
+
+`ExecuteLifeCycle` 接口允许您钩入请求执行生命周期，并在拦截器处理 `FetchExchange` 之前和之后修改它。这提供了一种在执行流程的特定点自定义 API 调用行为的方法。
+
+### ExecuteLifeCycle 接口
+
+```typescript
+import { ExecuteLifeCycle } from '@ahoo-wang/fetcher-decorator';
+
+interface ExecuteLifeCycle {
+  beforeExecute?(exchange: FetchExchange): void | Promise<void>;
+  afterExecute?(exchange: FetchExchange): void | Promise<void>;
+}
+```
+
+### 生命周期方法
+
+#### `beforeExecute(exchange: FetchExchange)`
+
+在 `FetchExchange` 被拦截器处理之前调用。用户可以在处理之前检查或修改交换，例如添加头部、修改请求体或设置日志记录。
+
+**参数：**
+
+- `exchange`: 表示请求和响应的 `FetchExchange` 对象
+
+#### `afterExecute(exchange: FetchExchange)`
+
+在 `FetchExchange` 被拦截器处理之后调用。用户可以在处理之后检查或修改交换，例如处理响应数据、记录结果或执行清理。
+
+**参数：**
+
+- `exchange`: 表示请求和响应的 `FetchExchange` 对象
+
+### 使用示例
+
+```typescript
+import { api, get, path, ExecuteLifeCycle } from '@ahoo-wang/fetcher-decorator';
+import { FetchExchange } from '@ahoo-wang/fetcher';
+
+@api('/users')
+class UserService implements ExecuteLifeCycle {
+  @get('/{id}')
+  getUser(@path() id: number): Promise<User> {
+    throw autoGeneratedError(id);
+  }
+
+  async beforeExecute(exchange: FetchExchange): Promise<void> {
+    // 在请求执行前添加自定义头部
+    exchange.request.headers.set('X-Custom-Header', 'value');
+
+    // 记录请求
+    console.log('Executing request:', exchange.request.url);
+  }
+
+  async afterExecute(exchange: FetchExchange): Promise<void> {
+    // 记录响应状态
+    console.log('Response status:', exchange.response?.status);
+
+    // 处理特定错误代码
+    if (exchange.response?.status === 401) {
+      // 处理未授权访问
+      console.warn('Unauthorized access detected');
+    }
+  }
+}
+
+const userService = new UserService();
+const user = await userService.getUser(123); // 生命周期钩子将被自动调用
+```
+
+### 执行流程
+
+当调用装饰方法时，执行遵循以下序列：
+
+1. **参数解析**：方法参数被解析为请求配置
+2. **交换创建**：创建 `FetchExchange` 对象
+3. **执行前钩子**：如果实现，则调用 `beforeExecute`
+4. **拦截器处理**：交换通过拦截器链处理
+5. **执行后钩子**：如果实现，则调用 `afterExecute`
+6. **结果提取**：提取并返回最终结果
+
 ## 🛠️ 高级用法
 
 ### 继承支持

package/dist/executeLifeCycle.d.ts

@@ -0,0 +1,28 @@
+import { FetchExchange } from '@ahoo-wang/fetcher';
+/**
+ * Lifecycle hooks for decorator-based API execution.
+ *
+ * This interface allows users to hook into the request execution lifecycle
+ * and modify the FetchExchange before and after it is processed by interceptors.
+ * It provides a way to customize the behavior of API calls at specific points
+ * in the execution flow.
+ */
+export interface ExecuteLifeCycle {
+    /**
+     * Called before the FetchExchange is processed by interceptors.
+     * Users can inspect or modify the exchange before processing at this point,
+     * such as adding headers, modifying the request body, or setting up logging.
+     *
+     * @param exchange - The FetchExchange object representing the request and response
+     */
+    beforeExecute?(exchange: FetchExchange): void | Promise<void>;
+    /**
+     * Called after the FetchExchange is processed by interceptors.
+     * Users can inspect or modify the exchange after processing at this point,
+     * such as handling response data, logging results, or performing cleanup.
+     *
+     * @param exchange - The FetchExchange object representing the request and response
+     */
+    afterExecute?(exchange: FetchExchange): void | Promise<void>;
+}
+//# sourceMappingURL=executeLifeCycle.d.ts.map

package/dist/executeLifeCycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executeLifeCycle.d.ts","sourceRoot":"","sources":["../src/executeLifeCycle.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D"}