ATKONBASE

外观

字段值编码契约 ​

目标：说清元数据字段值按类型如何编码，以及 null 的语义为什么不唯一。这是读写 metadata、消费 schema 导出前必须先懂的静态契约。

不在本篇范围：按字段筛选、跨资源类型联合查询、字段定义的增删改等动态用法——那些属于元数据模式篇与接口参考。

一、字段值按类型编码 ​

每个字段定义带两个决定编码形态的属性：

  • valueType：值类型——STRING / INTEGER / DECIMAL / BOOLEAN / DATE / DATETIME。
  • cardinality：基数——SINGLE（单值）/ MULTI（多值）。

字段值（包括 metadata 实际值、字段定义里的 defaultValue）对 ATKONBASE 是透明字符串——平台不解释、不校验、不转换，由消费方按 valueType + cardinality 解析。编码形态：

valueTypecardinality编码形态示例
STRINGSINGLE字符串原文直存engineering
INTEGERSINGLE十进制整数字符串123、-7
DECIMALSINGLE十进制小数字符串（不带千分隔）3.14、-0.5
BOOLEANSINGLE字符串 true / falsetrue
DATESINGLEISO 8601 日期（不带时间）2026-05-23
DATETIMESINGLEISO 8601 日期时间（带时区）2026-05-23T10:00:00+08:00
任意MULTIJSON 数组字符串，元素按对应 SINGLE 规则编码["a","b"]、[1,2,3]

⚠️ 必须按 valueType + cardinality 选择解析策略。若一律按字符串处理（不区分类型），会在 MULTI / INTEGER / DECIMAL 等场景出错。

校验规则的编码 ​

字段定义里的 validationRule 也是字符串，按 valueType 编码：

valueType编码形态示例
STRING正则表达式字符串^[A-Z]{3}[0-9]{4}$
INTEGER / DECIMALJSON 对象字符串描述上下界{"min":0,"max":100}
DATE / DATETIMEJSON 对象字符串描述时间区间{"after":"2020-01-01"}
BOOLEAN通常无校验（必填走 required 字段）（null）
任意 + MULTIJSON 数组 / 对象描述元素或数量约束按字段定义

二、dataType 与 valueType 是同一套枚举 ​

同一套类型枚举，在不同位置字段名不同——请勿混用：

  • 读 metadata 值时，响应项里的类型字段名是 dataType（如入门篇示例中的 "dataType": "STRING"）。
  • 看 schema 定义时，字段定义里的类型字段名是 valueType。

两者取值集合完全相同（STRING / INTEGER / DECIMAL / BOOLEAN / DATE / DATETIME），只是出现位置不同。

三、null 的语义不唯一 ​

null 不是单一含义——同样是 null，在不同字段上表达不同的契约语义。没有「null 一律视为未设置」这样的统一规则；必须按字段判定。常见可归为三类：

语义类别含义典型字段
结构语义null 表示一种结构状态内容类型的 parentTypeId：null = 根类型（无父）
策略语义null 表示「不限 / 不约束」maxVersionCount：null = 不限版本数（正整数 = 保留最近 N 个）；retentionDays：null = 不限天数
缺省语义null 表示「无 / 未设置」defaultValue：null = 无默认值；validationRule：null = 无校验规则；termSetCode：null = 非词表字段

反例：若强行用单一规则（如「null 一律视为未设置」）会失真——例如 maxVersionCount 的 null 表示主动不限而非未设置。

metadata 值层面的「未设置」 ​

对一个具体文档的 metadata：某字段从未写入时，/v1/metadata/values/get 返回的列表里不出现该项（新上传、未挂任何值的文档可能返回空列表）。「列表里没有」与「列表里有但值为 null」是两种不同状态，集成方解析时需区分。

四、新增枚举取值的容忍 ​

平台未来可能新增 valueType 等枚举取值。消费方应对未知取值保持向前兼容——遇到尚未识别的枚举值不要直接报错，而是按业务需要降级处理（关键路径除外）。

下一步 ​