vtex-io-masterdata-strategy

主数据策略

何时使用此技能

在判断 Master Data v2 是否适合用作 VTEX IO 应用中的自定义数据存储机制时，请使用此技能。

• 为评价、愿望清单、表单或自定义应用记录建模
• 选择实体边界
• 规划架构索引和生命周期
• 审查长期 Master Data 设计

以下情况请勿使用此技能：

• 低层级客户端使用细节
• 运行时或路由结构
• 应用设置架构
• 前端 UI 行为

决策规则

• 只有在 Master Data 已成为值得认真考虑的存储机制时，才使用此技能。如需了解 Master Data、VBase、VTEX 核心 API 和外部存储之间的更广泛选择，请使用 vtex-io-data-access-patterns。
• 对需要验证、索引和查询支持的结构化自定义数据，请使用 Master Data。
• 当此应用引入新的业务实体、拥有数据模型，并希望将架构作为应用契约的一部分来创建和版本化时，请使用 masterdata builder。
• 如果实体和架构已经存在且由共享或集中管理，而此应用只需读取或写入记录，无需重新定义架构本身，则优先只使用 Master Data 客户端。
• 对于由应用拥有但不应在每个应用版本中重新创建或更新的稳定架构，请将架构定义保留在代码中，并在受控的设置流程中使用 Master Data 客户端，仅在需要时创建或更新架构。
• 请记住，Master Data 实体的作用范围是账户级别。更改共享实体或架构会影响该账户中依赖它的所有应用，因此，如果架构由集中管理，请优先仅通过客户端使用。
• 有意划分实体边界，并使其与所存储的业务概念保持一致。
• 为实际用于筛选和搜索的字段建立索引。
• 明确规划架构生命周期，以避免架构泛滥。
• 从一开始就考虑数据量和保留期限。如果数据集将无限增长，且没有保留或归档策略，Master Data 很可能不是合适的存储机制。
• 不要把 Master Data 当作可无限扩展的任意数据载体。
• 不要将 Master Data 用作高吞吐量、仅追加数据的无限日志或事件存储。如果主要需求是保留原始历史记录，而非结构化查询，请优先使用专用日志记录或存储机制。
• 不要在 Master Data 中存储机密、凭据或全局应用配置。请改用应用设置或配置应用。
• 不要为每个账户、工作区或功能标志生成一个实体或架构。请保持实体名称稳定，并在必要时通过记录字段区分租户或环境。
• 通过 masterdata builder 将架构演进直接与应用版本绑定时务必谨慎。频繁的架构变更与应用发布耦合，可能导致过多的架构更新、索引变更和长期架构泛滥。

在 masterdata 构建器与 Master Data 客户端之间进行选择

VTEX IO 应用使用 Master Data 的主要方式有三种：

• 通过 masterdata 构建器拥有架构：

  • 应用在代码库的 masterdata/ 目录下声明实体和架构。
  • 架构字段、验证和索引随应用代码一同演进。
  • 当应用是数据模型的主要所有者、架构变更相对不频繁，且架构应作为应用契约的一部分推出时，使用此方式。

• 仅通过 Master Data 客户端使用现有架构：

  • 应用使用 Master Data 客户端，但不通过 masterdata 构建器声明实体或架构。
  • 应用假定架构由其他地方管理且稳定，并且只读取或写入符合该契约的记录。
  • 当实体由多个应用共享或由中央统一管理，且此应用不应在不同环境中重新定义或拆分架构时，使用此方式。

• 在代码中拥有稳定的架构定义，并通过客户端应用：

  • 应用在代码中保留稳定的架构定义，而不是使用 masterdata/ 构建器文件。
  • 受控的设置流程会检查架构是否存在，并且仅在必要时创建或更新架构。
  • 当应用确实拥有该架构，但不应将架构推出与每个应用版本或每个发布管道步骤绑定时，使用此方式。

硬性约束

约束：Master Data 实体必须有明确的架构边界

每个实体都必须代表清晰的业务概念，其架构必须符合预期用途。

原因

实体边界不明确会导致查询混乱、索引选择不佳和架构漂移。

检测

如果一个实体混合了不相关的概念，或存储了许多彼此无关的记录形态，请停止并拆分设计。

正确

{
  "title": "review-schema-v1",
  "type": "object",
  "properties": {
    "productId": { "type": "string" },
    "userId": { "type": "string" },
    "rating": { "type": "number" },
    "approved": { "type": "boolean" }
  },
  "required": ["productId", "userId", "rating"],
  "v-indexed": ["productId", "userId", "approved"]
}

错误

{
  "title": "everything-schema",
  "type": "object"
}

约束：索引字段必须符合实际查询行为

用于筛选或查找的字段必须经过有意的索引设计。

原因

缺少索引会导致查询行为不佳，并带来不必要的运维风险。

检测

如果查询依赖的字段未纳入索引策略，请停止并协调架构与访问模式。

正确

{
  "v-indexed": ["productId", "approved"]
}

错误

{
  "v-indexed": []
}

约束：必须明确管理架构生命周期

规划 Master Data 架构演进时，必须考虑清理和版本管理。

原因

架构在缺乏管理的情况下不断扩展，会造成长期运维负担，并可能触及平台限制。

检测

如果添加架构版本时没有生命周期或清理计划，请停止并制定计划。

正确

review-schema-v1 -> review-schema-v2 with cleanup plan

错误

review-schema-v1, v2, v3, v4, v5 with no cleanup strategy

请记住，更改索引字段或字段类型可能会影响现有文档的索引和查询方式。当架构演进与频繁的应用版本变更绑定时，这种风险会增加。

约束：实体和架构名称必须在不同环境中保持稳定

实体名称和架构标识符在不同账号、工作区和环境中都必须保持稳定。不要将账号名称、工作区或发布标记编码到实体或架构名称中。

原因

按账号或工作区命名架构会导致架构泛滥、生命周期管理更加困难，并带来之后难以清理的运维限制。

检测

如果设计提议为每个工作区、账号或环境分别创建实体或架构，请停止并重新设计，改用稳定名称和带作用域的字段或记录。

正确

review-schema-v1
RV

错误

review-schema-brazil-master
RV_US_MASTER

如果有明确计划保持开发环境和生产环境的架构同步，分别使用一个统一管理的架构是可以接受的。避免按工作区、账号或功能标记生成架构名称。

首选模式

对于结构化自定义记录，使用 Master Data；只为需要查询的字段建立索引，并有计划地进行架构演进。

示例：应用通过 masterdata 构建器管理架构

• masterdata/review-schema-v1.json 声明 RV 实体的架构和索引。
• 然后，应用使用专用的 Master Data 客户端创建和查询 RV 文档。

{
  "title": "review-schema-v1",
  "v-entity": "RV",
  "type": "object",
  "properties": {
    "productId": { "type": "string" },
    "userId": { "type": "string" },
    "rating": { "type": "number" },
    "approved": { "type": "boolean" }
  },
  "required": ["productId", "userId", "rating"],
  "v-indexed": ["productId", "userId", "approved"]
}

示例：应用仅通过客户端使用现有架构

• 此应用不声明任何 masterdata 构建器文件。
• 它使用 Master Data 客户端访问由其他位置管理的现有稳定 RV 实体。

await ctx.clients.masterdata.createDocument({
  dataEntity: 'RV',
  fields: {
    productId,
    userId,
    rating,
    approved: false,
  },
})

示例：应用在代码中管理稳定架构，并通过客户端确保其存在

• 应用在代码中保留稳定的架构定义。
• 通过受控的设置流程确保架构存在，而不是每次发布都依赖 masterdata 构建器。

const schema = {
  title: 'review-schema-v1',
  'v-entity': 'RV',
}

const existing = await ctx.clients.masterdata.getSchema('review-schema-v1')

if (!existing) {
  await ctx.clients.masterdata.createOrUpdateSchema('review-schema-v1', schema)
}

常见失败模式

• 创建范围过广的实体。
• 查询未建立索引的字段。
• 不制定生命周期计划，导致架构版本不断累积。
• 将 Master Data 用作高容量日志或事件接收端，却没有保留或归档策略。
• 将配置、密钥或跨应用共享设置存储在 Master Data 中，而不是使用专门的配置机制。
• 创建按账户或工作区划分的实体，例如 RV_storeA_master，而不是使用带作用域记录字段的稳定实体（例如 RV）。
• 频繁更改架构，并让每个应用版本都依赖 masterdata 构建器，导致架构更新过多，并随着时间推移产生索引副作用。

审核清单

• 对于此用例，Master Data 是合适的存储机制吗？
• 此应用应通过 masterdata 构建器管理架构，还是仅通过客户端使用现有的稳定架构？
• 与每个应用版本的发布流程耦合相比，在代码中定义稳定架构并采用受控的设置流程是否更安全？
• 每个实体是否代表明确的业务概念？
• 实体名称和架构名称在各个工作区和账户中是否保持稳定？
• 是否有意为需要筛选的字段建立索引？
• 是否制定了架构生命周期计划？
• 如果开发和生产环境使用不同的架构，是否有明确计划使它们保持同步，同时避免架构泛滥？

相关技能

• vtex-io-data-access-patterns - 在为特定数据集选择 Master Data、VBase、VTEX 核心 API 或外部存储时使用

参考资料

• Master Data - 平台数据存储背景