5 篇博文 含有标签「REST」

v0.18 聚焦于三件事：对随请求上下文变化的值进行更丰富的数据建模、更简单的类型化下载，以及更贴近真实 API 过滤条件的集合匹配。

新特性：

• Scalar schema - 随视角（lens）变化的实体字段（例如特定投资组合的数值），且永不修改底层实体
• RestEndpoint content 属性 - 只用一个属性即可实现类型化文件下载、文本响应和流式传输
• resource() nonFilterArgumentKeys - 排序/分页参数不再把你的 Collection 拆散

其他改进：

• 二进制 Content-Type 自动检测 - 图片、PDF 及其他二进制响应无需任何配置即可自动处理（#3868）
• Collection 扩展方法的 body 类型与 HTTP 方法语义一致 - PATCH 扩展方法（.move、.remove）接受部分 body；独立的 RestEndpoint 会从 Collection 的实体 schema 推导出类型化的 body（#3910）
• 从 @data-client/endpoint 和 @data-client/rest 导出 CollectionOptions，用于类型化地构造 Collection（#3904）

import { Collection, Entity, RestEndpoint, Scalar } from '@data-client/rest';

export class Company extends Entity {
  id = '';
  name = '';
  price = 0;
  pct_equity = 0;
  shares = 0;
}

const PortfolioScalar = new Scalar({
  lens: args => args[0]?.portfolio,
  key: 'portfolio',
  entity: Company,
});
Company.schema = {
  pct_equity: PortfolioScalar,
  shares: PortfolioScalar,
};

export const getCompanies = new RestEndpoint({
  path: '/companies',
  searchParams: {} as { portfolio: string },
  // `portfolio` is a lens, not a filter — the returned Company list is the same
  // regardless of lens. Dropping it from `argsKey` collapses every portfolio to
  // one Collection pk, so `Collection.queryKey()` finds the list on every
  // switch and `useSuspense` reuses it without refetching.
  schema: new Collection([Company], { argsKey: () => ({}) }),
});

export const getPortfolioColumns = new RestEndpoint({
  path: '/companies/columns',
  searchParams: {} as { portfolio: string },
  schema: new Collection([PortfolioScalar], {
    argsKey: ({ portfolio }: { portfolio: string }) => ({ portfolio }),
  }),
});

这个示例展示了同一批 Company 实体通过不同的投资组合视角进行渲染。稳定的 Entity 字段会被复用，而随视角变化的值则从独立的 Scalar 单元格中选取。

破坏性变更：

• Schema.denormalize() 接收 delegate - denormalize(input, args, unvisit) → denormalize(input, delegate)。仅影响自定义 Schema 实现。
• Schema.normalize() 接收 delegate - normalize(input, parent, key, args, visit, delegate) → normalize(input, parent, key, delegate)。仅影响自定义 Schema 实现。

**在使用 AI 智能体？**安装迁移 skill——它会运行 codemod，为依赖参数的 schema 注册 argsKey，并处理 codemod 无法覆盖的情况（类字段、动态方法赋值、SFC <script> 块、自定义辅助函数）：

npx skills add reactive/data-client --skill data-client-v0.18-migration

npx openskills install reactive/data-client/.agents/skills/data-client-v0.18-migration

claude plugin marketplace add reactive/data-client
claude plugin install migrations@data-client

否则，直接运行 codemod——它覆盖了常见情况：

npx jscodeshift -t https://dataclient.io/codemods/v0.18.js --extensions=ts,tsx,js,jsx src/

新特性：

• 使用 useFetch() 并行加载数据——通过 use(useFetch()) 并发获取多个 endpoint，避免串行瀑布流
• Collection.move——用一次操作在多个 Collection 之间移动实体
• Collection.moveWith()——自定义移动行为（例如前置插入而非追加）
• Lazy——延迟关系的反规范化，以提升性能并隔离记忆化

其他改进：

• 直接导入 schema——无需 schema 命名空间即可直接导入 schema 类
• 反规范化深度限制——防止大型双向实体图导致栈溢出；可通过 Entity.maxEntityDepth 配置（#3822）
• DevToolsManager 在开发模式下暴露 globalThis.__DC_CONTROLLERS__，便于从 Chrome DevTools MCP 和 Expo MCP 以编程方式访问 store。使用 data-client-react skill 来启用 AI 辅助调试。
• 移除 Next.js SSR 期间具有误导性的 'Uncaught Suspense' 警告
• 修复 RestEndpoint 中 method: 'POST' 导致 sideEffect: false 类型丢失的问题
• renderDataHook() 在每个测试之后自动清理——无需手动调用 cleanup()
• renderDataHook() 返回每次渲染的 cleanup() 和 allSettled()，让测试的收尾更可靠

Collection.move 让你能够用一次操作轻松地在多个 Collection 之间移动实体：

import { useController } from '@data-client/react';
import { TaskResource, type Task } from './TaskResource';

export default function TaskCard({ task }: { task: Task }) {
  const handleMove = () => ctrl.fetch(
    TaskResource.getList.move,
    { id: task.id },
    { id: task.id, status: task.status === 'backlog' ? 'in-progress' : 'backlog' },
  );
  const ctrl = useController();
  return (
    <div className="listItem">
      <span style={{ flex: 1 }}>{task.title}</span>
      <button onClick={handleMove}>
        {task.status === 'backlog' ? '\u25bc' : '\u25b2'}
      </button>
    </div>
  );
}

破坏性变更：

• path-to-regexp v8——RestEndpoint.path 语法更新：/:optional? → {/:optional}，/:repeat+ → /*repeat（类型为 string[]）
• useFetch() 返回 UsablePromise——返回可供 React.use() 使用的 thenable；请检查 .resolved 而不是真值性

使用自动化 codemod 升级，它涵盖所有破坏性变更：

npx jscodeshift -t https://dataclient.io/codemods/v0.16.js --extensions=ts,tsx,js,jsx src/

本次发布聚焦于一致性和可扩展性。null 处理现在在所有 schema 类型中保持统一，使数据转换更可预测。新的 URL 工具函数支持自定义 URL 构造和搜索参数编码。

class MyEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
  searchToString(searchParams) {
    // Use qs library for complex nested object encoding
    return qs.stringify(searchParams);
  }
}

破坏性变更：

• Array/Object schema 中保留 null 值

其他改进：

• RestEndpoint.searchToString() 用于自定义搜索参数编码
• 导出 getUrlBase、getUrlTokens 用于自定义 URL 构造
• 修复 DevToolsManager 内存泄漏

本次发布聚焦于开发者体验：在开发模式下显示的 devtools 按钮、更好的 DevTools 历史记录，以及 controller.expireAll() 和 controller.fetchIfStale() 等新的 controller 方法。

Resource.extend() 提供了三种强大的方式来自定义 resource——添加新的 endpoint、覆盖已有的 endpoint，或从基础 endpoint 派生。

const UserResource = createResource({
  path: '/users/:id',
  schema: User,
}).extend('current', {
  path: '/users/current',
});

破坏性变更：

• 移除所有 /next 导出
• 移除 makeCacheProvider
• DELETE -> INVALIDATE action 类型
• 不再支持遗留 schema
• Schema 序列化器必须支持函数调用
• Action 类型加上 'rdc' 前缀

Collection 让数组和对象可以通过 push 或 unshift 新成员来轻松扩展。它的名字来自 Backbone Collections。

Collection 现在是 Resource.getList 的默认 schema。

import { useController } from '@data-client/react';
import { TodoResource } from './TodoResource';

export default function CreateTodo({ userId }: { userId: number }) {
  const ctrl = useController();
  const handleKeyDown = async e => {
    if (e.key === 'Enter') {
      ctrl.fetch(TodoResource.getList.push, {
        userId,
        title: e.currentTarget.value,
        id: Math.random(),
      });
      e.currentTarget.value = '';
    }
  };
  return (
    <div className="listItem nogap">
      <label>
        <input type="checkbox" name="new" checked={false} disabled />
        <input type="text" onKeyDown={handleKeyDown} />
      </label>
    </div>
  );
}

升级相当简单，因为我们引入了 @data-client/rest/next 和 @data-client/react/next，以便渐进式地采用本版本中变更的新 API。这使得实际的升级只是简单地重命名一下导入路径。

其他亮点包括

• @data-client/rest
  • 异步 RestEndpoint.getHeaders
• @data-client/react
  • Controller.fetch() 的返回值按 schema 反规范化
  • Manager action 类型更新

完整细节请继续阅读：