值类型与约束

基础类型管形状，值类型管含义

上一节的共享属性，让多个类型共用一份属性定义。这一节的值类型再进一步：让多个属性共用同一条取值规则。

string 只说「这是一段文字」。但订单状态不是随便一段文字，它只能是 draft、confirmed、inProduction、shipped、closed、cancelled 六个值之一。值类型（Value Type）就是给基础类型加上含义和规则：一个基础类型，加上元数据，再加上约束。

规则写进类型，用到它的每个属性和 Action 参数就都会在写入时被检查，不用在每个应用里各写一遍校验。下面定义两个值类型：订单状态，和订单号的格式。

[
  {
    "kind": "valueType",
    "apiName": "orderStatus",
    "title": "Order status",
    "description": "Where a sales order is in its life.",
    "schema": {
      "baseType": "string",
      "constraints": [
        { "type": "enum", "options": ["draft", "confirmed", "inProduction", "shipped", "closed", "cancelled"] }
      ],
      "version": "1.0.0"
    }
  },
  {
    "kind": "valueType",
    "apiName": "orderNumber",
    "title": "Order number",
    "schema": {
      "baseType": "string",
      "constraints": [ { "type": "regex", "pattern": "SO-[0-9]{4}-[0-9]{4}" } ],
      "version": "1.0.0"
    }
  }
]

属性用 valueType 引用它。salesOrder 的两个属性这样写：

{ "name": "orderNo", "type": "string", "primaryKey": true, "valueType": "orderNumber" }
{ "name": "status", "type": "string", "title": "Status", "valueType": "orderStatus" }

值类型还能在多个属性之间复用。salesOrder.totalUsd、customer.creditLimitUsd、product.standardCostUsd 都是金额，都不该是负数：写一个 usdAmount（decimal，range 的最小值为 0），三个属性都引用它就行。

八种约束

两个容易误会的地方。一是 regex 缺省要匹配整个字符串，只有打开 partialMatch，前面多出一个字母的「XSO-2026-0412」才可能混进来，而这多半不是你想要的。二是值类型只看一个值本身：「承诺交期不早于订单日期」要比较两个属性，那是 Action 提交条件的事，不是值类型的活。

一个值类型最多带 10 个约束。它的基础类型只能是 string、integer、long、short、byte、boolean、float、double、decimal、date、timestamp、array、struct；geopoint、vector 这类特殊类型套不了值类型。

版本与写入时校验

值类型有版本号，写在 version 里，缺省是 1.0.0。显示名、说明和 API name 随时能改；基础类型和约束属于这个版本，改约束就要升版本。改动分两种：

• 兼容的改动：给 customerTier 加一个选项 partner。已有的数据仍然合规，升版本后，用到它的属性和 Action 都按新规则检查。
• 破坏性的改动：删一个选项，或把范围收窄。已有的数据可能不再合规，用到它的地方会出错。已经有人在用时，稳妥的做法是弃用旧的、新建一个，再逐个迁过去。

常犯的错是把经常增减的分类写成 enum。每加一个选项要升一次版本，删一个更是破坏性改动。公司的部门有几十个、年年调整，更适合建成对象类型 department，用关系连起来；customerTier 这种三五个、几乎不变的取值，才适合 enum。

判断的办法是问一句：这个分类一年里会变几次？会变很多次，就别写进类型里。

给已有数据的属性套约束之前，先查一遍现有的值，再试跑：

aidc semantic sql 'SELECT status, count(*) FROM "salesOrder" GROUP BY 1'
aidc semantic define value-types.json --dry-run
aidc semantic value-types

下一节讲派生属性：不存下来，读的时候沿关系算出来的属性。