Skip to content

数据模型

目录

1. 概述

Yao 数据模型是应用的核心组件,它使系统能够:

  • 自动数据迁移:根据模型定义创建和更新数据库表结构
  • 元数据原子操作:提供标准化的数据操作方法
  • 数据校验:基于模型定义进行输入数据的合法性验证
  • 自动管理后台:生成数据管理界面

数据模型将操作方法映射为处理器(process),可在数据流(Flow)和接口(API)中直接调用。对于使用golang开发的业务插件,可通过Gou包访问模型方法。

2. 命名规范

数据模型使用小写英文字母命名的JSON文件:<name>.mod.json

文件位置文件名模型名称处理器调用方式
/name.mod.jsonnamemodels.name.<process>
/group/name.mod.jsongroup.namemodels.group.name.<process>
/group1/group2/name.mod.jsongroup1.group2.namemodels.group1.group2.name.<process>

3. 文档结构

数据模型定义文件包含以下主要部分:

json
{
  "name": "用户", // 模型中文名称
  "table": {}, // 数据表定义
  "columns": [], // 字段定义
  "indexes": [], // 索引定义
  "relations": {}, // 关系映射
  "values": [], // 默认数据
  "option": {} // 配置选项
}
字段类型说明必填
nameString模型中文名称
tableObject数据表定义
columnsArray<Object>字段定义
indexesArray<Object>索引定义
relations[key:String]:Object关系映射
valuesArray<Object>默认数据
optionObject配置选项

3.1 基础信息

基础信息用于描述模型的元数据,便于在开发平台中管理和检索。

json
{
  "name": "用户",
  "version": "1.0.0",
  "description": "网站用户元数据模型",
  "author": "开发者姓名",
  "email": "developer@example.com",
  "license": "MIT"
}
字段类型说明必填
nameString中文名称
versionString遵循语义化版本的版本号
descriptionString详细介绍
authorString作者
emailString联系方式
licenseString共享协议
homepageString官网
tunString象传智慧共享仓库地址,如microcity/petstore/user

3.2 数据表 table

定义模型对应的数据库表结构。

json
{
  "table": {
    "name": "user", // 表名
    "comment": "用户表", // 表注释
    "engine": "InnoDB" // 数据表引擎(MySQL)
  }
}
字段类型说明必填
nameString数据表名称
commentString数据表注释
engineString表引擎(MySQL),可选值:InnoDBMyISAM

3.3 字段定义 columns

字段定义包含模型的各个属性及其验证规则。

json
{
  "columns": [
    {
      "label": "ID",
      "name": "id",
      "type": "ID"
    },
    {
      "label": "用户名",
      "name": "username",
      "type": "string",
      "length": 50,
      "comment": "登录用户名",
      "nullable": false,
      "unique": true,
      "validations": [
        {
          "method": "typeof",
          "args": ["string"],
          "message": "用户名必须是字符串"
        },
        {
          "method": "minLength",
          "args": [3],
          "message": "用户名至少需要3个字符"
        }
      ]
    }
  ]
}

字段基本属性

字段类型说明必填
nameString字段名称
typeString字段类型
labelString显示名称
commentString字段注释
lengthInteger字段长度(适用于string等类型)
precisionInteger数值总位数(适用于float等)
scaleInteger小数位位数(适用于float等)
optionArray<String>枚举类型选项
default任意默认值
default_rawString原始默认值(支持SQL函数)
nullableBoolean是否可为空(默认false)
indexBoolean是否为索引(默认false)
uniqueBoolean是否为唯一索引(默认false)
primaryBoolean是否为主键(默认false)
cryptString加密方式,可选值:AESPASSWORD
validationsArray<Object>验证规则

字段类型对照表

类型说明参数MySQL对应类型
string字符串lengthVARCHAR(length)
text文本-TEXT
integer整型-INT
ID/id自增长整型-BIGINT UNSIGNED AUTO_INCREMENT
float浮点数precision, scaleFLOAT(precision,scale)
decimal精确小数precision, scaleDECIMAL(precision,scale)
boolean布尔型-BOOLEAN
enum枚举型optionENUM(option...)
date日期-DATE
datetime日期时间-DATETIME
timestamp时间戳-TIMESTAMP
json/JSONJSON数据-JSON

完整字段类型列表请参考文档后面的详细说明

数据验证规则

验证规则用于在数据创建和更新时检查字段值的合法性。

json
{
  "validations": [
    {
      "method": "typeof", // 验证方法
      "args": ["string"], // 方法参数
      "message": "必须是字符串" // 错误提示
    }
  ]
}
验证方法参数说明示例
typeof[类型]检查数据类型{"method":"typeof", "args":["integer"]}
min[最小值]最小值检查{"method":"min", "args":[0]}
max[最大值]最大值检查{"method":"max", "args":[100]}
enum[选项...]枚举值检查{"method":"enum", "args":["enabled","disabled"]}
pattern[正则表达式]正则匹配{"method":"pattern", "args":["^1[3-9]\\d{9}$"]}
minLength[长度]最小长度{"method":"minLength", "args":[6]}
maxLength[长度]最大长度{"method":"maxLength", "args":[18]}
email[]邮箱格式{"method":"email", "args":[]}
mobile[地区]手机号格式{"method":"mobile", "args":["cn"]}

错误消息支持模板变量:

  • - 用户输入的值
  • - 字段标签

字段加密

支持两种加密方式保护敏感数据:

加密方式说明可逆性
AESAES加密(需设置环境变量XIANG_DB_AESKEY)可逆
PASSWORD密码哈希加密不可逆

3.4 索引定义 indexes

索引用于提高查询性能和保证数据唯一性。

json
{
  "indexes": [
    {
      "name": "user_email_mobile_unique", // 索引名称
      "type": "unique", // 索引类型
      "columns": ["email", "mobile"], // 索引字段
      "comment": "用户邮箱和手机号唯一" // 索引说明
    }
  ]
}
字段类型说明必填
nameString索引名称(建议格式:字段1字段2..._索引类型)
typeString索引类型:indexuniqueprimaryfulltext
columnsArray<String>索引字段名称列表(顺序有关)
commentString索引注释

3.5 关系映射 relations

关系映射定义模型之间的关联关系,支持一对一、一对多、多对多等多种映射方式。

json
{
  "relations": {
    "profile": {
      // 关联名称
      "type": "hasOne", // 关系类型
      "model": "user_profile", // 关联模型
      "key": "user_id", // 关联模型的关联字段
      "foreign": "id", // 当前模型的关联字段
      "query": {
        // 默认查询参数
        "select": ["avatar", "bio"]
      }
    }
  }
}

关系类型

关系类型说明用途
hasOne一对一关系用户-资料、产品-详情
hasMany一对多关系用户-订单、文章-评论
hasOneThrough跨表一对一复杂的间接关联
hasManyThrough跨表一对多用户-角色-权限

关系定义字段

字段类型说明必填
typeString关系类型
modelString关联模型名称✓ (简单关系)
keyString关联模型关联字段✓ (简单关系)
foreignString当前模型关联字段✓ (简单关系)
queryObject默认查询参数
linksArray<Object>多表关联定义✓ (跨表关系)

实际应用示例

一对一关系(hasOne):

json
{
  "manu": {
    "type": "hasOne",
    "model": "manu",
    "key": "id",
    "foreign": "manu_id",
    "query": { "select": ["name", "short_name"] }
  }
}

一对多关系(hasMany):

json
{
  "addresses": {
    "type": "hasMany",
    "model": "address",
    "key": "user_id",
    "foreign": "id",
    "query": {
      "select": ["province", "city", "location"],
      "limit": 20
    }
  }
}

3.6 默认数据 values

定义模型的初始数据,在首次迁移时自动插入。

json
{
  "values": [
    {
      "name": "管理员",
      "email": "admin@example.com",
      "password": "Admin@123",
      "type": "admin",
      "status": "enabled"
    }
  ]
}

3.7 配置选项 option

定义模型的全局配置参数。

json
{
  "option": {
    "timestamps": true, // 自动添加时间戳字段
    "soft_deletes": true // 启用软删除
  }
}
选项类型说明
timestampsBoolean添加created_atupdated_at字段并自动维护
soft_deletesBoolean添加deleted_at字段实现软删除功能

4. 查询参数 QueryParam

查询参数用于在关系定义和API调用中描述数据过滤、排序和关联查询条件。

json
{
  "select": ["id", "name", "mobile"], // 查询字段
  "wheres": [
    // 查询条件
    { "column": "status", "value": "enabled" }
  ],
  "orders": [
    // 排序条件
    { "column": "id", "option": "desc" }
  ],
  "withs": {
    // 关联查询
    "profile": { "select": ["avatar"] }
  },
  "limit": 10, // 返回记录数
  "page": 1, // 页码
  "pagesize": 20 // 每页记录数
}

查询条件格式

json
{
  "wheres": [
    {
      "column": "status", // 字段名
      "value": "enabled", // 匹配值
      "op": "eq", // 操作符(可选,默认eq)
      "method": "where" // 方法(可选,默认where)
    },
    {
      "rel": "profile", // 关联模型名
      "column": "is_verified", // 关联模型字段
      "value": true
    },
    {
      "wheres": [
        // 分组条件(OR)
        { "column": "name", "value": "%张%", "op": "like" },
        { "method": "orwhere", "column": "name", "value": "%李%", "op": "like" }
      ]
    }
  ]
}

常用操作符

操作符说明SQL等价
eq等于(默认)field = value
like模糊匹配field LIKE value
gt大于field > value
ge大于等于field >= value
lt小于field < value
le小于等于field <= value
in包含field IN (values)
null为空field IS NULL
notnull不为空field IS NOT NULL

5. 处理器(process)

数据模型自动生成以下处理器,可在API和Flow中使用:

处理器调用方式功能
findmodels.模型名.find查询单条记录
getmodels.模型名.get按条件查询(不分页)
paginatemodels.模型名.paginate按条件查询(分页)
createmodels.模型名.create创建单条记录
updatemodels.模型名.update更新单条记录
savemodels.模型名.save保存记录(存在则更新,不存在则创建)
deletemodels.模型名.delete删除单条记录(软删除)
destroymodels.模型名.destroy删除单条记录(物理删除)
insertmodels.模型名.insert批量插入记录
updatewheremodels.模型名.updatewhere按条件更新记录
deletewheremodels.模型名.deletewhere按条件删除记录(软删除)
destroywheremodels.模型名.destroywhere按条件删除记录(物理删除)
eachsavemodels.模型名.eachsave批量保存记录

6. 完整示例

以下是一个完整的用户模型定义示例:

json
{
  "name": "用户",
  "table": {
    "name": "user",
    "comment": "用户信息表",
    "engine": "InnoDB"
  },
  "columns": [
    { "label": "ID", "name": "id", "type": "ID" },
    {
      "label": "用户名",
      "name": "username",
      "type": "string",
      "length": 50,
      "unique": true,
      "comment": "登录用户名",
      "validations": [
        {
          "method": "typeof",
          "args": ["string"],
          "message": "{{label}}必须是字符串"
        },
        {
          "method": "minLength",
          "args": [3],
          "message": "{{label}}长度至少为3个字符"
        }
      ]
    },
    {
      "label": "密码",
      "name": "password",
      "type": "string",
      "length": 256,
      "comment": "登录密码",
      "crypt": "PASSWORD",
      "validations": [
        {
          "method": "pattern",
          "args": [
            "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]{8,}$"
          ],
          "message": "{{label}}必须包含大小写字母、数字和特殊字符,且长度不少于8位"
        }
      ]
    },
    {
      "label": "状态",
      "name": "status",
      "type": "enum",
      "option": ["active", "inactive", "banned"],
      "default": "inactive",
      "comment": "用户状态",
      "index": true
    }
  ],
  "indexes": [
    {
      "name": "username_status_index",
      "comment": "用户名和状态联合索引",
      "columns": ["username", "status"],
      "type": "index"
    }
  ],
  "relations": {
    "profile": {
      "type": "hasOne",
      "model": "user_profile",
      "key": "user_id",
      "foreign": "id"
    },
    "orders": {
      "type": "hasMany",
      "model": "order",
      "key": "user_id",
      "foreign": "id",
      "query": { "limit": 10 }
    }
  },
  "values": [
    {
      "username": "admin",
      "password": "Admin@123",
      "status": "active"
    }
  ],
  "option": {
    "timestamps": true,
    "soft_deletes": true
  }
}