@ticatec/restful_service_api 0.6.1 → 0.7.0

package/README-CN.md

@@ -18,6 +18,32 @@
 - 🌐 **浏览器优先**: 专为前端应用程序设计
 - ✨ **PATCH 支持**: 完整支持 HTTP PATCH 方法进行部分更新
 
+## ⚠️ v0.7.0 重大变更
+
+**`RestfulOptions.contentType` 已被移除，改为使用通用的 `headers` 字段。**
+
+### 对您的影响
+
+- `RestfulOptions`（用于 `post`/`put`/`del`/`patch`）不再识别 `contentType` 字段，
+  请把 `{ contentType: 'multipart/form-data' }` 改为
+  `{ headers: { 'Content-Type': 'multipart/form-data' } }`。
+- `get()` 新增了一个可选的第 4 个参数：`get(url, params?, dataProcessor?, headers?)`。
+  已有的按位置调用方式（`get(url)`、`get(url, params)`、`get(url, params, dataProcessor)`）不受影响。
+- 这也让单次请求携带任意自定义请求头成为可能（不仅限于 Content-Type），例如通过
+  `If-None-Match` 实现条件 GET —— 参见"自定义请求头（例如条件请求）"一节。
+
+### 迁移指南
+
+**之前（v0.6.x 及更早版本）：**
+```typescript
+await api.post('/upload', formData, { contentType: 'multipart/form-data' });
+```
+
+**之后（v0.7.0+）：**
+```typescript
+await api.post('/upload', formData, { headers: { 'Content-Type': 'multipart/form-data' } });
+```
+
 ## ⚠️ v0.5.0 重大变更
 
 **从 0.5.0 版本开始，此包已迁移到 ESM (ECMAScript Modules) 格式。**
@@ -59,7 +85,7 @@ import RestService, { FileService } from '@ticatec/restful_service_api';
 
 // 实现 RestService 接口
 class MyApiClient implements RestService {
-  async get(url: string, params?: any, dataProcessor?: DataProcessor) {
+  async get(url: string, params?: any, dataProcessor?: DataProcessor, headers?: Record<string, string>) {
     // 在这里实现
   }
 
@@ -109,7 +135,7 @@ const result = await fileApi.upload('/upload', { userId: 123 }, file);
 
 ```typescript
 interface RestService {
-  get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
+  get(url: string, params?: any, dataProcessor?: DataProcessor, headers?: Record<string, string>): Promise<any>;
   post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
   put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
   patch(url: string, data?: any, options?: RestfulOptions): Promise<any>;
@@ -131,11 +157,12 @@ interface FileService {
 
 ### RestService 方法
 
-#### `get(url, params?, dataProcessor?)`
+#### `get(url, params?, dataProcessor?, headers?)`
 执行 HTTP GET 请求获取资源。
 - **url**: 接口端点 URL
 - **params**: 查询参数（可选）
 - **dataProcessor**: 处理响应数据的函数（可选）
+- **headers**: 本次调用的自定义请求头（可选），例如条件请求：`{ 'If-None-Match': contentHash }`
 
 #### `post(url, data?, options?)`
 执行 HTTP POST 请求创建新资源。
@@ -143,7 +170,8 @@ interface FileService {
 - **data**: 请求载荷（可选）
 - **options**: 可选的配置对象，包含：
   - **params**: 查询参数（可选）
-  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **headers**: 本次调用的自定义请求头（可选）。可用于覆盖默认的 `Content-Type`
+    （`application/json`），例如 `{ 'Content-Type': 'multipart/form-data' }`
   - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `put(url, data?, options?)`
@@ -152,7 +180,7 @@ interface FileService {
 - **data**: 请求载荷（可选）
 - **options**: 可选的配置对象，包含：
   - **params**: 查询参数（可选）
-  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **headers**: 本次调用的自定义请求头（可选）
   - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `patch(url, data?, options?)`
@@ -161,7 +189,7 @@ interface FileService {
 - **data**: 包含要更新字段的请求载荷（可选）
 - **options**: 可选的配置对象，包含：
   - **params**: 查询参数（可选）
-  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **headers**: 本次调用的自定义请求头（可选）
   - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `del(url, data?, options?)`
@@ -170,7 +198,7 @@ interface FileService {
 - **data**: 请求体数据（可选）
 - **options**: 可选的配置对象，包含：
   - **params**: 查询参数（可选）
-  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **headers**: 本次调用的自定义请求头（可选）
   - **dataProcessor**: 处理响应数据的函数（可选）
 
 ### FileService 方法
@@ -232,7 +260,7 @@ import {
 // RestfulOptions 用于配置请求
 const options: RestfulOptions = {
   params: { page: 1, limit: 10 },
-  contentType: 'application/json',
+  headers: { 'Content-Type': 'application/json' },
   dataProcessor: (data: any) => data.results || data
 };
 
@@ -278,8 +306,34 @@ import {
   TYPE_TEXT
 } from '@ticatec/restful_service_api';
 
-// 使用示例
-await api.post('/upload', data, {}, { contentType: TYPE_JSON });
+// 使用示例 - 通过 RestfulOptions.headers 显式设置请求头
+await api.post('/upload', data, { headers: { [CONTENT_TYPE_NAME]: TYPE_JSON } });
+```
+
+### 自定义请求头（例如条件请求）
+
+`RestfulOptions.headers`（以及 `get()` 的第 4 个参数 `headers`）允许为单次请求附加自定义请求头。
+一个常见场景是基于本地缓存的 ETag/hash 发起条件 GET 请求：
+
+```typescript
+// 第一次请求：还没有缓存的 hash
+const pack = await api.get('/messages/node1');
+localStorage.setItem('node1-hash', pack.contentHash);
+
+// 之后：把缓存的 hash 作为 If-None-Match 发送
+const cachedHash = localStorage.getItem('node1-hash');
+try {
+    const updated = await api.get('/messages/node1', undefined, undefined, {
+        'If-None-Match': cachedHash ?? ''
+    });
+    // 服务端返回 200 —— 内容有变化，使用 `updated`
+} catch (error) {
+    if (error instanceof ApiError && Number(error.status) === 304) {
+        // 服务端返回 304 Not Modified —— 本地缓存仍然有效
+    } else {
+        throw error;
+    }
+}
 ```
 
 ## 实现示例
@@ -309,48 +363,45 @@ class FetchRestService implements RestService {
     this.postInterceptor = postInterceptor;
   }
 
-  async get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any> {
+  async get(url: string, params?: any, dataProcessor?: DataProcessor, headers?: Record<string, string>): Promise<any> {
     const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
-    return this.request('GET', url + queryString, null, undefined, dataProcessor);
+    return this.request('GET', url + queryString, null, headers, 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);
+    return this.request('POST', url + queryString, data, options?.headers, options?.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);
+    return this.request('PUT', url + queryString, data, options?.headers, options?.dataProcessor);
   }
 
   async patch(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('PATCH', url + queryString, data, contentType, options?.dataProcessor);
+    return this.request('PATCH', url + queryString, data, options?.headers, options?.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);
+    return this.request('DELETE', url + queryString, data, options?.headers, options?.dataProcessor);
   }
 
-  private async request(method: string, url: string, body?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any> {
+  private async request(method: string, url: string, body?: any, customHeaders?: Record<string, string>, dataProcessor?: DataProcessor): Promise<any> {
     const fullUrl = this.baseURL + url;
 
     // 应用请求前拦截器
     const interceptorResult = this.preInterceptor?.(method, fullUrl) || { headers: {} };
 
     const headers = {
+      'Content-Type': TYPE_JSON,
       ...interceptorResult.headers,
-      ...(contentType && { 'Content-Type': contentType })
+      ...customHeaders
     };
 
     try {

package/README.md

@@ -18,6 +18,31 @@ A lightweight TypeScript RESTful API client for browsers with comprehensive erro
 - 🌐 **Browser-First**: Designed specifically for frontend applications
 - ✨ **PATCH Support**: Full support for HTTP PATCH method for partial updates
 
+## ⚠️ Breaking Changes in v0.7.0
+
+**`RestfulOptions.contentType` has been removed in favor of a general-purpose `headers` field.**
+
+### What This Means for You
+
+- `contentType` is no longer a recognized field on `RestfulOptions` (used by `post`/`put`/`del`/`patch`).
+  Replace `{ contentType: 'multipart/form-data' }` with `{ headers: { 'Content-Type': 'multipart/form-data' } }`.
+- `get()` gained a new, optional 4th parameter: `get(url, params?, dataProcessor?, headers?)`. Existing
+  positional calls (`get(url)`, `get(url, params)`, `get(url, params, dataProcessor)`) are unaffected.
+- This also enables custom per-call headers in general (not just Content-Type), e.g. a conditional
+  GET via `If-None-Match` — see [Custom Headers (e.g. Conditional Requests)](#custom-headers-eg-conditional-requests).
+
+### Migration Guide
+
+**Before (v0.6.x and earlier):**
+```typescript
+await api.post('/upload', formData, { contentType: 'multipart/form-data' });
+```
+
+**After (v0.7.0+):**
+```typescript
+await api.post('/upload', formData, { headers: { 'Content-Type': 'multipart/form-data' } });
+```
+
 ## ⚠️ Breaking Changes in v0.5.0
 
 **Starting from version 0.5.0, this package has migrated to ESM (ECMAScript Modules) format.**
@@ -58,7 +83,7 @@ import RestService, { FileService } from '@ticatec/restful_service_api';
 
 // Your implementation of RestService interface
 class MyApiClient implements RestService {
-    async get(url: string, params?: any, dataProcessor?: DataProcessor) {
+    async get(url: string, params?: any, dataProcessor?: DataProcessor, headers?: Record<string, string>) {
         // Implementation here
     }
 
@@ -108,7 +133,7 @@ The main interface for standard HTTP REST operations:
 
 ```typescript
 interface RestService {
-    get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
+    get(url: string, params?: any, dataProcessor?: DataProcessor, headers?: Record<string, string>): Promise<any>;
     post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     patch(url: string, data?: any, options?: RestfulOptions): Promise<any>;
@@ -130,11 +155,13 @@ interface FileService {
 
 ### RestService Methods
 
-#### `get(url, params?, dataProcessor?)`
+#### `get(url, params?, dataProcessor?, headers?)`
 Performs HTTP GET request to retrieve a resource.
 - **url**: The endpoint URL
 - **params**: Query parameters (optional)
 - **dataProcessor**: Function to process response data (optional)
+- **headers**: Custom request headers for this single call (optional), e.g. for a conditional
+  request: `{ 'If-None-Match': contentHash }`
 
 #### `post(url, data?, options?)`
 Performs HTTP POST request to create a new resource.
@@ -142,7 +169,8 @@ Performs HTTP POST request to create a new resource.
 - **data**: Request payload (optional)
 - **options**: Optional configuration object containing:
   - **params**: Query parameters (optional)
-  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **headers**: Custom request headers for this single call (optional). Use this to override
+    the default `Content-Type` (`application/json`), e.g. `{ 'Content-Type': 'multipart/form-data' }`
   - **dataProcessor**: Function to process response data (optional)
 
 #### `put(url, data?, options?)`
@@ -151,7 +179,7 @@ Performs HTTP PUT request to update an entire resource.
 - **data**: Request payload (optional)
 - **options**: Optional configuration object containing:
   - **params**: Query parameters (optional)
-  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **headers**: Custom request headers for this single call (optional)
   - **dataProcessor**: Function to process response data (optional)
 
 #### `patch(url, data?, options?)`
@@ -160,7 +188,7 @@ Performs HTTP PATCH request to partially update a resource.
 - **data**: Request payload with fields to update (optional)
 - **options**: Optional configuration object containing:
   - **params**: Query parameters (optional)
-  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **headers**: Custom request headers for this single call (optional)
   - **dataProcessor**: Function to process response data (optional)
 
 #### `del(url, data?, options?)`
@@ -169,7 +197,7 @@ Performs HTTP DELETE request to delete a resource.
 - **data**: Request body data (optional)
 - **options**: Optional configuration object containing:
   - **params**: Query parameters (optional)
-  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **headers**: Custom request headers for this single call (optional)
   - **dataProcessor**: Function to process response data (optional)
 
 ### FileService Methods
@@ -231,7 +259,7 @@ import {
 // RestfulOptions for configuring requests
 const options: RestfulOptions = {
     params: { page: 1, limit: 10 },
-    contentType: 'application/json',
+    headers: { 'Content-Type': 'application/json' },
     dataProcessor: (data: any) => data.results || data
 };
 
@@ -277,8 +305,35 @@ import {
     TYPE_TEXT
 } from '@ticatec/restful_service_api';
 
-// Usage
-await api.post('/upload', data, {}, { contentType: TYPE_JSON });
+// Usage - set a header explicitly via RestfulOptions.headers
+await api.post('/upload', data, { headers: { [CONTENT_TYPE_NAME]: TYPE_JSON } });
+```
+
+### Custom Headers (e.g. Conditional Requests)
+
+`RestfulOptions.headers` (and the 4th `headers` parameter of `get()`) let you attach custom
+request headers to a single call. A common use case is a conditional GET based on a
+previously-cached ETag/hash:
+
+```typescript
+// First request: no cached hash yet
+const pack = await api.get('/messages/node1');
+localStorage.setItem('node1-hash', pack.contentHash);
+
+// Later: send the cached hash as If-None-Match
+const cachedHash = localStorage.getItem('node1-hash');
+try {
+    const updated = await api.get('/messages/node1', undefined, undefined, {
+        'If-None-Match': cachedHash ?? ''
+    });
+    // Server responded 200 - content changed, use `updated`
+} catch (error) {
+    if (error instanceof ApiError && Number(error.status) === 304) {
+        // Server responded 304 Not Modified - the local cache is still valid
+    } else {
+        throw error;
+    }
+}
 ```
 
 ## Implementation Example
@@ -308,48 +363,45 @@ class FetchRestService implements RestService {
         this.postInterceptor = postInterceptor;
     }
 
-    async get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any> {
+    async get(url: string, params?: any, dataProcessor?: DataProcessor, headers?: Record<string, string>): Promise<any> {
         const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
-        return this.request('GET', url + queryString, null, undefined, dataProcessor);
+        return this.request('GET', url + queryString, null, headers, 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);
+        return this.request('POST', url + queryString, data, options?.headers, options?.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);
+        return this.request('PUT', url + queryString, data, options?.headers, options?.dataProcessor);
     }
 
     async patch(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('PATCH', url + queryString, data, contentType, options?.dataProcessor);
+        return this.request('PATCH', url + queryString, data, options?.headers, options?.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);
+        return this.request('DELETE', url + queryString, data, options?.headers, options?.dataProcessor);
     }
 
-    private async request(method: string, url: string, body?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any> {
+    private async request(method: string, url: string, body?: any, customHeaders?: Record<string, string>, dataProcessor?: DataProcessor): Promise<any> {
         const fullUrl = this.baseURL + url;
 
         // Apply pre-interceptor
         const interceptorResult = this.preInterceptor?.(method, fullUrl) || { headers: {} };
 
         const headers = {
+            'Content-Type': TYPE_JSON,
             ...interceptorResult.headers,
-            ...(contentType && { 'Content-Type': contentType })
+            ...customHeaders
         };
 
         try {

package/dist/FileService.d.ts

@@ -45,20 +45,20 @@ export default interface FileService {
      *   { userId: 123 },
      *   file,
      *   {
-     *     onProgress: (loaded, total, percent) => {
-     *       console.log(`Upload: ${percent}%`);
+     *     progressUpdate: (uploadBytes) => {
+     *       console.log(`Uploaded: ${uploadBytes} bytes`);
      *     },
      *     onCompleted: (data) => {
      *       console.log('Upload complete:', data);
      *     },
-     *     onError: (error) => {
+     *     handleError: (error) => {
      *       console.error('Upload failed:', error);
      *     }
      *   }
      * );
      *
      * // Cancel the upload
-     * progress.abort();
+     * progress.cancel();
      * ```
      */
     asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress>;

package/dist/RestService.d.ts

@@ -38,10 +38,6 @@ export type ErrorHandler = (ex: Error) => boolean | void;
  * RESTful API request options
  */
 export type RestfulOptions<T = any> = {
-    /**
-     * Optional Content-Type header, defaults to 'application/json'
-     */
-    contentType?: string;
     /**
      * Optional data processing function to transform response data before returning
      */
@@ -50,6 +46,13 @@ export type RestfulOptions<T = any> = {
      * Optional query parameters object that will be converted to URL query string
      */
     params?: any;
+    /**
+     * Optional custom request headers for this single call (e.g. { 'If-None-Match': contentHash },
+     * or { 'Content-Type': 'multipart/form-data' } to override the default JSON content type).
+     * These are merged on top of any headers produced by the PreInterceptor, and take precedence
+     * over them when the same header name is used.
+     */
+    headers?: Record<string, string>;
 };
 /**
  * HTTP header name for Content-Type
@@ -76,6 +79,7 @@ export default interface RestService {
      * @param url The target URL path for the request
      * @param params Query parameters object that will be converted to URL query string
      * @param dataProcessor Optional data processing function to transform response data before returning
+     * @param headers Optional custom request headers for this single call (e.g. conditional GET via If-None-Match)
      * @returns Promise that resolves to the server response data
      *
      * @example
@@ -88,14 +92,17 @@ export default interface RestService {
      *
      * // GET with data processor
      * const users = await restService.get('/api/users', null, (data) => data.items);
+     *
+     * // GET with a custom header (e.g. conditional GET)
+     * const pack = await restService.get('/api/messages/node1', null, undefined, { 'If-None-Match': contentHash });
      * ```
      */
-    get<T = any>(url: string, params?: any, dataProcessor?: DataProcessor<T>): Promise<T>;
+    get<T = any>(url: string, params?: any, dataProcessor?: DataProcessor<T>, headers?: Record<string, string>): Promise<T>;
     /**
      * Performs an HTTP POST request to create a new resource
      * @param url The target URL path for the request
      * @param data Request body data to be sent, typically an object or string
-     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @param options Optional request configuration options, including headers and dataProcessor
      * @returns Promise that resolves to the server response data
      *
      * @example
@@ -103,9 +110,9 @@ export default interface RestService {
      * // Simple POST request
      * const newUser = await restService.post('/api/users', { name: 'John', age: 30 });
      *
-     * // POST with custom content type
+     * // POST with a custom Content-Type header
      * const result = await restService.post('/api/data', formData, {
-     *   contentType: 'multipart/form-data'
+     *   headers: { 'Content-Type': 'multipart/form-data' }
      * });
      *
      * // POST with data processor
@@ -119,7 +126,7 @@ export default interface RestService {
      * Performs an HTTP PUT request to update an existing resource
      * @param url The target URL path for the request
      * @param data Optional request body data to be sent for updating the resource
-     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @param options Optional request configuration options, including headers and dataProcessor
      * @returns Promise that resolves to the server response data
      *
      * @example
@@ -136,7 +143,7 @@ export default interface RestService {
      * Performs an HTTP DELETE request to delete a resource
      * @param url The target URL path for the request
      * @param data Optional request body data, some DELETE operations may require sending data
-     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @param options Optional request configuration options, including headers and dataProcessor
      * @returns Promise that resolves to the server response data
      *
      * @example
@@ -153,7 +160,7 @@ export default interface RestService {
      * Performs an HTTP PATCH request to partially update a resource
      * @param url The target URL path for the request
      * @param data Optional request body data to be sent for partially updating the resource
-     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @param options Optional request configuration options, including headers and dataProcessor
      * @returns Promise that resolves to the server response data
      *
      * @example

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@ticatec/restful_service_api",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "A lightweight TypeScript RESTful API client for browsers with error handling. (ESM only, v0.6.0+)",
   "main": "dist/index.js",
   "module": "dist/index.js",