xxf_react 0.7.3 → 0.7.4

package/dist/http/api/ApiBuilder.d.ts

@@ -8,110 +8,104 @@
  *
  * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
  * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
- * - **路径参数推断**：从 path 字符串自动提取 `{param}` 并约束 `pathParams` 类型
  * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
- * - **防止重复端点**：添加已存在的端点名称会编译报错
  *
  * @example
  * ```ts
  * interface CreateUserDTO { name: string; email: string }
  *
- * // 定义 API
  * const userApi = ApiBuilder.create({
  *   baseUrl: 'https://api.example.com',
  * })
- *   .get<User>('getUser', {
- *     path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
- *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
- *   })
+ *   .get<User>('getUser', { path: '/users/{id}' })
  *   .get<User[]>('getUsers', { path: '/users' })
- *   .post<User, CreateUserDTO>('createUser', { path: '/users' })  // body 类型为 CreateUserDTO
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
  *   .build()
  *
  * // ✅ 类型正确推断
- * userApi.getUser({ pathParams: { id: '123' } })          // pathParams 必须有 id
- * userApi.getUsers()                                       // 无需 pathParams
- * userApi.createUser({ body: { name: 'John', email: 'x' } }) // body 类型检查
+ * userApi.getUser({ pathParams: { id: '123' } })
+ * userApi.createUser({ body: { name: 'John', email: 'x' } })
  *
  * // ❌ 类型错误会被捕获
- * userApi.getUser({ pathParams: { wrong: '1' } })  // Error: 缺少 id
- * userApi.createUser({ body: { wrong: 'x' } })     // Error: body 类型不匹配
- * userApi.unknownMethod()                          // Error: 方法不存在
+ * userApi.unknownMethod()  // Error: 方法不存在
  * ```
  */
 import ky, { type Options as KyOptions } from 'ky';
 import { HttpClient } from '../client/HttpClient';
 import { ApiStream } from '../client/ApiStream';
-import type { RequestConfig, CacheConfig, HttpClientConfig } from '../types';
+import type { RequestConfig, ApiOptions, CacheConfig, HttpClientConfig } from '../types';
 /**
- * 从路径字符串中提取参数名称
- *
- * @example
- * ExtractPathParams<'/users/{id}'> = 'id'
- * ExtractPathParams<'/users/{userId}/posts/{postId}'> = 'userId' | 'postId'
- * ExtractPathParams<'/users'> = never
+ * 基础 API 调用选项（不含 body）
  */
-type ExtractPathParams<Path extends string> = Path extends `${string}{${infer Param}}${infer Rest}` ? Param | ExtractPathParams<Rest> : never;
+type BaseApiOptions = Omit<ApiOptions, 'body'>;
 /**
- * 根据路径参数生成 pathParams 类型
- *
- * @example
- * PathParamsType<'/users/{id}'> = { id: string | number }
- * PathParamsType<'/users'> = undefined (无需路径参数)
+ * 带 body 的 API 调用选项（body 必需）
  */
-type PathParamsType<Path extends string> = ExtractPathParams<Path> extends never ? undefined : Record<ExtractPathParams<Path>, string | number>;
+type WithBodyRequired<TBody> = BaseApiOptions & {
+    body: TBody;
+};
 /**
- * 判断路径是否有参数
+ * 带 body 的 API 调用选项（body 可选）
  */
-type HasPathParams<Path extends string> = ExtractPathParams<Path> extends never ? false : true;
+type WithBodyOptional = BaseApiOptions & {
+    body?: unknown;
+};
 /**
- * 带类型约束的 API 调用选项
- *
- * @template Path 路径字符串字面量
- * @template TBody 请求体类型（用于 POST/PUT/PATCH）
- * @template HasBody 是否需要 body
+ * 无 body 的 API 调用选项（GET/DELETE）
  */
-type TypedApiOptions<Path extends string, TBody = never, HasBody extends boolean = false> = {
-    /** 查询参数，会自动过滤 undefined 和 null */
-    query?: Record<string, string | number | boolean | undefined>;
-    /** 覆盖缓存配置（优先级最高） */
-    cache?: Partial<CacheConfig>;
-    /** 覆盖请求头 */
-    headers?: Record<string, string>;
-} & (HasPathParams<Path> extends true ? {
-    pathParams: PathParamsType<Path>;
-} : {
-    pathParams?: undefined;
-}) & (HasBody extends true ? {
-    body?: TBody;
-} : {
+type WithoutBodyOptions = BaseApiOptions & {
     body?: never;
-});
+};
 /**
- * API 端点函数类型（带路径参数和 Body 类型约束）
- *
- * @template TResponse 响应数据类型
- * @template Path 路径字符串字面量
- * @template TBody 请求体类型
- * @template HasBody 是否需要 body
+ * API 端点函数类型（有 body 且必需 - POST/PUT/PATCH 指定了 TBody）
  */
-export type ApiEndpoint<TResponse, Path extends string = string, TBody = never, HasBody extends boolean = false> = {
-    (options?: TypedApiOptions<Path, TBody, HasBody>): ApiStream<TResponse>;
+export type ApiEndpointWithBodyRequired<TResponse, TBody> = {
+    (options: WithBodyRequired<TBody>): ApiStream<TResponse>;
     /** 请求配置 */
     config: RequestConfig;
 };
+/**
+ * API 端点函数类型（有 body 但可选 - POST/PUT/PATCH 未指定 TBody）
+ */
+export type ApiEndpointWithBodyOptional<TResponse> = {
+    (options?: WithBodyOptional): ApiStream<TResponse>;
+    /** 请求配置 */
+    config: RequestConfig;
+};
+/**
+ * API 端点函数类型（无 body - GET/DELETE）
+ */
+export type ApiEndpointWithoutBody<TResponse> = {
+    (options?: WithoutBodyOptions): ApiStream<TResponse>;
+    /** 请求配置 */
+    config: RequestConfig;
+};
+/**
+ * 检测是否为 unknown 类型
+ */
+type IsUnknown<T> = [unknown] extends [T] ? ([T] extends [unknown] ? true : false) : false;
+/**
+ * 检测是否为 void 类型
+ */
+type IsVoid<T> = [T] extends [void] ? ([void] extends [T] ? true : false) : false;
+/**
+ * 有 body 的端点类型（根据 TBody 选择必需或可选）
+ */
+export type ApiEndpointWithBody<TResponse, TBody> = IsUnknown<TBody> extends true ? ApiEndpointWithBodyOptional<TResponse> : IsVoid<TBody> extends true ? ApiEndpointWithBodyOptional<TResponse> : ApiEndpointWithBodyRequired<TResponse, TBody>;
+/**
+ * API 端点函数类型（泛型版本，用于内部和类型导出）
+ */
+export type ApiEndpoint<TResponse, TBody = unknown, HasBody extends boolean = false> = HasBody extends true ? ApiEndpointWithBody<TResponse, TBody> : ApiEndpointWithoutBody<TResponse>;
 /**
  * API 定义类型（端点集合）
  */
-export type ApiDefinition = Record<string, ApiEndpoint<unknown, string, unknown, boolean>>;
+export type ApiDefinition = Record<string, ApiEndpoint<unknown, unknown, boolean>>;
 /**
  * 端点选项（构建时配置）
- *
- * @template Path 路径字符串字面量，用于类型推断
  */
-interface EndpointOptions<Path extends string = string> {
+interface EndpointOptions {
     /** 请求路径，支持 {param} 占位符 */
-    path: Path;
+    path: string;
     /** 请求方法 */
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
     /** 请求头 */
@@ -123,12 +117,39 @@ interface EndpointOptions<Path extends string = string> {
     /** 缓存配置 */
     cache?: CacheConfig;
 }
+/**
+ * 空 API 类型（空记录，不允许任意属性访问）
+ */
+type EmptyApi = {};
 /**
  * API 构建器类
  *
+ * 使用链式调用定义类型安全的 API 端点。
+ *
  * @template T 当前已定义的端点类型集合，通过链式调用累积
+ *
+ * @remarks
+ * **类型深度限制**：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
+ *
+ * 建议：
+ * - 保持单个 builder 的端点数量在 4 个以内
+ * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({ baseUrl: '/api' })
+ *   .get<User>('getUser', { path: '/users/{id}' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+ *   .put<User, UpdateUserDTO>('updateUser', { path: '/users/{id}' })
+ *   .build()
+ *
+ * // 类型安全调用
+ * const user = await userApi.getUser({ pathParams: { id: '1' } })
+ * const newUser = await userApi.createUser({ body: { name: 'John', email: 'j@test.com' } })
+ * ```
  */
-export declare class ApiBuilder<T extends ApiDefinition = Record<string, never>> {
+export declare class ApiBuilder<T extends object = EmptyApi> {
     private client;
     private endpoints;
     private constructor();
@@ -137,203 +158,85 @@ export declare class ApiBuilder<T extends ApiDefinition = Record<string, never>>
      *
      * @param config HTTP 客户端配置
      * @returns 新的 ApiBuilder 实例
-     *
-     * @example
-     * ```ts
-     * const api = ApiBuilder.create({
-     *   baseUrl: 'https://api.example.com',
-     *   timeout: 10000,
-     * })
-     * ```
      */
-    static create(config: HttpClientConfig): ApiBuilder;
+    static create(config: HttpClientConfig): ApiBuilder<object>;
     /**
      * 从现有 ky 实例创建
      *
      * @param kyInstance 已配置的 ky 实例
      * @param config 可选的额外配置
      * @returns 新的 ApiBuilder 实例
-     *
-     * @example
-     * ```ts
-     * const kyInstance = ky.create({ prefixUrl: 'https://api.example.com' })
-     * const api = ApiBuilder.from(kyInstance)
-     * ```
      */
-    static from(kyInstance: ReturnType<typeof ky.create>, config?: Partial<HttpClientConfig>): ApiBuilder;
+    static from(kyInstance: ReturnType<typeof ky.create>, config?: Partial<HttpClientConfig>): ApiBuilder<object>;
     /**
      * 定义 GET 请求
      *
      * @template TResponse 响应数据类型
-     * @template K 端点名称（自动推断，不能与已有端点重复）
-     * @template Path 路径字符串（自动推断，用于提取路径参数）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .get<User>('getUser', {
-     *   path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
-     *   cache: { mode: CacheMode.IfCache },
-     * })
-     * ```
+     * @template K 端点名称（自动推断）
      */
-    get<TResponse, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, // 防止重复端点名称
-    options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, never, false>>>;
+    get<TResponse, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithoutBody<TResponse>;
+    }>;
     /**
      * 定义 POST 请求
      *
      * @template TResponse 响应数据类型
-     * @template TBody 请求体类型（可选，默认 unknown）
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * interface CreateUserDTO { name: string; email: string }
-     *
-     * .post<User, CreateUserDTO>('createUser', {
-     *   path: '/users',
-     * })
-     * // body 类型约束为 CreateUserDTO
-     * ```
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
-    post<TResponse, TBody = unknown, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, TBody, true>>>;
+    post<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
     /**
      * 定义 PUT 请求
      *
      * @template TResponse 响应数据类型
-     * @template TBody 请求体类型（可选，默认 unknown）
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .put<User, UpdateUserDTO>('updateUser', {
-     *   path: '/users/{id}',
-     * })
-     * ```
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
-    put<TResponse, TBody = unknown, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, TBody, true>>>;
+    put<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
     /**
      * 定义 DELETE 请求
      *
      * @template TResponse 响应数据类型
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .delete<void>('deleteUser', {
-     *   path: '/users/{id}',
-     * })
-     * ```
+     * @template K 端点名称
      */
-    delete<TResponse, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, never, false>>>;
+    delete<TResponse, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithoutBody<TResponse>;
+    }>;
     /**
      * 定义 PATCH 请求
      *
      * @template TResponse 响应数据类型
-     * @template TBody 请求体类型（可选，默认 unknown）
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .patch<User, Partial<UpdateUserDTO>>('patchUser', {
-     *   path: '/users/{id}',
-     * })
-     * ```
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
-    patch<TResponse, TBody = unknown, K extends string = string, Path extends string = string>(name: K extends keyof T ? never : K, options: Omit<EndpointOptions<Path>, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse, Path, TBody, true>>>;
+    patch<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
     /**
      * 通用端点定义（内部方法）
-     *
-     * @template TResponse 响应数据类型
-     * @template K 端点名称
-     * @template Path 路径字符串
-     * @template TBody 请求体类型
-     * @template HasBody 是否有请求体
      */
     private endpoint;
     /**
      * 扩展 ky 实例（添加 hooks 等）
      *
-     * @param options ky 配置选项
-     * @returns this（支持链式调用）
-     *
-     * @example
-     * ```ts
-     * .extend({
-     *   hooks: {
-     *     beforeRequest: [(req) => {
-     *       req.headers.set('Authorization', `Bearer ${token}`)
-     *     }],
-     *   },
-     * })
-     * ```
+     * @param options Ky 配置选项
+     * @returns 当前 Builder 实例（保留累积的类型）
      */
-    extend(options: KyOptions): this;
+    extend(options: KyOptions): ApiBuilder<T>;
     /**
      * 构建 API 服务
      *
-     * 将所有定义的端点转换为可调用的 API 对象。
-     * 每个端点都带有完整的类型信息（响应类型、路径参数、请求体类型）。
-     *
      * @returns 类型安全的 API 对象
-     *
-     * @example
-     * ```ts
-     * const api = ApiBuilder.create({ baseUrl: '...' })
-     *   .get<User>('getUser', { path: '/users/{id}' })
-     *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
-     *   .build()
-     *
-     * // 类型安全调用
-     * await api.getUser({ pathParams: { id: '1' } })
-     * await api.createUser({ body: { name: 'John', email: 'x@x.com' } })
-     * ```
      */
     build(): T;
     /**
      * 获取 HTTP 客户端实例（用于高级操作）
-     *
-     * @returns HttpClient 实例
-     *
-     * @example
-     * ```ts
-     * const client = api.getClient()
-     * await client.clearCache()
-     * ```
      */
     getClient(): HttpClient;
 }
-/**
- * 从路径字符串中提取参数名称
- *
- * @example
- * ```ts
- * type Params = ExtractPathParams<'/users/{userId}/posts/{postId}'>
- * // Params = 'userId' | 'postId'
- * ```
- */
-export type { ExtractPathParams, PathParamsType, HasPathParams };
+export {};
 //# sourceMappingURL=ApiBuilder.d.ts.map

package/dist/http/api/ApiBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}

package/dist/http/api/ApiBuilder.js

@@ -8,45 +8,56 @@
  *
  * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
  * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
- * - **路径参数推断**：从 path 字符串自动提取 `{param}` 并约束 `pathParams` 类型
  * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
- * - **防止重复端点**：添加已存在的端点名称会编译报错
  *
  * @example
  * ```ts
  * interface CreateUserDTO { name: string; email: string }
  *
- * // 定义 API
  * const userApi = ApiBuilder.create({
  *   baseUrl: 'https://api.example.com',
  * })
- *   .get<User>('getUser', {
- *     path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
- *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
- *   })
+ *   .get<User>('getUser', { path: '/users/{id}' })
  *   .get<User[]>('getUsers', { path: '/users' })
- *   .post<User, CreateUserDTO>('createUser', { path: '/users' })  // body 类型为 CreateUserDTO
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
  *   .build()
  *
  * // ✅ 类型正确推断
- * userApi.getUser({ pathParams: { id: '123' } })          // pathParams 必须有 id
- * userApi.getUsers()                                       // 无需 pathParams
- * userApi.createUser({ body: { name: 'John', email: 'x' } }) // body 类型检查
+ * userApi.getUser({ pathParams: { id: '123' } })
+ * userApi.createUser({ body: { name: 'John', email: 'x' } })
  *
  * // ❌ 类型错误会被捕获
- * userApi.getUser({ pathParams: { wrong: '1' } })  // Error: 缺少 id
- * userApi.createUser({ body: { wrong: 'x' } })     // Error: body 类型不匹配
- * userApi.unknownMethod()                          // Error: 方法不存在
+ * userApi.unknownMethod()  // Error: 方法不存在
  * ```
  */
 import { HttpClient } from '../client/HttpClient';
-// ============================================================================
-// API 构建器
-// ============================================================================
 /**
  * API 构建器类
  *
+ * 使用链式调用定义类型安全的 API 端点。
+ *
  * @template T 当前已定义的端点类型集合，通过链式调用累积
+ *
+ * @remarks
+ * **类型深度限制**：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
+ *
+ * 建议：
+ * - 保持单个 builder 的端点数量在 4 个以内
+ * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({ baseUrl: '/api' })
+ *   .get<User>('getUser', { path: '/users/{id}' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+ *   .put<User, UpdateUserDTO>('updateUser', { path: '/users/{id}' })
+ *   .build()
+ *
+ * // 类型安全调用
+ * const user = await userApi.getUser({ pathParams: { id: '1' } })
+ * const newUser = await userApi.createUser({ body: { name: 'John', email: 'j@test.com' } })
+ * ```
  */
 export class ApiBuilder {
     constructor(config) {
@@ -58,14 +69,6 @@ export class ApiBuilder {
      *
      * @param config HTTP 客户端配置
      * @returns 新的 ApiBuilder 实例
-     *
-     * @example
-     * ```ts
-     * const api = ApiBuilder.create({
-     *   baseUrl: 'https://api.example.com',
-     *   timeout: 10000,
-     * })
-     * ```
      */
     static create(config) {
         return new ApiBuilder(config);
@@ -76,12 +79,6 @@ export class ApiBuilder {
      * @param kyInstance 已配置的 ky 实例
      * @param config 可选的额外配置
      * @returns 新的 ApiBuilder 实例
-     *
-     * @example
-     * ```ts
-     * const kyInstance = ky.create({ prefixUrl: 'https://api.example.com' })
-     * const api = ApiBuilder.from(kyInstance)
-     * ```
      */
     static from(kyInstance, config) {
         const builder = new ApiBuilder({
@@ -95,46 +92,17 @@ export class ApiBuilder {
      * 定义 GET 请求
      *
      * @template TResponse 响应数据类型
-     * @template K 端点名称（自动推断，不能与已有端点重复）
-     * @template Path 路径字符串（自动推断，用于提取路径参数）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .get<User>('getUser', {
-     *   path: '/users/{id}',  // pathParams 自动约束为 { id: string | number }
-     *   cache: { mode: CacheMode.IfCache },
-     * })
-     * ```
+     * @template K 端点名称（自动推断）
      */
-    get(name, // 防止重复端点名称
-    options) {
+    get(name, options) {
         return this.endpoint(name, { ...options, method: 'GET' });
     }
     /**
      * 定义 POST 请求
      *
      * @template TResponse 响应数据类型
-     * @template TBody 请求体类型（可选，默认 unknown）
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * interface CreateUserDTO { name: string; email: string }
-     *
-     * .post<User, CreateUserDTO>('createUser', {
-     *   path: '/users',
-     * })
-     * // body 类型约束为 CreateUserDTO
-     * ```
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
     post(name, options) {
         return this.endpoint(name, { ...options, method: 'POST' });
@@ -143,20 +111,8 @@ export class ApiBuilder {
      * 定义 PUT 请求
      *
      * @template TResponse 响应数据类型
-     * @template TBody 请求体类型（可选，默认 unknown）
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .put<User, UpdateUserDTO>('updateUser', {
-     *   path: '/users/{id}',
-     * })
-     * ```
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
     put(name, options) {
         return this.endpoint(name, { ...options, method: 'PUT' });
@@ -165,19 +121,7 @@ export class ApiBuilder {
      * 定义 DELETE 请求
      *
      * @template TResponse 响应数据类型
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .delete<void>('deleteUser', {
-     *   path: '/users/{id}',
-     * })
-     * ```
+     * @template K 端点名称
      */
     delete(name, options) {
         return this.endpoint(name, { ...options, method: 'DELETE' });
@@ -186,32 +130,14 @@ export class ApiBuilder {
      * 定义 PATCH 请求
      *
      * @template TResponse 响应数据类型
-     * @template TBody 请求体类型（可选，默认 unknown）
-     * @template K 端点名称（自动推断）
-     * @template Path 路径字符串（自动推断）
-     *
-     * @param name 端点名称
-     * @param options 端点配置
-     * @returns 累积了新端点类型的 ApiBuilder
-     *
-     * @example
-     * ```ts
-     * .patch<User, Partial<UpdateUserDTO>>('patchUser', {
-     *   path: '/users/{id}',
-     * })
-     * ```
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
     patch(name, options) {
         return this.endpoint(name, { ...options, method: 'PATCH' });
     }
     /**
      * 通用端点定义（内部方法）
-     *
-     * @template TResponse 响应数据类型
-     * @template K 端点名称
-     * @template Path 路径字符串
-     * @template TBody 请求体类型
-     * @template HasBody 是否有请求体
      */
     endpoint(name, options) {
         var _a;
@@ -224,25 +150,13 @@ export class ApiBuilder {
             cache: options.cache,
         };
         this.endpoints.set(name, config);
-        // 关键：返回 this，但类型已经累积
         return this;
     }
     /**
      * 扩展 ky 实例（添加 hooks 等）
      *
-     * @param options ky 配置选项
-     * @returns this（支持链式调用）
-     *
-     * @example
-     * ```ts
-     * .extend({
-     *   hooks: {
-     *     beforeRequest: [(req) => {
-     *       req.headers.set('Authorization', `Bearer ${token}`)
-     *     }],
-     *   },
-     * })
-     * ```
+     * @param options Ky 配置选项
+     * @returns 当前 Builder 实例（保留累积的类型）
      */
     extend(options) {
         this.client.extendKy(options);
@@ -251,27 +165,11 @@ export class ApiBuilder {
     /**
      * 构建 API 服务
      *
-     * 将所有定义的端点转换为可调用的 API 对象。
-     * 每个端点都带有完整的类型信息（响应类型、路径参数、请求体类型）。
-     *
      * @returns 类型安全的 API 对象
-     *
-     * @example
-     * ```ts
-     * const api = ApiBuilder.create({ baseUrl: '...' })
-     *   .get<User>('getUser', { path: '/users/{id}' })
-     *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
-     *   .build()
-     *
-     * // 类型安全调用
-     * await api.getUser({ pathParams: { id: '1' } })
-     * await api.createUser({ body: { name: 'John', email: 'x@x.com' } })
-     * ```
      */
     build() {
         const api = {};
         for (const [name, config] of this.endpoints) {
-            // 运行时不需要类型检查，类型安全由编译时保证
             const endpoint = ((options) => {
                 return this.client.request(config, options);
             });
@@ -282,14 +180,6 @@ export class ApiBuilder {
     }
     /**
      * 获取 HTTP 客户端实例（用于高级操作）
-     *
-     * @returns HttpClient 实例
-     *
-     * @example
-     * ```ts
-     * const client = api.getClient()
-     * await client.clearCache()
-     * ```
      */
     getClient() {
         return this.client;

package/dist/http/api/index.d.ts

@@ -1,2 +1,2 @@
-export { ApiBuilder, type ApiEndpoint, type ApiDefinition, type ExtractPathParams, type PathParamsType, type HasPathParams, } from './ApiBuilder';
+export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './ApiBuilder';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,GACrB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA"}

package/dist/http/api/index.js

@@ -1 +1 @@
-export { ApiBuilder, } from './ApiBuilder';
+export { ApiBuilder } from './ApiBuilder';

package/dist/http/demo/api-builder.demo.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ApiBuilder 使用示例
+ *
+ * 此文件演示 ApiBuilder 的类型安全特性：
+ * 1. 泛型累积 - 链式调用自动累积端点类型
+ * 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
+ * 3. 端点名称字面量 - 调用不存在的端点会编译报错
+ */
+/** 用户实体 */
+interface User {
+    id: string;
+    name: string;
+    email: string;
+    createdAt: string;
+}
+/** 创建用户 DTO */
+interface CreateUserDTO {
+    name: string;
+    email: string;
+}
+/** 更新用户 DTO */
+interface UpdateUserDTO {
+    name?: string;
+    email?: string;
+}
+/** 分页响应 */
+interface PaginatedResponse<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export declare const userApi: object & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<User[]>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<User>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<PaginatedResponse<User>>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, CreateUserDTO>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyOptional<void>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, UpdateUserDTO>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, Partial<UpdateUserDTO>>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<void>;
+};
+declare function demo(): Promise<void>;
+declare function typeErrors(): void;
+export { demo, typeErrors };
+//# sourceMappingURL=api-builder.demo.d.ts.map

package/dist/http/demo/api-builder.demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-builder.demo.d.ts","sourceRoot":"","sources":["../../../src/http/demo/api-builder.demo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,WAAW;AACX,UAAU,IAAI;IACV,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CACpB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,WAAW;AACX,UAAU,iBAAiB,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACnB;AAMD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;CA8DR,CAAA;AAMZ,iBAAe,IAAI,kBAuElB;AAoBD,iBAAS,UAAU,SAYlB;AAMD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA"}

package/dist/http/demo/api-builder.demo.js

@@ -0,0 +1,163 @@
+/**
+ * ApiBuilder 使用示例
+ *
+ * 此文件演示 ApiBuilder 的类型安全特性：
+ * 1. 泛型累积 - 链式调用自动累积端点类型
+ * 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
+ * 3. 端点名称字面量 - 调用不存在的端点会编译报错
+ */
+import { ApiBuilder } from '../api/ApiBuilder';
+import { CacheMode } from '../models/CacheMode';
+// ============================================================================
+// 创建 API 服务
+// ============================================================================
+export const userApi = ApiBuilder.create({
+    baseUrl: 'https://api.example.com',
+    timeout: 10000,
+    defaultCache: {
+        mode: CacheMode.FirstRemote,
+        ttl: 5 * 60 * 1000,
+    },
+})
+    // GET 请求 - 无路径参数
+    .get('getUsers', {
+    path: '/users',
+    cache: { mode: CacheMode.FirstCache },
+})
+    // GET 请求 - 有路径参数
+    .get('getUser', {
+    path: '/users/{id}',
+    cache: { mode: CacheMode.IfCache, ttl: 60000 },
+})
+    // GET 请求 - 分页
+    .get('getUsersPaginated', {
+    path: '/users/paginated',
+})
+    // POST 请求 - 有 body 类型
+    .post('createUser', {
+    path: '/users',
+})
+    // POST 请求 - 无 body 类型（触发器）
+    .post('activateUser', {
+    path: '/users/{id}/activate',
+})
+    // PUT 请求 - 完整更新
+    .put('updateUser', {
+    path: '/users/{id}',
+})
+    // PATCH 请求 - 部分更新
+    .patch('patchUser', {
+    path: '/users/{id}',
+})
+    // DELETE 请求
+    .delete('deleteUser', {
+    path: '/users/{id}',
+})
+    // 扩展 ky 实例（添加拦截器）
+    .extend({
+    hooks: {
+        beforeRequest: [
+            (request) => {
+                const token = 'mock-token';
+                request.headers.set('Authorization', `Bearer ${token}`);
+            },
+        ],
+    },
+})
+    .build();
+// ============================================================================
+// 使用示例 - 类型安全调用
+// ============================================================================
+async function demo() {
+    // ✅ GET 无路径参数
+    const users = await userApi.getUsers();
+    console.log('Users:', users);
+    // ✅ GET 有路径参数
+    const user = await userApi.getUser({
+        pathParams: { id: '123' },
+    });
+    console.log('User:', user);
+    // ✅ GET 带 query 参数
+    const paginatedUsers = await userApi.getUsersPaginated({
+        query: { page: 1, pageSize: 10 },
+    });
+    console.log('Paginated:', paginatedUsers);
+    // ✅ POST 有 body 类型约束
+    const newUser = await userApi.createUser({
+        body: { name: 'John', email: 'john@example.com' },
+    });
+    console.log('Created:', newUser);
+    // ✅ POST 无 body（触发器）
+    await userApi.activateUser({
+        pathParams: { id: '123' },
+    });
+    // ✅ PUT 完整更新
+    const updatedUser = await userApi.updateUser({
+        pathParams: { id: '123' },
+        body: { name: 'John Updated', email: 'john.updated@example.com' },
+    });
+    console.log('Updated:', updatedUser);
+    // ✅ PATCH 部分更新
+    const patchedUser = await userApi.patchUser({
+        pathParams: { id: '123' },
+        body: { name: 'John Patched' },
+    });
+    console.log('Patched:', patchedUser);
+    // ✅ DELETE
+    await userApi.deleteUser({
+        pathParams: { id: '123' },
+    });
+    // ✅ 覆盖缓存配置
+    const freshUser = await userApi.getUser({
+        pathParams: { id: '123' },
+        cache: { mode: CacheMode.OnlyRemote },
+    });
+    console.log('Fresh:', freshUser);
+    // ✅ 多次响应（for await）
+    for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
+        console.log('Data:', data, 'FromCache:', fromCache);
+    }
+    // ✅ subscribe 方式
+    await userApi.getUser({ pathParams: { id: '123' } }).subscribe({
+        onData: (data, fromCache) => {
+            console.log('Subscribe data:', data, fromCache);
+        },
+        onError: (error) => {
+            console.error('Error:', error);
+        },
+        onComplete: () => {
+            console.log('Complete');
+        },
+    });
+}
+// ============================================================================
+// 类型错误示例
+// ============================================================================
+/**
+ * 类型安全验证
+ *
+ * 注意：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当链式调用超过 4 个端点时，类型推断可能不够精确。
+ * 建议：保持单个 builder 的端点数量在 4 个以内，或分批构建。
+ *
+ * 以下是简化版本的类型安全验证（2-3 个端点）
+ */
+const simpleApi = ApiBuilder.create({ baseUrl: 'http://test' })
+    .get('getUser', { path: '/users/{id}' })
+    .post('createUser', { path: '/users' })
+    .build();
+function typeErrors() {
+    // ❌ body 类型不匹配（缺少 email）
+    // @ts-expect-error email is required
+    simpleApi.createUser({ body: { name: 'John' } });
+    // ❌ body 类型不匹配（错误的属性）
+    // @ts-expect-error wrong property
+    simpleApi.createUser({ body: { wrong: 'x' } });
+    // ❌ GET 请求不应该有 body
+    // @ts-expect-error body not allowed for GET
+    simpleApi.getUser({ pathParams: { id: '1' }, body: {} });
+}
+// ============================================================================
+// 导出
+// ============================================================================
+export { demo, typeErrors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "private": false,
   "type": "module",
   "main": "dist/index.js",