4. 对象引用与关系建立

在 Jira Assets 中，对象本身只是静态的数据记录，真正让资产模型产生工程价值的是对象之间的引用关系。引用类型（Reference Types）定义了“谁指向谁、指向意味着什么”，而对象引用（Object References）则是这些类型在具体对象之间的实例化。理解引用类型的方向与语义，是构建可查询、可追溯、可影响分析资产图谱的前提。

引用类型的方向性：从“源”到“目标”

每一个引用类型都有明确的源对象类型（Source Object Type）和目标对象类型（Target Object Type），以及一个方向性描述。方向决定了在对象详情页中，引用出现在哪一侧：源对象上显示“出向引用”，目标对象上显示“入向引用”。例如，定义“应用依赖数据库”时，源是“应用”，目标是“数据库”，方向为“应用 → 数据库”。在应用对象上可以看到它依赖哪些数据库；在数据库对象上则可以看到被哪些应用依赖。

方向不是装饰性的，它直接影响 AQL 查询的写法。查询“哪些应用依赖了 DB-PROD-01”时，需要从应用侧出发，使用 outboundReferences 或引用类型名称进行过滤；而查询“DB-PROD-01 被哪些应用依赖”时，则从数据库侧使用 inboundReferences。如果方向定义反了，后续所有影响分析和报表都会出现逻辑错误。

三类核心引用语义：依赖、托管、连接

在应用与服务器、数据库的关联场景中，最常用的三类引用语义如下：

• 依赖（Depends on）：表示源对象的运行或功能需要目标对象存在。语义是“没有它，我就不完整或不可用”。典型例子：应用依赖数据库、应用依赖中间件、服务依赖认证系统。依赖关系通常用于影响分析——当数据库计划停机时，所有依赖它的应用都应被识别出来。
• 托管（Hosted on / Hosts）：表示物理或逻辑承载关系。语义是“我运行在它上面”或“它承载了我”。典型例子：应用托管在服务器上、虚拟机托管在宿主机上、数据库实例托管在数据库服务器上。托管关系通常用于定位和容量管理——服务器下线时，需要知道上面托管了哪些应用和数据库。
• 连接（Connects to）：表示网络或通信层面的可达关系。语义是“我与它存在通信链路”，但不一定存在强依赖。典型例子：应用连接消息队列、应用连接缓存集群、服务连接外部 API 网关。连接关系用于网络拓扑和故障域分析，比依赖关系更偏基础设施视角。

三类语义可以同时存在于同一对对象之间。例如，一个应用既“托管”在一台服务器上，又“连接”到某个数据库，同时“依赖”该数据库提供数据服务。它们回答的是不同的问题，不应混用。

在 Assets 中创建引用类型与对象引用

创建引用类型时，需要依次确定以下要素：名称、描述、源对象类型、目标对象类型、方向标签（出向/入向的显示名称）。建议命名采用“源语义 + 目标语义”的方式，例如“应用依赖数据库”和“数据库被应用依赖”，这样在两侧对象页面上都能看到符合阅读习惯的标签。

创建对象引用的操作路径通常为：进入源对象详情页 → 找到对应引用类型的引用区域 → 添加目标对象 → 选择具体对象并保存。也可以在目标对象侧通过入向引用区域反向建立，效果等价，但方向仍由引用类型定义决定。

下面给出一个可参考的引用类型配置示例，用于应用、服务器、数据库三类对象之间的关联：

建立引用后，可以通过 AQL 验证关系是否正确。例如，查询所有托管在 SRV-PROD-07 上的应用：

objectType = "应用" AND
"应用托管于服务器" IN outboundReferences AND
outboundReferences."应用托管于服务器" = "SRV-PROD-07"

如果返回结果为空，应检查引用类型的方向是否定义反了，或者对象名称是否精确匹配。Assets 的引用查询对对象名称大小写和空格敏感，建议使用对象 Key 而非显示名称进行过滤，以提高稳定性。

关系建立后的影响分析示例

假设生产环境需要将数据库 DB-ORDER-01 迁移到新服务器。通过已建立的引用关系，可以快速得到影响范围：

1. 查询所有“依赖数据库”指向 DB-ORDER-01 的应用，得到受影响应用清单。
2. 查询 DB-ORDER-01 的“托管于”引用，确认当前所在服务器。
3. 查询这些应用是否还“连接”了其他数据库或消息队列，判断是否存在跨系统耦合。
4. 根据结果安排迁移窗口和通知范围。

这个过程不需要人工翻查表格，完全依赖引用关系的方向性和语义正确性。如果“依赖”和“连接”被混用，影响分析就会把仅通信可达但无强依赖的系统也纳入停机范围，造成不必要的协调成本。

从图中可以直观看到，同一个应用对象同时拥有三类出向引用：托管于服务器、依赖数据库、连接消息队列。数据库自身又托管于同一台服务器。当 SRV-PROD-07 需要维护时，通过入向引用可以同时找到“托管应用”和“托管数据库”，再沿数据库的入向“被应用依赖”找到所有受影响应用，形成完整的故障影响链。

最后，建议为每类引用关系建立命名规范和定期校验机制。命名规范确保不同人员创建引用时语义一致；定期校验则通过 AQL 检查是否存在孤立对象、方向异常或重复引用。例如，检查是否存在“应用托管于服务器”但服务器对象已标记为“已退役”的情况，这类引用应及时清理或迁移，避免资产图谱随时间腐化。