# 斯普什反应 Spoosh 是一个类型安全的 API 工具包，具有适用于 TypeScript 的可组合插件架构。这项技能涵盖了 React 集成，包括钩子 API、插件和组件模式。 ## 设置 pnpm 添加 @spoosh/core @spoosh/react 从“@spoosh/core”导入{Spoosh}；从“@spoosh/react”导入{创建}；类型 ApiSchema = { “用户”：{ 获取：{数据：用户[]}； POST: { 数据: 用户;正文：CreateUserBody }; }; “用户/：id”：{ GET：{数据：用户}；删除：{数据：无效}； }; }; const spoosh = new Spoosh("/api") .use([cachePlugin(), retryPlugin()]); 导出常量 { useRead, useWrite, usePages, useQueue, useSSE } = create(spoosh); ## createClient（轻量级）对于没有钩子或插件的简单用例：从“@spoosh/core”导入{createClient}； const api = createClient("/api"); const { 数据，错误 } = wait api("users").GET(); const { data: user } = wait api("users/:id").GET({ params: { id: "123" } }); wait api("users").POST({ body: { name: "John" } }); ## 钩子 API ### 使用阅读通过自动缓存和状态管理来获取数据。 const { 数据、加载、错误、触发器 } = useRead( (api) => api("用户").GET(), { staleTime: 30000, 启用: true } ）； **返回：** `data`、`loading`、`fetching`、`error`、`trigger()`、`abort()`、`meta` **选项：** `enabled`、`tags`、`staleTime`、`retry`、`pollingInterval`、`refetch`、`debounce`、`transform`、`initialData` ### 使用写入执行突变（POST、PUT、DELETE）。 const { 触发器、加载、错误 } = useWrite((api) => api("users").POST()); 等待触发({ 正文：{姓名，电子邮件}，无效：“全部” }); **返回：** `trigger()`、`loading`、`error`、`data`、`meta`、`abort()` **触发选项：** `body`、`params`、`query`、`headers`、`invalidate`、`clearCache`、`optimistic` ### 使用页面具有无限滚动的双向分页。 const { 数据，fetchNext，canFetchNext，加载 } = usePages( (api) => api("帖子").GET({ 查询: { 页: 1 } }), { canFetchNext: ({lastPage}) =>lastPage?.data?.hasMore ??假的，下一页请求: ({ 最后一页, 请求 }) => ({ 查询: { ...request.query, 页: (lastPage?.data?.page ?? 0) + 1 } }), 合并：(pages)=>pages.flatMap(p=>p.data?.items??[]) } ）； **返回：** `data`、`pages`、`loading`、`fetchingNext`、`canFetchNext`、`fetchNext()`、`fetchPrev()`、`trigger()` ### 使用队列具有并发控制的批量操作的队列管理。 const { 任务、统计信息、触发器、重试 } = useQueue( (api) => api("文件").POST(), { 并发数：3 } ）； files.forEach(文件 => 触发器({ body: form({ file }) })); **返回：** `tasks`、`stats`、`trigger()`、`abort()`、`retry()`、`remove()`、`removeSettled()`、`clear()`、`setConcurrency()` **统计：** `待处理`、`加载中`、`已解决`、`成功`、`失败`、`总计`、`百分比` ### 使用SSE 用于实时流的服务器发送事件。 const { 数据、isConnected、触发器、断开连接 } = useSSE( (api) => api("流").GET(), { 解析：“json”，累积：“替换” } ）； **返回：** `data`、`error`、`isConnected`、`loading`、`trigger()`、`disconnect()`、`reset()` **选项：** `enabled`、`parse` (auto|json|text|json-done)、`accumulate` (replace|merge)、`maxRetries`、`retryDelay` ## 插件插件 |目的|关键选项 ---|---|--- `cachePlugin` |响应缓存 | `陈旧时间` `重试插件` |自动重试 | `重试：{重试，延迟}` `轮询插件` |自动刷新 | `轮询间隔` `invalidationPlugin` |缓存失效| `无效` `optimisticPlugin` |即时 UI 更新 | ‘乐观’ `debouncePlugin` |反跳请求 | `去抖动` `refetchPlugin` |重新获取焦点 | `重新获取：{ onFocus，onReconnect }` `初始数据插件` |预加载数据 | `初始数据` `开发工具` |可视化调试面板| `启用`、`显示浮动图标` ## 开发工具从“@spoosh/devtool”导入{devtool}； const spoosh = new Spoosh("/api") .use([cachePlugin(), devtool({ 启用: process.env.NODE_ENV === "开发" })]); 功能：请求跟踪、插件可视化、缓存检查器、时间线视图。 ## 缓存失效 // 变异后等待触发器（{主体：数据，无效：“全部”}）； // 使层次结构无效等待触发器（{主体：数据，无效：“自我”}）； // 仅精确路径等待触发器（{主体：数据，无效：[“用户”]}）； // 具体标签 ## 组件模式 ### 数据获取导出函数 UserList() { const { 数据、加载、错误、触发器 } = useRead( (api) => api("用户").GET(), { 过时时间：30000 } ）；如果（正在加载）返回； if (error) return ; if (!data?.length) return ; 返回（

)}

）； } ### 变异形式导出函数 CreateUserForm() { const [名称，setName] = useState(""); const { 触发器、加载、错误 } = useWrite((api) => api("users").POST()); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); const 结果 = 等待触发器({ body: { name }, invalidate: "all" }); if (结果.data) setName(""); }; 返回（

setName(e.target.value)} disabled={loading} /> {错误&&

{error.message}

} <按钮禁用={加载}>{加载？ “正在创建...”：“创建”} ）； } ### 无限滚动导出函数 InfinitePostList() { const { ref, inView } = useInView(); const { 数据、加载、fetchingNext、canFetchNext、fetchNext } = usePages( (api) => api("帖子").GET({ 查询: { 页数: 1, 限制: 20 } }), { canFetchNext: ({lastPage}) =>lastPage?.data?.hasMore ??假的，下一页请求: ({ 最后一页, 请求 }) => ({ 查询: { ...request.query, 页: (lastPage?.data?.page ?? 0) + 1 } }), 合并：(pages)=>pages.flatMap((p)=>p.data?.items??[]) } ）；使用效果（（）=> { if (inView && canFetchNext && !fetchingNext) fetchNext(); }, [inView, canFetchNext, fetchingNext]); 如果（加载）返回；返回（

{data?.map((post) => )}

{fetchingNext && }

）； } ### 乐观更新导出函数 ToggleLikeButton({ postId, Liked, likeCount }: Props) { const { 触发器 } = useWrite((api) => api("posts/:id/like").POST()); const 句柄切换 = () => { 触发器（{ 参数: { id: postId }, 乐观：（缓存）=>缓存（`posts/${postId}`） .set((当前) => ({ ...当前，喜欢：！喜欢，喜欢计数：喜欢？喜欢计数 - 1 : 喜欢计数 + 1 }）） }); }; 返回 ; } ### 使用去抖动进行搜索导出函数SearchUsers() { const [查询，setQuery] = useState(""); const { 数据，获取 } = useRead( (api) => api("用户/搜索").GET({ 查询: { q: 查询 } }), { 启用：query.length >= 2，去抖：300 } ）；返回（

setQuery(e.target.value)} placeholder="搜索..." /> {获取&& } {data?.map((user) =>

{user.name}

)}

）； } ### 投票导出函数 JobStatus({ jobId }: { jobId: string }) { const { 数据 } = useRead( (api) => api("jobs/:id").GET({ params: { id: jobId } }), { 轮询间隔: ({ 数据 }) => { if (data?.status === "已完成" || data?.status === "失败") return false; 返回 2000； } } ）；返回

状态：{data?.status}

； } ## Next.js ### 使用 createClient 进行服务器端获取 // 应用程序/帖子/page.tsx 从“@spoosh/core”导入{createClient}； const api = createClient(process.env.API_URL!); 导出默认异步函数 PostsPage() { const { data: posts } = wait api("posts").GET(); 返回 ; } ### 具有初始数据的客户端 // 组件/PostList.tsx “使用客户端”；导出函数PostList({initialData}:{initialData:Post[]}){ const { 数据，加载 } = useRead( (api) => api("帖子").GET(), {initialData } // 第一次渲染时没有加载状态）；返回数据？.map((post) => ); } ### 服务器重新验证的突变 // lib/spoosh.ts 从“@spoosh/plugin-nextjs”导入{nextjsPlugin}； const spoosh = new Spoosh("/api") .use([cachePlugin(), invalidationPlugin(), nextjsPlugin()]); // 突变后，Next.js 缓存标签会自动重新验证等待触发器({ body: newPost, invalidate: "all" }); ## 服务器类型推断 ### 霍诺从“@spoosh/core”导入{ Spoosh，StripPrefix }；从“@spoosh/hono”导入类型{HonoToSpoosh}； // 服务器：app.basePath("/api") type FullSchema = HonoToSpoosh<应用程序类型>; 类型 ApiSchema = StripPrefix; // 避免重复 /api/api const spoosh = new Spoosh("/api"); ### 艾丽西亚从“@spoosh/core”导入{ Spoosh，StripPrefix }；从“@spoosh/elysia”导入类型 { ElysiaToSpoosh }； // 服务器: new Elysia({ prefix: "/api" }) type FullSchema = ElysiaToSpoosh<应用程序类型>; 类型 ApiSchema = StripPrefix; // 避免重复 /api/api const spoosh = new Spoosh("/api"); 当您的 baseUrl 包含与服务器的 basePath 相同的前缀时，请使用 `StripPrefix` 以防止双重前缀（例如，`/api/api/users`）。 ## 开放API # 导出 TypeScript → OpenAPI npx spoosh-openapi 导出 --schema ./schema.ts --output openapi.json # 导入 OpenAPI → TypeScript npx spoosh-openapi 导入 openapi.json --output ./schema.ts ## 参考文献详细API文档： * `references/hooks-api.md` \- 完整的钩子签名 * `references/plugins-api.md` \- 所有插件配置 * `references/advanced-patterns.md` \- 复杂模式和边缘情况如果需要更多详细信息，请获取（或 /llms-full 以获得完整文档）。

斯普什反应

包含技能