@ticatec/restful_service_api 0.1.6 → 0.2.0

package/README-CN.md

@@ -29,14 +29,14 @@ import RestService from '@ticatec/restful_service_api';
 
 // 实现 RestService 接口
 class MyApiClient implements RestService {
-  async get(url: string, params?: any) {
+  async get(url: string, params?: any, dataProcessor?: DataProcessor) {
     // 在这里实现
   }
-  
-  async post(url: string, data: any, params?: any, contentType?: string) {
+
+  async post(url: string, data?: any, options?: RestfulOptions) {
     // 在这里实现
   }
-  
+
   // ... 其他方法
 }
 
@@ -56,9 +56,9 @@ const newUser = await api.post('/users', { name: '张三' });
 ```typescript
 interface RestService {
   get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
-  post(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
-  put(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
-  del(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+  post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+  put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+  del(url: string, data?: any, options?: RestfulOptions): Promise<any>;
   upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any>;
   asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress>;
   download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any>;
@@ -72,18 +72,27 @@ interface RestService {
 - **params**: 查询参数（可选）
 - **dataProcessor**: 处理响应数据的函数（可选）
 
-#### `post(url, data, params?, contentType?, dataProcessor?)`
+#### `post(url, data?, options?)`
 - **url**: 接口端点 URL
-- **data**: 请求载荷
-- **params**: 查询参数（可选）
-- **contentType**: Content-Type 请求头（可选，默认为 application/json）
-- **dataProcessor**: 处理响应数据的函数（可选）
-
-#### `put(url, data, params?, contentType?, dataProcessor?)`
-类似于 POST，但用于更新操作。
-
-#### `del(url, data, params?, contentType?, dataProcessor?)`
+- **data**: 请求载荷（可选）
+- **options**: 可选的配置对象，包含：
+  - **params**: 查询参数（可选）
+  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **dataProcessor**: 处理响应数据的函数（可选）
+
+#### `put(url, data?, options?)`
+类似于 POST，但用于更新操作。所有参数均为可选。
+- **options**: 可选的配置对象，包含：
+  - **params**: 查询参数（可选）
+  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **dataProcessor**: 处理响应数据的函数（可选）
+
+#### `del(url, data?, options?)`
 用于删除操作，支持可选的请求体。
+- **options**: 可选的配置对象，包含：
+  - **params**: 查询参数（可选）
+  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `upload(url, params, file, fileKey?, dataProcessor?)`
 - **url**: 上传端点 URL
@@ -128,13 +137,21 @@ try {
 ### 类型和拦截器
 
 ```typescript
-import { 
-  PreInterceptor, 
-  PostInterceptor, 
-  ErrorHandler, 
-  DataProcessor 
+import {
+  PreInterceptor,
+  PostInterceptor,
+  ErrorHandler,
+  DataProcessor,
+  RestfulOptions
 } from '@ticatec/restful_service_api';
 
+// RestfulOptions 用于配置请求
+const options: RestfulOptions = {
+  params: { page: 1, limit: 10 },
+  contentType: 'application/json',
+  dataProcessor: (data: any) => data.results || data
+};
+
 // 请求前拦截器，用于添加认证头
 const preInterceptor: PreInterceptor = (method: string, url: string) => {
   return {
@@ -170,15 +187,15 @@ const dataProcessor: DataProcessor = (data: any) => {
 预定义的内容类型常量：
 
 ```typescript
-import { 
+import {
   CONTENT_TYPE_NAME,
   TYPE_JSON,
   TYPE_HTML,
-  TYPE_TEXT 
+  TYPE_TEXT
 } from '@ticatec/restful_service_api';
 
 // 使用示例
-await api.post('/upload', data, {}, TYPE_JSON);
+await api.post('/upload', data, {}, { contentType: TYPE_JSON });
 ```
 
 ## 实现示例
@@ -186,11 +203,12 @@ await api.post('/upload', data, {}, TYPE_JSON);
 以下是使用原生 fetch API 的完整实现示例：
 
 ```typescript
-import RestService, { 
-  ApiError, 
-  PreInterceptor, 
+import RestService, {
+  ApiError,
+  PreInterceptor,
   PostInterceptor,
-  TYPE_JSON 
+  RestfulOptions,
+  TYPE_JSON
 } from '@ticatec/restful_service_api';
 
 class FetchRestService implements RestService {
@@ -209,24 +227,33 @@ class FetchRestService implements RestService {
     return this.request('GET', url + queryString, null, undefined, dataProcessor);
   }
 
-  async post(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
-    return this.request('POST', url, data, contentType, dataProcessor);
+  async post(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+    const contentType = options?.contentType || TYPE_JSON;
+    const params = options?.params;
+    const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+    return this.request('POST', url + queryString, data, contentType, options?.dataProcessor);
   }
 
-  async put(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
-    return this.request('PUT', url, data, contentType, dataProcessor);
+  async put(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+    const contentType = options?.contentType || TYPE_JSON;
+    const params = options?.params;
+    const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+    return this.request('PUT', url + queryString, data, contentType, options?.dataProcessor);
   }
 
-  async del(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
-    return this.request('DELETE', url, data, contentType, dataProcessor);
+  async del(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+    const contentType = options?.contentType || TYPE_JSON;
+    const params = options?.params;
+    const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+    return this.request('DELETE', url + queryString, data, contentType, options?.dataProcessor);
   }
 
   private async request(method: string, url: string, body?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any> {
     const fullUrl = this.baseURL + url;
-    
+
     // 应用请求前拦截器
     const interceptorResult = this.preInterceptor?.(method, fullUrl) || { headers: {} };
-    
+
     const headers = {
       ...interceptorResult.headers,
       ...(contentType && { 'Content-Type': contentType })
@@ -245,19 +272,19 @@ class FetchRestService implements RestService {
         throw new ApiError(response.status, errorData);
       }
 
-      let data = await response.json();
-      
+      let responseData = await response.json();
+
       // 应用响应后拦截器
       if (this.postInterceptor) {
-        data = await this.postInterceptor(data);
+        responseData = await this.postInterceptor(responseData);
       }
-      
+
       // 应用数据处理器
       if (dataProcessor) {
-        data = dataProcessor(data);
+        responseData = dataProcessor(responseData);
       }
 
-      return data;
+      return responseData;
     } catch (error) {
       if (error instanceof ApiError) {
         throw error;
@@ -270,6 +297,8 @@ class FetchRestService implements RestService {
 // 使用示例
 const api = new FetchRestService('https://api.example.com');
 const users = await api.get('/users');
+const newUser = await api.post('/users', { name: '张三' });
+const updatedUser = await api.put('/users/1', { name: '李四' });
 ```
 
 ### 文件上传和下载示例

package/README.md

@@ -29,11 +29,11 @@ import RestService from '@ticatec/restful_service_api';
 
 // Your implementation of RestService interface
 class MyApiClient implements RestService {
-    async get(url: string, params?: any) {
+    async get(url: string, params?: any, dataProcessor?: DataProcessor) {
         // Implementation here
     }
 
-    async post(url: string, data: any, params?: any, contentType?: string) {
+    async post(url: string, data?: any, options?: RestfulOptions) {
         // Implementation here
     }
 
@@ -56,9 +56,9 @@ The main interface that defines the contract for REST operations:
 ```typescript
 interface RestService {
     get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
-    post(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
-    put(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
-    del(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+    put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+    del(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any>;
     asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress>;
     download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any>;
@@ -72,18 +72,27 @@ interface RestService {
 - **params**: Query parameters (optional)
 - **dataProcessor**: Function to process response data (optional)
 
-#### `post(url, data, params?, contentType?, dataProcessor?)`
+#### `post(url, data?, options?)`
 - **url**: The endpoint URL
-- **data**: Request payload
-- **params**: Query parameters (optional)
-- **contentType**: Content-Type header (optional, defaults to application/json)
-- **dataProcessor**: Function to process response data (optional)
-
-#### `put(url, data, params?, contentType?, dataProcessor?)`
-Similar to POST but for update operations.
-
-#### `del(url, data, params?, contentType?, dataProcessor?)`
+- **data**: Request payload (optional)
+- **options**: Optional configuration object containing:
+  - **params**: Query parameters (optional)
+  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **dataProcessor**: Function to process response data (optional)
+
+#### `put(url, data?, options?)`
+Similar to POST but for update operations. All parameters are optional.
+- **options**: Optional configuration object containing:
+  - **params**: Query parameters (optional)
+  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **dataProcessor**: Function to process response data (optional)
+
+#### `del(url, data?, options?)`
 For delete operations with optional request body.
+- **options**: Optional configuration object containing:
+  - **params**: Query parameters (optional)
+  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **dataProcessor**: Function to process response data (optional)
 
 #### `upload(url, params, file, fileKey?, dataProcessor?)`
 - **url**: The upload endpoint URL
@@ -132,9 +141,17 @@ import {
     PreInterceptor,
     PostInterceptor,
     ErrorHandler,
-    DataProcessor
+    DataProcessor,
+    RestfulOptions
 } from '@ticatec/restful_service_api';
 
+// RestfulOptions for configuring requests
+const options: RestfulOptions = {
+    params: { page: 1, limit: 10 },
+    contentType: 'application/json',
+    dataProcessor: (data: any) => data.results || data
+};
+
 // Pre-interceptor for adding authentication headers
 const preInterceptor: PreInterceptor = (method: string, url: string) => {
     return {
@@ -178,7 +195,7 @@ import {
 } from '@ticatec/restful_service_api';
 
 // Usage
-await api.post('/upload', data, {}, TYPE_JSON);
+await api.post('/upload', data, {}, { contentType: TYPE_JSON });
 ```
 
 ## Implementation Example
@@ -190,6 +207,7 @@ import RestService, {
     ApiError,
     PreInterceptor,
     PostInterceptor,
+    RestfulOptions,
     TYPE_JSON
 } from '@ticatec/restful_service_api';
 
@@ -209,16 +227,25 @@ class FetchRestService implements RestService {
         return this.request('GET', url + queryString, null, undefined, dataProcessor);
     }
 
-    async post(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
-        return this.request('POST', url, data, contentType, dataProcessor);
+    async post(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+        const contentType = options?.contentType || TYPE_JSON;
+        const params = options?.params;
+        const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+        return this.request('POST', url + queryString, data, contentType, options?.dataProcessor);
     }
 
-    async put(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
-        return this.request('PUT', url, data, contentType, dataProcessor);
+    async put(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+        const contentType = options?.contentType || TYPE_JSON;
+        const params = options?.params;
+        const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+        return this.request('PUT', url + queryString, data, contentType, options?.dataProcessor);
     }
 
-    async del(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
-        return this.request('DELETE', url, data, contentType, dataProcessor);
+    async del(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+        const contentType = options?.contentType || TYPE_JSON;
+        const params = options?.params;
+        const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+        return this.request('DELETE', url + queryString, data, contentType, options?.dataProcessor);
     }
 
     private async request(method: string, url: string, body?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any> {
@@ -245,19 +272,19 @@ class FetchRestService implements RestService {
                 throw new ApiError(response.status, errorData);
             }
 
-            let data = await response.json();
+            let responseData = await response.json();
 
             // Apply post-interceptor
             if (this.postInterceptor) {
-                data = await this.postInterceptor(data);
+                responseData = await this.postInterceptor(responseData);
             }
 
             // Apply data processor
             if (dataProcessor) {
-                data = dataProcessor(data);
+                responseData = dataProcessor(responseData);
             }
 
-            return data;
+            return responseData;
         } catch (error) {
             if (error instanceof ApiError) {
                 throw error;
@@ -270,6 +297,8 @@ class FetchRestService implements RestService {
 // Usage
 const api = new FetchRestService('https://api.example.com');
 const users = await api.get('/users');
+const newUser = await api.post('/users', { name: 'John Doe' });
+const updatedUser = await api.put('/users/1', { name: 'Jane Doe' });
 ```
 
 ### File Upload and Download Examples

package/dist/RestService.d.ts

@@ -13,6 +13,20 @@ export type DataProcessor = (data: any) => any;
 export type PreInterceptor = (method: string, url: string) => PreInterceptorResult;
 export type PostInterceptor = (data: any) => Promise<any>;
 export type ErrorHandler = (ex: Error) => boolean;
+export type RestfulOptions = {
+    /**
+     * 可选的Content-Type头部，默认为application/json
+     */
+    contentType?: string;
+    /**
+     * 可选的数据处理函数，用于在返回前转换响应数据
+     */
+    dataProcessor?: DataProcessor;
+    /**
+     * 可选的查询参数对象，将被转换为URL查询字符串
+     */
+    params?: any;
+};
 export declare const CONTENT_TYPE_NAME = "Content-Type";
 export declare const TYPE_JSON = "application/json";
 export declare const TYPE_HTML = "text/html";
@@ -30,32 +44,26 @@ export default interface RestService {
      * 执行HTTP POST请求创建新资源
      * @param url 请求的目标URL路径
      * @param data 要发送的请求体数据，通常为对象或字符串
-     * @param params 可选的查询参数对象，将被转换为URL查询字符串
-     * @param contentType 可选的Content-Type头部，默认为application/json
-     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @param options 可选的请求配置选项，包含contentType和dataProcessor
      * @returns 返回Promise，解析为服务器响应数据
      */
-    post(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     /**
      * 执行HTTP PUT请求更新现有资源
      * @param url 请求的目标URL路径
-     * @param data 要发送的请求体数据，用于更新资源
-     * @param params 可选的查询参数对象，将被转换为URL查询字符串
-     * @param contentType 可选的Content-Type头部，默认为application/json
-     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @param data 可选的要发送的请求体数据，用于更新资源
+     * @param options 可选的请求配置选项，包含contentType和dataProcessor
      * @returns 返回Promise，解析为服务器响应数据
      */
-    put(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     /**
      * 执行HTTP DELETE请求删除资源
      * @param url 请求的目标URL路径
      * @param data 可选的请求体数据，某些DELETE操作可能需要发送数据
-     * @param params 可选的查询参数对象，将被转换为URL查询字符串
-     * @param contentType 可选的Content-Type头部，默认为application/json
-     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @param options 可选的请求配置选项，包含contentType和dataProcessor
      * @returns 返回Promise，解析为服务器响应数据
      */
-    del(url: string, data?: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    del(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     /**
      * 执行同步文件上传操作
      * @param url 上传的目标URL路径

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticatec/restful_service_api",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "A lightweight TypeScript RESTful API client for browsers with error handling.",
   "main": "dist/index.js",
   "module": "dist/index.js",