|
| 1 | +## OpenMetadata 功能需求文档:词汇表术语的永久链接 (Stable URL) |
| 2 | + |
| 3 | +### 1. 核心问题 (Problem Statement) |
| 4 | + |
| 5 | +当前 OpenMetadata 词汇表术语 (Glossary Term) 的 URL 严重依赖其 FQN (完全限定名称)。这导致了三个主要痛点: |
| 6 | + |
| 7 | +* **链接稳定性差:** 当术语的`name`或其在词汇表中的**层级结构**发生变更时,FQN 会随之改变。这导致所有从外部系统(如 Confluence, Google Docs, Word, Notion 等)引用的 URL 全部失效,破坏了知识库的链接完整性。 |
| 8 | +* **国际化支持不佳:** 对于使用非拉丁语系(如俄语/西里尔字母)的用户,术语的`name`在 URL 中会被编码为不可读的字符串 (例如 `%D0%B3%D0%BB...`),严重影响了 URL 的可读性和可用性。 |
| 9 | +* **用户体验混乱:** 在创建术语时,用户普遍不理解为何需要同时填写 `name` 和 `displayName` 两个字段,尤其是在两者内容几乎重复的情况下,这增加了不必要的操作摩擦。 |
| 10 | + |
| 11 | +### 2. 核心需求 (Core Feature Request) |
| 12 | + |
| 13 | +为了解决链接失效问题,我们必须引入一种独立于 FQN 的、**永久稳定**的链接机制。 |
| 14 | + |
| 15 | +核心需求是:**词汇表术语的 URL 必须支持通过其唯一的 ID (UUID) 进行解析。** |
| 16 | + |
| 17 | +### 3. 具体功能点 (Acceptance Criteria) |
| 18 | + |
| 19 | +为实现此核心需求,需要满足以下功能点: |
| 20 | + |
| 21 | +1. **路由逻辑 (Routing):** |
| 22 | + * 系统路由必须支持解析格式为 `https://[host-name]/glossary-term/[UUID]` 的 URL。 |
| 23 | +2. **版本解析 (Version Resolution):** |
| 24 | + * 当用户访问一个仅包含 UUID 的词汇表 URL 时,系统必须**自动解析并重定向到该术语的“最新版本” (Latest Version) 的概览页面**。 |
| 25 | + * 这解决了当前使用“特定版本 URL” (`.../versions/0.5`) 作为变通方案时,链接会过时的问题。 |
| 26 | +3. **UI 界面增强 (UI Enhancement):** |
| 27 | + * 在词汇表术语的 UI 界面上,必须提供一个清晰的“复制 URL”功能。 |
| 28 | + * 点击此按钮后,应允许用户至少选择“按 ID 复制 URL”(获取新的稳定链接),也可以保留“按 FQN 复制 URL”(当前行为)。 |
| 29 | + |
| 30 | +### 4. 相关讨论与备选方案 (Related Issues & Alternatives) |
| 31 | + |
| 32 | +在相关的讨论中,还提出了两个旨在解决“URL 不可读”和“`name`/`displayName` 混淆”问题的补充方案: |
| 33 | + |
| 34 | +* **方案 1: 自动生成 `name` (音译)** |
| 35 | + * **描述:** 用户在表单中只填写 `displayName`。系统通过音译(例如使用 `slugify` 库将西里尔字母转为拉丁字母)自动生成一个 URL 友好且唯一的 `name`。 |
| 36 | + * **优点:** 简化用户操作;生成的 URL 可读性强;不破坏现有的 FQN 路由逻辑。 |
| 37 | + * **缺点:** 需要引入额外的转写库;可能存在命名冲突(需要处理)。 |
| 38 | +* **方案 2: 在 URL 中(完全)使用 `id` 替代 `name`** |
| 39 | + * **描述:** 在 UI 表单中移除 `name` 字段,只保留 `displayName`。URL 结构完全切换为 `.../glossary/<UUID>`。 |
| 40 | + * **优点:** 链接绝对稳定;UI 极致简化;无命名冲突。 |
| 41 | + * **缺点:** 需要在整个项目中进行重大更改;URL 丧失了可读性;无法从 URL 中直观看出术语的层级结构。 |
| 42 | + |
| 43 | +### 5. 总结建议 (Summary of Feedback) |
| 44 | + |
| 45 | +所有讨论均指向一个明确的共识:**启用 ID 作为 URL 的一部分以确保链接的永久稳定性是必须的**,这对依赖外部文档引用的用户至关重要。 |
| 46 | + |
| 47 | +同时,“自动从 `displayName` 生成 `name`”(方案 1)的提议也获得了支持,它可以作为解决 UI 混淆和非拉丁字符 URL 可读性问题的补充优化。 |
| 48 | + |
| 49 | +**建议的实施路径:** |
| 50 | +优先实现**核心需求 (第 2、3 点)**,解决链接失效的痛点。然后,将**方案 1 (自动生成 `name`)** 作为一个独立的改进点进行评估,以优化新术语的创建体验和 URL 可读性。 |
| 51 | + |
| 52 | +--- |
0 commit comments