ApiHug
Changelog

规范/Domain

规范

数据库指令规范

ApiHug persistence 扩展使用手册

Maven Central version badge for com.apihug/it-bom

将 proto message 映射为数据库实体、DDL 与持久化元数据。

  • 扩展包: apihug/protobuf/domain/persistence.proto + annotations.proto
  • 作用范围: message（表）与 field（列）
  • 场景: JPA 实体、DDL、Liquibase、视图建模

导入

Proto
import "apihug/protobuf/domain/annotations.proto";

annotations.proto 会引入 persistence.proto。文档上不应再把它写成依赖 extend/common.proto。

基本结构

表级定义

Proto
message Category {
  option (hope.persistence.table) = {
    name: "CATEGORY";
    description: "宠物分类";
    wires: [IDENTIFIABLE];
  };
}

列级定义

Proto
string name = 1 [(hope.persistence.column) = {
  name: "NAME";
  description: "分类名称";
  nullable: false;
  length: 32;
  unique: true;
  type: VARCHAR;
}];

关键规则

1. 布尔值用 true / false

不要再使用 TRUE / FALSE 这类旧写法。

Proto
nullable: false;
unique: true;
insertable: false;
updatable: false;
searchable: true;
sortable: true;

2. 数值字段直接写标量

不要再使用旧的包装写法：

Proto
length: 32;
precision: 10;
scale: 2;

而不是：

Proto
length: {value: 32}
precision: {value: 10}

3. wires 负责通用字段

Wire作用
IDENTIFIABLE主键字段
AUDITABLE创建/更新时间与创建/更新人
DELETABLE逻辑删除字段
TENANTABLE租户字段
VERSIONABLE乐观锁版本字段
ALL启用全部通用能力
NONE完全自定义

示例：

Proto
option (hope.persistence.table) = {
  name: "PET";
  description: "宠物";
  wires: [IDENTIFIABLE, AUDITABLE, DELETABLE];
};

常用列配置

字段类型说明
namestring列名
descriptionstring业务说明
nullablebool是否允许 NULL
uniquebool是否唯一
insertablebool是否参与插入
updatablebool是否参与更新
searchablebool是否允许查询
sortablebool是否允许排序
typeColumn.Type显式 SQL 类型
lengthuint32字符串长度
precisionuint32DECIMAL 总位数
scaleuint32DECIMAL 小数位数
default_valuestring默认值
transientbool非持久化字段

SQL 类型

常用 Column.Type 包括：

  • VARCHAR
  • CHAR
  • INTEGER
  • BIGINT
  • DOUBLE
  • DECIMAL
  • DATE
  • TIME
  • TIMESTAMP
  • BOOLEAN
  • BLOB
  • CLOB
  • TIME_WITH_TIMEZONE
  • TIMESTAMP_WITH_TIMEZONE
  • ROWID

如果你要表达时区时间或数据库特定行标识，应优先使用这些已经存在的枚举，而不是自己发明兼容写法。

主键与生成策略

Proto
int64 id = 1 [(hope.persistence.column) = {
  name: "ID";
  id: true;
  nullable: false;
  generated_value: {
    strategy: UUID;
  };
}];

常见策略：

  • AUTO
  • TABLE
  • SEQUENCE
  • IDENTITY
  • UUID

枚举映射

Proto
com.example.pet.enumeration.Size size = 4 [(hope.persistence.column) = {
  name: "SIZE";
  nullable: false;
  enum_type: STRING;
  type: VARCHAR;
  length: 32;
}];

推荐：

  • STRING
  • CODE

不推荐继续使用旧式位置型映射思路。

完整示例

Proto
message Pet {
  option (hope.persistence.table) = {
    name: "PET";
    description: "宠物信息表";
    wires: [IDENTIFIABLE, AUDITABLE, DELETABLE];
  };

  string name = 1 [(hope.persistence.column) = {
    name: "NAME";
    description: "宠物名称";
    nullable: false;
    length: 32;
    type: VARCHAR;
  }];

  string category = 2 [(hope.persistence.column) = {
    name: "CATEGORY";
    description: "宠物分类";
    nullable: false;
    length: 32;
    type: VARCHAR;
  }];

  double weight = 3 [(hope.persistence.column) = {
    name: "WEIGHT";
    description: "宠物体重";
    nullable: false;
    type: DOUBLE;
  }];

  double price = 4 [(hope.persistence.column) = {
    name: "PRICE";
    description: "售价";
    nullable: false;
    type: DECIMAL;
    precision: 10;
    scale: 2;
  }];
}

视图与 Liquibase

当实体需要列表视图、详情视图或数据库定制 SQL 时，再使用：

  • views
  • liquibase

这些能力是高级建模能力，不建议在基础实体阶段滥用。

最佳实践

  • 表名、列名统一使用大写下划线风格
  • 通用字段优先走 wires
  • 布尔值用小写 true / false
  • 标量直接写数值，不使用 {value: ...} 包装
  • 金额使用 DECIMAL + precision + scale
  • 文档与 proto 保持一份真相来源，不手写第二套实体规则

On this page

Copyright © 2026 ApiHug·AI-native Enterprise Architecture Factory