百积木文档
开发指南平台应用、模块与 Bundle 开发

Type Definition

独立发布共享类型,在 Module 中导入精确版本,并验证接口兼容性。

Type Definition 是平台顶层资源,不属于 Bundle 或 Module。工作区拥有可编辑草稿,平台分配稳定 UUID。 发布版本使用严格 Semantic Version,内容不可覆盖、不可删除,不参与 Bundle 安装或 Runtime 物化。

发布与共享边界

当前发布版本会对当前平台部署中的所有工作区开放查询和引用;草稿编辑仍归所属工作区。 当前没有“发布但仅本工作区可见”或“只授权指定工作区”的类型版本能力。发布前应确认类型名称、字段、 注释和枚举可以公开,不把企业保密信息写入待发布定义。类型可读不代表有权调用实现该接口的业务服务, 服务绑定、调用权限和业务数据授权仍独立校验。

管理前端的“工作区管理 → 类型定义”用于创建、编辑、查询和发布。CLI 使用前先查看 baijimu type-definition --help 和具体子命令帮助,使用类型目录返回的身份和已发布精确版本。 发布后需要修改契约,应更新草稿并创建后继版本,不能覆盖历史版本。

编写 document

共享文档使用类型系统:命名类型与精确引用规定的当前结构。该页面统一维护 schemaVersion、kind、rootType、dataSchema、interfaces、完整示例和引用作用域;不在本页复制另一份类型语言。

发布前确认草稿中所有成员都使用当前公共 Type,根成员与 kind 一致,局部及外部引用均可解析。旧版本可查询不代表能按当前协议编译,迁移边界见兼容性与迁移。

Module 导入与引用

在 module.json 中通过 typeImports 锁定类型目录返回的环境、定义身份和精确版本,数据位置用 JsonSchema.schema.$ref 引用数据成员,接口位置用 RefType 引用接口成员。完整导入声明和 URI 语法只在命名类型与精确引用维护。

发布 Module 时展开导入、校验成员与接口实现;发布新 Type Definition 不会自动修改已发布或已安装的 Module。

发布与消费验证

  1. 在类型定义管理入口更新所属工作区的草稿,按当前协议校验完整 document。
  2. 检查类型名称、字段、注释与枚举的公开性,并按兼容性影响确定严格 SemVer。
  3. 发布新的不可变版本,回读确认文档协议、根成员和业务版本。
  4. 修改消费 Module 的精确导入,提交项目源码并从准确 Git 提交创建 Module 版本。
  5. 将新 Module 版本纳入 Bundle 后继版本,完成审核、安装及实际调用验证。

接口兼容性的输入/输出方向、对象与错误类型变化由类型系统:兼容性与迁移统一定义;方法的幂等、事务和重试语义另见方法行为与重试契约。

历史不可变版本不能覆盖,不能用修改历史文档或静默选版替代后继版本迁移。

本页内容