@anycms/web-client

TypeScript SDK for anycms-web CRUD routes and JsonQuery engine.

提供类型安全的查询构建器和 CRUD API 客户端，与后端 crud_routes! 宏生成的路由一一对应。

安装

npm install @anycms/web-client

使用

CRUD API 客户端

import { QueryBuilder, createEntityApi } from '@anycms/web-client';

const api = createEntityApi<Customer>('/api/customer');

// 列表查询（POST /api/customer/list）
const result = await api.query(
  new QueryBuilder().eq('status', 1).page(1, 20).build()
);
// result: { items: Customer[], total: number, page: number, pageSize: number }

// CRUD
const created = await api.create({ name: 'New' });
const item = await api.get('id');
const updated = await api.update('id', { name: 'Updated' });
await api.delete('id');

QueryBuilder 查询

// 简单查询
const query = new QueryBuilder()
  .eq('status', 1)
  .in('level', [1, 2, 3])
  .keyword('搜索关键词')
  .sort('created_time', 'desc')
  .page(1, 20)
  .build();

// AND/OR 嵌套: status=1 AND (level=1 OR level=2)
const query = new QueryBuilder()
  .eq('status', 1)
  .or(b => b.eq('level', 1).eq('level', 2))
  .build();

// 复杂嵌套: (type=1 AND level>=2) OR (type=2 AND level=3)
const query = new QueryBuilder()
  .orGroup([
    b => b.eq('type', 1).gte('level', 2),
    b => b.eq('type', 2).eq('level', 3),
  ])
  .build();

// 范围查询
const query = new QueryBuilder()
  .between('price', 100, 500)
  .build();

// 文本过滤
const query = new QueryBuilder()
  .notContains('title', 'spam')
  .isEmpty('remark')
  .build();

路由对应关系

SDK 方法与 crud_routes! 宏生成的端点一一对应：

| SDK 方法 | HTTP 方法 | 路径 | 说明 | |----------|-----------|------|------| | query(jsonQuery) | POST | /list | JsonQuery 查询 | | get(id) | GET | /{id} | 按 ID 获取 | | create(data) | POST | `` | 创建 | | update(id, data) | PUT | /{id} | 更新 | | delete(id) | DELETE | /{id} | 删除 |

响应格式

后端返回 ApiResult<T> 统一响应，SDK 自动解包：

interface ApiResult<T> {
  success: boolean;
  data?: T | T[];         // 单个对象或数组
  message?: string;       // 错误信息
  code?: number;          // 错误码
  pagination?: {          // 分页（仅列表查询）
    total: number;
    page: number;
    pageSize: number;
    currentPage: number;
  };
  errors?: { field: string; message: string }[];  // 字段级校验错误
  traceId?: string;
}

错误时抛出 ApiError：

try {
  await api.get('invalid-id');
} catch (e) {
  if (e instanceof ApiError) {
    console.log(e.code, e.message, e.errors);
  }
}

API 参考

QueryBuilder

| 方法 | 说明 | |------|------| | eq(field, value) | 等于 | | ne(field, value) | 不等于 | | gt(field, value) | 大于 | | gte(field, value) | 大于等于 | | lt(field, value) | 小于 | | lte(field, value) | 小于等于 | | contains(field, value) | 模糊包含 (LIKE %value%) | | notContains(field, value) | 不包含 (NOT LIKE %value%) | | startsWith(field, value) | 前缀匹配 | | endsWith(field, value) | 后缀匹配 | | in(field, values) | 在列表中 | | notIn(field, values) | 不在列表中 | | between(field, min, max) | 范围查询 | | isNull(field) | 为空 (IS NULL) | | isNotNull(field) | 不为空 (IS NOT NULL) | | isEmpty(field) | 空字符串 (= '' OR IS NULL) | | isNotEmpty(field) | 非空字符串 (!= '' AND IS NOT NULL) | | keyword(keyword) | 关键词搜索 | | sort(field, order) | 排序 (order: 'asc' / 'desc') | | asc(field) | 升序排序 | | desc(field) | 降序排序 | | page(page, pageSize) | 分页 (默认 pageSize=20) | | or(fn) | 添加 OR 组 | | and(fn) | 添加 AND 组 | | orGroup(fns) | 多个 AND 组之间 OR | | build() | 构建 JsonQuery 对象 |

createEntityApi

const api = createEntityApi<T>(basePath, options?)

Options:

| 参数 | 说明 | |------|------| | baseUrl | 基础 URL 前缀 | | fetch | 自定义 fetch 函数 | | headers | 默认请求头 |

License

MIT