Skip to Content
文档Entityengine数据源与API数据源概览

数据源概览

Entity Engine 的数据源系统是您与数据交互的核心组件，它提供了统一的数据访问接口，让您可以轻松地查询、创建、更新和删除数据。数据源系统基于 TRPC 协议，确保类型安全的远程调用和实时数据同步。

什么是数据源

数据源（DataSource）是 Entity Engine 中负责数据操作的核心服务。它抽象了底层数据存储的复杂性，为您提供简洁统一的 API 接口。无论您的数据存储在数据库、API 服务还是其他存储系统中，数据源都能提供一致的访问方式。

核心特性

  • 统一接口：提供标准化的 CRUD 操作方法
  • 类型安全：基于 TypeScript，确保编译时类型检查
  • 关系管理：支持对象间引用关系的创建和管理
  • 高级查询：支持复杂条件查询、分组统计和树形数据处理
  • React 集成：无缝集成 React Hooks，简化状态管理

获取数据源实例

在使用数据源之前，您需要通过引擎实例获取数据源对象。Entity Engine 提供了两种获取方式：

在 React 组件中使用

在 React 组件中，推荐使用 useEntityEngine Hook 来获取引擎实例，然后通过数据源工厂获取数据源：

import { useEntityEngine } from '@scenemesh/entity-engine';
 
const MyComponent = () => {
  const engine = useEntityEngine();
  const dataSource = engine.datasourceFactory.getDataSource();
  
  // 现在可以使用 dataSource 进行数据操作
};

在非 React 环境中使用

如果您在服务端代码或非 React 环境中使用，可以直接导入引擎实例：

import { engine } from '@scenemesh/entity-engine';
 
const dataSource = engine.datasourceFactory.getDataSource();

转换为 React Hooks

为了更好地与 React 生态系统集成，Entity Engine 提供了 toDataSourceHook 工具函数，可以将数据源方法转换为 React Hooks：

import { toDataSourceHook } from '@scenemesh/entity-engine';
 
const dataSourceHooks = toDataSourceHook(dataSource);

转换后，您就可以使用熟悉的 Hook 模式来处理数据操作，包括自动的加载状态管理、错误处理和数据缓存。

基本数据操作

数据源提供了完整的 CRUD（创建、读取、更新、删除）操作方法。每个操作都支持丰富的参数配置，以满足不同的业务需求。

查询数据

数据源提供了多种查询方法来获取数据：

查询单个对象：使用 findOne 方法通过 ID 查询特定对象，或使用 findOneWithReferences 方法查询包含关联数据的对象。

查询多个对象：使用 findMany 方法进行列表查询，支持分页、排序、过滤等参数。这是最常用的数据查询方法。

统计查询：使用 findCount 方法获取符合条件的记录数量，适用于分页显示和数据统计场景。

创建数据

使用 create 方法创建新的数据对象。创建时可以同时建立与其他对象的引用关系，通过 reference 参数指定父子关系。

更新数据

数据源提供两种更新方式：update 方法用于更新完整的对象数据，updateValues 方法用于仅更新特定字段的值。根据您的业务需求选择合适的更新方式。

删除数据

支持单个删除（delete 方法）和批量删除（deleteMany 方法）。删除操作会自动处理相关的引用关系清理。

高级查询功能

除了基础的 CRUD 操作，数据源还提供了强大的高级查询功能：

树形数据查询

使用 findTreeObjects 方法查询具有父子关系的树形结构数据。这对于组织架构、分类目录等场景非常有用。您只需指定模型名称和父级字段名，系统会自动构建完整的树形结构。

分组聚合查询

使用 findGroupedObjects 方法进行数据分组和聚合统计。支持多种聚合操作（求和、计数、平均值等），适用于报表统计和数据分析场景。

关联数据查询

使用 findManyWithReferences 方法查询包含关联数据的对象列表。这样可以在一次查询中获取主对象及其相关联的数据，减少网络请求次数。

引用关系管理

Entity Engine 支持对象间的引用关系管理，让您可以建立和维护复杂的数据关联：

查询引用关系

使用 findReferences 方法查询对象的引用关系，了解对象间的关联情况。

创建引用关系

使用 createReference 方法在两个对象间建立引用关系。需要指定源对象、目标对象以及引用字段名称。

删除引用关系

支持删除单个引用（deleteReference）或批量删除引用（deleteReferences）。这在对象关系变更时非常有用。

查询条件构建

数据源支持丰富的查询条件构建，帮助您精确筛选所需数据：

基础操作符

支持等于、不等于、大于、小于、包含、范围查询等多种操作符。您可以根据字段类型选择合适的操作符进行查询。

复合条件

支持使用 and 和 or 操作符构建复杂的查询条件。可以嵌套多层条件，实现精确的数据筛选。

排序和分页

通过 sortBy 参数设置排序规则，支持多字段排序。使用 pageSize 和 pageIndex 参数实现分页查询，确保良好的性能表现。

React Hooks 集成

Entity Engine 与 React 生态系统深度集成，提供了完整的 Hooks 支持：

查询 Hooks

转换后的数据源 Hooks 提供了 useFindMany、useFindOne 等查询方法，自动处理加载状态、错误状态和数据缓存。

操作 Hooks

提供 useCreate、useUpdate、useDelete 等操作 Hooks，支持乐观更新和自动重新获取数据。

状态管理

所有 Hooks 都遵循 React Query 的最佳实践，提供了 loading、error、data 等状态，以及 refetch、mutate 等操作方法。

配置和验证

配置查询

使用 findPlainConfig 方法获取模型和视图的配置信息。这有助于动态构建用户界面和验证数据结构。

数据验证

使用 validate 方法验证数据格式是否符合模型定义。在数据提交前进行验证，可以及早发现并处理数据问题。

实际应用场景

数据源系统适用于各种实际业务场景：

商品管理系统：查询商品列表、创建新商品、更新库存信息、删除下架商品。支持按分类、价格、状态等条件筛选。

用户管理系统：用户信息的增删改查、用户角色关系管理、用户行为统计分析。

组织架构管理：树形组织结构的查询和维护、部门人员关系管理、权限继承处理。

内容管理系统：文章的发布管理、分类组织、标签关联、评论系统。

最佳实践建议

性能优化

  1. 合理使用分页：对于大数据集，始终使用分页参数避免性能问题
  2. 精确查询条件：构建精确的过滤条件，减少不必要的数据传输
  3. 缓存策略：对于频繁查询的数据，使用适当的缓存策略

错误处理

  1. 完善错误处理：始终处理查询和操作中可能出现的错误
  2. 用户友好提示：为用户提供清晰的错误信息和操作指引
  3. 重试机制：在网络不稳定的情况下提供重试功能

数据安全

  1. 权限验证：在数据操作前进行适当的权限检查
  2. 数据验证：使用内置的验证功能确保数据质量
  3. 敏感信息处理：避免在客户端暴露敏感数据

Entity Engine 的数据源系统为您提供了强大而灵活的数据访问能力。通过合理使用这些功能，您可以构建高效、稳定、用户友好的数据驱动应用。记住始终关注性能优化、错误处理和用户体验，这将帮助您创建更好的应用程序。

Last updated on
数据源概览添加字段类型