@kevisual/query

封装 fetch、认证 token 和统一响应，默认向 /api/router 发送 POST 请求。

路由调用

import { Query } from '@kevisual/query';

const query = new Query();
await query.post({
  key: 'info', path: 'user', time: 'v1',
  payload: { id: '123' },
});
await query.post({ route_key: 'user:info:v1', payload: { id: '123' } });

path 必填，key、time 可省略；也可以仅提供 route_key。 完整键格式为 path:key:time，缺省位置保留，例如 user:info:、user::。 同时提供两种身份时，以 route_key 为准；非法键返回错误，不回退到其他字段。 请求钩子执行后统一处理身份，请求体、URL 参数及自定义 adapter 使用相同的定位信息。

import type { Data, RouteReference } from '@kevisual/query';

const request: Data = { route_key: 'user:info:v1', payload: { id: '123' } };
const reference: RouteReference = { key: 'info', path: 'user' };

query.get 保留转发至 POST 的行为。实际发送 GET 时，使用 query.post(request, { method: 'GET' })；payload 会序列化为 JSON 查询参数。 Request 子入口提供通用 HTTP 请求，QueryWs 提供通用消息传输。

三层 API 和代码生成

import { createQueryApi, createQueryByRoutes } from '@kevisual/query/api';

const queryApi = createQueryApi({ api: {
  user: {
    info: {
      v1: {
        route_key: 'user:info:v1',
        metadata: { args: { id: { type: 'string' } } },
      },
      '': { key: 'info', path: 'user' },
    },
  },
} as const });

await queryApi.user.info.v1({ id: '123' });
await queryApi.user.info['']();

const routes = await query.post({ key: 'list', path: 'router' });
const source = createQueryByRoutes(routes.data.list);

固定使用 [path][key][time] 三层结构，未设置的 key/time 使用 ''。 生成器根据 route_key 优先解析身份，保留多版本、schema、描述及 method 元数据，重复完整键会报错。 method 不自动改变 HTTP 方法，调用时仍由请求选项控制。 与 QueryApi 成员或原型成员重名的 path（例如 query、post、createApi）会报错。

生成选项包括 onlyIdentity（仅保留身份）、removeViewItem、dts、before、after。 生成过程不修改传入的路由列表。dts: true 输出声明内容。

迁移（1.1.0）

不再支持 name/namespace/version 路由定位。namespace 改为 path，name 改为 key，version 改为 time；只有 name 的路由改为 { path: 原name }。 完整键调整为 path:key:time，请同步更新 route_key 并重新生成 API 文件。 path 必填，key/time 可省略；对应 API 层使用 ''，例如 queryApi.auth['']['']()。 time 保持字符串标识及精确匹配语义，不转换为时间戳。字段校验沿用字母、数字、-、_。 普通业务参数、文件路径和 metadata 不受影响。

本地验证

在仓库根目录安装工作区依赖，先构建本地 router，再执行本包的 bun run test、 bun run test:types 和 bun run build。