ArchDB：模块化 DB 模式作为代码

使用 ArchDB 进行模块化数据库架构设计：模板、包与声明式建模

ArchDB 允许您在 .adb 文件中以声明方式描述数据库结构，并将其集成到 Git 仓库中。模板消除了审计和标识字段的重复，而包则将单体架构分解为独立的模块。该模型可生成 DDL、文档和图表。这种方法加快了变更审查速度，并简化了与 ORM 的同步。

// Core.adb - 基础模板
Package com.example.ecommerce.Core

Template IdentifiableUuid {
  id uuid [pk, default: `gen_random_uuid()`]
}

Template Auditable {
  created_at timestamp [not_null, default: `now()`]
  created_by uuid [ref: > User.id, nullable]
  updated_at timestamp [default: `now()`]
  updated_by uuid [ref: > User.id, nullable]
  indexes {
    idx_created_at (created_at)
  }
}

Template BusinessEntity extends IdentifiableUuid, Auditable {
  version_no integer [default: 1]
  status varchar(50) [default: 'active']
}

模板实现可重用性

模板通过 extends 进行组合，继承字段和索引。BusinessEntity 结合了标识、审计和版本控制功能。将其应用于 User 表时，所有字段会自动添加：

• 带有主键和默认生成器的 UUID id
• 带有索引的 created_at/updated_at 字段
• 用于乐观锁定的 version_no

检查和唯一索引在表级别配置：

Table User extends BusinessEntity {
  email varchar(255) [unique, not_null]
  password_hash text [not_null]
  checks {
    `char_length(password_hash) >= 8`
  }
}

逻辑组通过分配颜色和描述，增强了文档的可视化效果。

通过包实现模块化分解

每个 .adb 文件都是一个独立的包，支持导入功能。Product.adb 导入 Core.adb 以扩展 BusinessEntity：

// Product.adb
Package com.example.ecommerce.Product
import "com.example.ecommerce.Core.adb" version 3.4.0

export Product as "com.example.ecommerce.Product" version 3.6.0

Table Product extends Core.BusinessEntity {
  sku varchar(50) [unique, not_null]
  price decimal(12, 2) [not_null]
  stock_quantity integer [default: 0]
  available_quantity integer [generated: `stock_quantity - reserved_quantity`]
  checks {
    `price >= cost_price`
    `reserved_quantity <= stock_quantity`
  }
}

生成字段在数据库级别计算。Relation 描述多对多关系：

Relation ProductCategory {
  Product.id <-> Category.id
}

导出版本控制（export ... version）确保模块兼容性。

| 优势 | 描述 |

|-----------|-------------|

| 独立性 | 模块并行开发 |

| 版本控制 | 导入时使用 Git 和语义版本控制 |

| 可重用性 | 通过库分发模板 |

高级实体：订单与枚举

Order.adb 导入 Core 和 Product，添加领域类型：

// Order.adb
import "com.example.ecommerce.Core.adb" version 3.4.0
import "com.example.ecommerce.Product.adb" version 3.6.0

Enum OrderStatus {
  pending [note: "等待付款"]
  paid
  shipped
  cancelled
}

Table Order extends Core.BusinessEntity {
  user_id uuid [ref: > Core.User.id]
  status OrderStatus [default: 'pending']
  total_amount decimal(12, 2) [not_null]
}

枚举作为字段类型集成。外键支持级联删除（on_delete: cascade）。

关键要点

• 声明式：描述期望状态；生成器创建 DDL 和迁移脚本。
• 模块化：包 + 导入/导出支持独立开发和 CI/CD。
• 模板：extends 组合审计字段、软删除和业务逻辑，无需复制粘贴。
• 验证：在架构级别进行检查，生成字段用于计算。
• 文档：note、Group、Metadata 生成图表和 README。

实践实施建议

• 创建包含 Identifiable、Auditable、SoftDeletable 模板的基础 Core.adb。
• 按领域将单体拆分为包：User、Product、Order。
• 设置 Git 钩子，在提交前进行架构验证。
• 集成 CI：DDL 生成、架构测试、文档更新。
• 对于 ORM：从 .adb 生成实体的脚本。

Metadata 和 Project 设置上下文：database: "postgresql"、version、author。

— Editorial Team