@ahoo-wang/fetcher-decorator 0.6.1 → 0.6.6

package/README.md

@@ -63,10 +63,7 @@ class UserService {
   }
 
   @get('/{id}')
-  getUser(
-    @path() id: number,
-    @query() include: string,
-  ): Promise<Response> {
+  getUser(@path() id: number, @query() include: string): Promise<Response> {
     throw new Error('Implementation will be generated automatically.');
   }
 }
@@ -192,6 +189,12 @@ parameter name.
 
 - `name`: Name of the header (optional - auto-extracted if not provided)
 
+#### `@request()`
+
+Defines a request parameter that will be used as the base request object. This allows you to pass a complete
+FetcherRequest
+object to customize the request configuration.
+
 **Example:**
 
 ```typescript
@@ -205,6 +208,11 @@ class UserService {
     throw new Error('Implementation will be generated automatically.');
   }
 
+  @post('/users')
+  createUsers(@request() request: FetcherRequest): Promise<Response> {
+    throw new Error('Implementation will be generated automatically.');
+  }
+
   @put('/{id}')
   updateUser(@path() id: number, @body() user: User): Promise<Response> {
     throw new Error('Implementation will be generated automatically.');
@@ -250,6 +258,33 @@ class ComplexService {
 }
 ```
 
+### Request Merging
+
+When using the `@request()` decorator, the provided `FetcherRequest` object is merged with endpoint-specific
+configuration using a sophisticated merging strategy:
+
+- **Nested objects** (path, query, headers) are recursively merged, with parameter values taking precedence
+- **Primitive values** (method, body, timeout, signal) from the parameter request override endpoint values
+- **Empty objects** are handled gracefully, falling back to endpoint configuration
+
+```typescript
+
+@api('/users')
+class UserService {
+  @post('/')
+  createUsers(
+    @body() user: User,
+    @request() request: FetcherRequest,
+  ): Promise<Response> {
+    // The final request will merge:
+    // - Endpoint method (POST)
+    // - Body parameter (user object)
+    // - Any configuration from the request parameter
+    throw new Error('Implementation will be generated automatically.');
+  }
+}
+```
+
 ## 🧪 Testing
 
 ```bash

package/README.zh-CN.md

@@ -62,10 +62,7 @@ class UserService {
   }
 
   @get('/{id}')
-  getUser(
-    @path() id: number,
-    @query() include: string,
-  ): Promise<Response> {
+  getUser(@path() id: number, @query() include: string): Promise<Response> {
     throw new Error('实现将自动生成');
   }
 }
@@ -188,6 +185,10 @@ class UserService {
 
 - `name`: 头部名称（可选 - 如果未提供则自动提取）
 
+#### `@request()`
+
+定义请求参数，将用作基础请求对象。这允许您传递一个完整的 FetcherRequest 对象来自定义请求配置。
+
 **示例：**
 
 ```typescript
@@ -201,6 +202,11 @@ class UserService {
     throw new Error('实现将自动生成');
   }
 
+  @post('/users')
+  createUsers(@request() request: FetcherRequest): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+
   @put('/{id}')
   updateUser(@path('id') id: number, @body() user: User): Promise<Response> {
     throw new Error('实现将自动生成');
@@ -246,6 +252,32 @@ class ComplexService {
 }
 ```
 
+### 请求合并
+
+当使用 `@request()` 装饰器时，提供的 `FetcherRequest` 对象会使用复杂的合并策略与端点特定配置进行合并：
+
+- **嵌套对象**（路径、查询、头部）会被递归合并，参数值优先
+- **基本值**（方法、请求体、超时、信号）来自参数请求的值会覆盖端点值
+- **空对象**会被优雅地处理，回退到端点配置
+
+```typescript
+
+@api('/users')
+class UserService {
+  @post('/')
+  createUsers(
+    @body() user: User,
+    @request() request: FetcherRequest,
+  ): Promise<Response> {
+    // 最终请求将合并：
+    // - 端点方法（POST）
+    // - 请求体参数（user 对象）
+    // - 来自 request 参数的任何配置
+    throw new Error('实现将自动生成');
+  }
+}
+```
+
 ## 🧪 测试
 
 ```bash