Skip to main content

Schema Resource

资源表是系统里“可以被引用、展示、管理、授权、审计”的核心对象表，例如 user、team、datasource、mcp_server、order、document、workflow。

tip

资源表的重点不是“字段越全越好”，而是让对象具备稳定身份、可追踪来源、可扩展元数据、可软删除、可做权限和审计。

命名​

  • 表名推荐单数：account、document、datasource_def。
  • 部分保留词或约定俗成可用复数或前缀：users、groups、app_user。
  • 字段尽量不用缩写：created_at 优于 ctime。
  • 外部来源字段建议使用明确前缀：source_type、source_id、external_id。
  • 面向用户的名字与系统名字分离：
    • name：稳定 key，可用于路径/引用。
    • title：展示名，可变。
    • description：描述。

基础字段​

常见资源表字段：

column说明
id主键，推荐 type-prefixed UUIDv7/ULID
uidUUID，适合跨系统关联或暴露
sid租户/业务维度自增编号，用户友好
tenant_id / tid租户 ID，多租户系统需要
name稳定名称/唯一 key
title展示名
description描述
created_at创建时间
updated_at更新时间
deleted_at软删除时间
version乐观锁/配置版本

来源字段​

用于导入、同步、对账、跨系统关联：

column说明
source_type来源系统，例如 github、stripe、platform
source_id来源系统对象 ID
source_name来源系统对象名称，可选
source_updated_at来源系统更新时间
imported_at本系统导入/同步时间
raw外部原始数据，通常 json/jsonb

建议：

unique (source_type, source_id)

如果是多租户：

unique (tenant_id, source_type, source_id)

扩展字段​

column读写方用途
metadata服务端/客户端均可读补充说明，不应成为强业务依赖
attributes客户端可写用户自定义属性
properties服务端写、客户端读服务端计算/托管属性
extensions内部使用不对外暴露的扩展数据
raw外部导入原始外部数据
warning

不要把关键业务状态藏在 metadata。如果需要查询、索引、授权或稳定约束，应提升为明确字段。

示例​

PostgreSQL：

create table datasource_def (
  id text primary key default ('dsd_' || replace(gen_random_uuid()::text, '-', '')),
  uid uuid not null default gen_random_uuid(),
  name text not null,
  title text,
  description text,

  source_type text,
  source_id text,
  source_updated_at timestamptz,
  imported_at timestamptz,

  metadata jsonb,
  attributes jsonb,
  properties jsonb,
  extensions jsonb,
  raw jsonb,

  version bigint not null default 1,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now(),
  deleted_at timestamptz,

  unique (name),
  unique (uid)
);

MySQL：

create table datasource_def (
  id varchar(64) not null primary key,
  name varchar(128) not null,
  title text,
  description text,
  metadata json,
  attributes json,
  properties json,
  version bigint not null default 1,
  created_at datetime(3) not null default current_timestamp(3),
  updated_at datetime(3) not null default current_timestamp(3) on update current_timestamp(3),
  deleted_at datetime(3) null,
  unique key uk_datasource_def_name (name),
  key idx_datasource_def_deleted_at (deleted_at)
);

索引建议​

  • 主键：id。
  • 唯一业务键：name、slug、source_type + source_id。
  • 常用过滤：tenant_id、deleted_at、created_at、updated_at。
  • 标签/JSON：PG 可用 jsonb GIN 或 text[] GIN；MySQL JSON 查询要谨慎。
  • 软删除唯一约束：PG 可用 partial unique index；MySQL 通常需要应用层约束或 generated column。

表分类​

类型示例常见字段
主要资源表user、document、mcp_serverid/name/title/owner/status/audit fields
关联表group_member、resource_label两端 ID、role、created_at
事件/日志表audit_log、request_logappend-only、trace/request/action fields
快照/读模型model_snapshot、pricing_viewsource/imported_at/raw
系统配置表setting、feature_flagkey/value/version

Wode 实践参考​

历史 Wode schema 大量使用统一资源字段：

id text not null default '<tag>_' || public.gen_ulid() primary key,
uid uuid not null default gen_random_uuid() unique,
tid text not null default public.current_tenant_id(),
eid text,
attributes jsonb not null default '{}',
properties jsonb not null default '{}',
extensions jsonb not null default '{}'

并按 (tid, eid) 做导入关联唯一约束。详见 Schema Wode Practice。

相关​