# @cocreate/crud-client 中文文档

规范地址：https://npmcn.com/package/%40cocreate/crud-client/

版本：2\.0\.1
npm 元数据更新时间：2026-11-05T23:51:32.199Z
中文译文更新时间：2026-11-10T05:25:43.687Z
软件包许可：AGPL-3\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cocreate/crud-client
原文对照：https://npmcn.com/package/%40cocreate/crud-client/?lang=original
项目主页：https://cocreatejs.com/docs/crud-client
源码仓库：https://github.com/CoCreateJS/crud-client

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：206 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2021-04-03T23:17:24.268Z
- 最新版本发布：2026-11-05T23:51:32.029Z
- 近 30 天下载量：3191（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：337（近 12 个月 12 个）

## 中文简介

一个高性能,多租借的CRUD客户端,用于CoCreate. 使用统一的API执行创建,读取,更新,删除,并针对一个或多个存储提供者进行实时同步操作. 支持各种数据库的并行持久性,例如:

## 安装

```sh
npm install @cocreate/crud-client
```

也可以使用：`pnpm add @cocreate/crud-client`、`yarn add @cocreate/crud-client`、`bun add @cocreate/crud-client`

## README

# @ cocreate/ crud- 客户端

一个高性能、数据库不可知客户端的CRUD引擎,用于使用单一的统一有效载荷进行查询、同步和持续应用数据。 它提供离线第一架构,透明地同步本地和远程存储提供商,并与CoCreate实时协作生态系统进行无缝整合. 单一的CRUD请求可以同时瞄准一个或多个存储提供者,允许应用程序在分布式数据库之间保持同步数据,并具有最小的应用逻辑.

* * *

## 文档

对于完整的API参考文献,存储适配器配置,同步策略,以及高级示例,参考了CoCreate CRUD客户端文档.

## 目录

-   [特征](https://npmcn.com/package/%40cocreate/crud-client/#readme-features)
-   [安装](https://npmcn.com/package/%40cocreate/crud-client/#readme-installation)
-   [使用量](https://npmcn.com/package/%40cocreate/crud-client/#readme-usage)
-   [如何运作](https://npmcn.com/package/%40cocreate/crud-client/#readme-how-it-works)
-   [结构和有效载荷光谱](https://npmcn.com/package/%40cocreate/crud-client/#readme-architecture-and-payload-specs)
-   [离线同步](https://npmcn.com/package/%40cocreate/crud-client/#readme-offline-synchronization)
-   [储存供应商](https://npmcn.com/package/%40cocreate/crud-client/#readme-storage-providers)
-   [通知](https://npmcn.com/package/%40cocreate/crud-client/#readme-announcements)
-   [路线图](https://npmcn.com/package/%40cocreate/crud-client/#readme-roadmap)
-   [如何贡献](https://npmcn.com/package/%40cocreate/crud-client/#readme-how-to-contribute)
-   [许可证](https://npmcn.com/package/%40cocreate/crud-client/#readme-license)

* * *

## 特征

-   **统一 CRUD API :** 使用一致的有效载荷结构创建、读取、更新和删除数据,而不论潜在的存储提供者如何.
-   **多堆放执行 :** 同步执行针对一个或多个存储提供者的 CRUD 操作 .
-   **并行数据库同步 :** 当指定多个存储提供者时,操作同时执行,以保持分布式数据库同步.
-   **离线- 第一架构 :** 继续使用本地存储提供者进行下线时读取并写入数据.
-   **实时同步 :** 与CoCreate Socket生态系统无缝地集成,使客户端和服务器的数据同步.
-   **数据库不可知论 :** 支持索引DB,SQLite,MongoDB,PostgreSQL,MySQL,Firestore,以及通过统一的有效载荷格式的额外适配器.
-   **优化更新 :** 本地操作在背景中发生远程同步时立即执行.
-   **无国籍操作 :** 每个 CRUD 请求都是完全自成一体的,使得请求容易进行序列化,排队,重试,并重放.

* * *

## 安装

```bash
npm install @cocreate/crud-client
```

* * *

## 使用量

### 初始化客户端

```javascript
import crud from "@cocreate/crud-client";

await crud.init({
    organization_id: "64b9a32e18f21bc56789abcd",
    host: window.location.host
});
```

* * *

### 读取数据

```javascript
const response = await crud.send({
    method: "object.read",
    array: "users"
});

console.log(response);
```

* * *

### 从特定存储提供者读取

```javascript
const response = await crud.send({
    method: "object.read",
    array: "users",
    storage: "mongodb"
});
```

何时 `storage` 是字符串,操作只针对指定的存储提供者执行.

* * *

### 在单一存储提供者中创建数据

```javascript
await crud.send({
    method: "object.create",
    array: "users",
    storage: "mongodb",
    object: [{
        name: "John Doe",
        email: "john@example.com"
    }]
});
```

* * *

### 在多个存储提供者中创建数据

```javascript
await crud.send({
    method: "object.create",
    array: "users",
    storage: [
        "mongodb",
        "sqlite"
    ],
    object: [{
        name: "John Doe",
        email: "john@example.com"
    }]
});
```

何时 `storage` 是一个阵列,同一有效载荷在每一个匹配的存储提供者之间平行执行。 这使得应用程序可以使用一个单一的CRUD请求对多个数据库的数据进行同步.

* * *

### 更新数据

```javascript
await crud.send({
    method: "object.update",
    array: "users",
    storage: [
        "mongodb",
        "sqlite"
    ],
    object: [{
        _id: "64b9a32e18f21bc56789abcd",
        status: "active"
    }]
});
```

* * *

### 删除数据

```javascript
await crud.send({
    method: "object.delete",
    array: "users",
    storage: "mongodb",
    object: [{
        _id: "64b9a32e18f21bc56789abcd"
    }]
});
```

* * *

## 如何运作

1.  CRUD的每一项请求均被表述为标准有效载荷物体.
2.  客户端决定由哪个存储提供者处理请求.
3.  本地供应商立即执行快速应用响应.
4.  远程提供者通过活动 Coreate 通信层传输请求.
5.  当指定多个存储提供者时,操作会同时执行.
6.  无论数据库技术如何,答复都趋于一致.
7.  离线突变在恢复连接后自动排队并同步.

* * *

## 结构和有效载荷光谱

### 统一有效载荷对象Schema

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `method` | `String` | CRUD 操作 (`object.create`, (中文(简体) ), `object.read`, (中文(简体) ), `object.update`, (中文(简体) ), `object.delete`, (中文(简体) ), `array.read`(见a/c.5/49/70,附件). |
| `array` | `String` | 收集、表格或数据集名称. |
| `object` | `Array<Object>` | 要创建、更新或删除的文档. |
| `storage` | `String | Array<String>` | 目标存储提供者。 当提供数组时,所有匹配的提供者都会平行执行请求. |
| `filter` | `Object` | 查询过滤器、限制、排序、索引、预测和搜索标准. |
| `organization_id` | `String` | 多租户工作空间标识符. |

* * *

## 离线同步

CRUD客户端采用离线先行执行模式.

无法连接时 :

-   阅读继续使用本地存储提供者.
-   写作在当地进行.
-   待发突变自动排队.
-   连接返回时同步排队操作 .
-   应用程序仍然具有响应性,而不需要不断联网.

* * *

## 储存供应商

这个 `storage` 属性决定 CRUD 操作在哪里执行 .

存储可能参考配置的提供者, 如MongoDB, SQLite, IndexedDB, PostgreSQL, 或任何自定义适配器 .

```javascript
storage: "primary"
```

存储名是由您的应用程序配置定义的别名 .

多个存储提供者可以同时被锁定.

```javascript
storage: [
    "primary",
    "backup",
    "analytics"
]
```

或者说

```javascript
storage: [
    "mongodb",
    "sqlite"
]
```

当提供一系列存储提供者时,CRUD客户端在每一个匹配的提供者之间同时执行同样的操作,允许应用程序在多个数据库之间保持同步数据,同时有一个请求.

* * *

## 通知

发布笔记,新功能,突破变化,并发布迁移指南在项目的"CHangGELOG"和"GitHub"发布会上.

* * *

## 路线图

即将作出的改进包括:

-   CRDT 基于冲突的解决
-   背景同步工人
-   三角洲同步
-   交易分批
-   图表查询支持
-   可插式存储适配器
-   边缘同步
-   高级解决冲突战略

* * *

## 如何贡献

我们鼓励为我们的图书馆捐款(你甚至可能得分不少)。 请看我们的 **捐款额** 详细指南。 我们希望这个图书馆 由社区驱动和创造者主导.

通过创建问题、提交拉动请求、审查现有讨论或参与专题请求,帮助确定发展的优先次序.

* * *

## 许可证

该软件在GNU Affero通用公共许可证版本3(AGPLv3)和商业许可证下获得双许可证.

-   **开源使用 :** 对于开源项目和非商业用途,该软件可在AGPLv3下提供. 许可证全文见LICENSE文件.
-   **商业用途:** 商业组织如果打算在AGPL要求之外使用这种软件,必须通过Coreate取得商业许可证.

## 常见问题

### @cocreate/crud-client 是什么？

一个高性能,多租借的CRUD客户端,用于CoCreate\. 使用统一的API执行创建,读取,更新,删除,并针对一个或多个存储提供者进行实时同步操作\. 支持各种数据库的并行持久性,例如:

### 如何安装 @cocreate/crud-client？

在项目目录运行 npm install @cocreate/crud-client，或使用 pnpm add / yarn add / bun add。

### @cocreate/crud-client 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cocreate\_\_crud-client 是否存在。

### @cocreate/crud-client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cocreate/crud-client 可以商用吗？

@cocreate/crud-client 使用 AGPL-3\.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @cocreate/crud-client 的下载量有多少？

根据 npm 官方下载统计，@cocreate/crud-client 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,191 次，日均约 106 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cocreate/crud-client 还在维护吗？

最新版本 2\.0\.1 发布于 2026/11/06（4 天前）；至今共发布 337 个版本，其中过去 12 个月发布了 12 个；首次发布于 2021/04/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。