OpenMetadata 开发规划技能指南：先设计、再编码的四阶段实施工作流

OpenMetadata 开发规划技能指南先设计、再编码的四阶段实施工作流【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata导读本文面向在 OpenMetadata 仓库中承担非平凡特性开发、跨模块重构或复杂 Bug 修复的开发者与 AI Agent系统讲解仓库内置的skills/planning/SKILL.md规划技能它要求在任何代码落地之前先完成理解问题 → 提出候选方案 → 制定分步实施计划 → 获批后执行的结构化设计思考从而避免在方向不明确的情况下贸然动手造成的返工。读完本文你将掌握 OpenMetadata 特有的 Schema 优先任务排序模式、四大技术层Java 后端 / React 前端 / Python 采集 / JSON Schema的改动顺序以及每一层配套的验证命令可直接用于指导你的下一次多文件改动。何时该启用规划技能规划技能的定位是写代码之前的设计强制门。根据skills/planning/SKILL.md的说明以下四类场景都应当主动进入规划流程而不是直接打开编辑器跨多文件或多模块的新特性一个功能同时触及数据模型、后端 API 与前端页面时改动范围大、依赖关系复杂触及后端、前端或采集层的重构OpenMetadata 是典型的多语言分层仓库重构往往横跨 Java、Python 与 TypeScript根因尚不明确的 Bug 修复在定位根因之前就动手改代码容易只修表象、引入新问题任何方案不是一眼可见的任务只要存在多种实现路径规划的价值就高于立刻编码。该技能在仓库中以可调用技能的形式定义frontmatter 中user-invocable: true其描述明确要求先头脑风暴方案、获得批准、再创建逐步实施计划是 OpenMetadata 开发工作流中面向 AI Agent 的标准化规划入口。工作流总览四个阶段整个流程分为四个阶段任何阶段之间都不应跳跃Phase 1理解问题Understand the Problem—— 阅读代码与约束不要对没读过的代码提出修改建议Phase 2提出候选方案Propose Approaches—— 给出 2~3 个带取舍分析的方案等待用户批准Phase 3创建实施计划Create Implementation Plan—— 把获批方案拆成有序、可验证的任务清单Phase 4执行Execute—— 按计划逐任务推进遇到阻塞停下讨论最后跑完整验证。下文按阶段深入展开并补充仓库源码层面的证据与可操作的细节。Phase 1理解问题——先读代码再开口这一阶段的核心纪律是一条硬性规则Read before suggesting先读再建议。不要对没有读过的代码、Schema 和测试提出修改方案。在此基础上需要完成三件事逐个提出澄清问题一次只问一个问题避免一次性倾倒 10 个问题的清单这有助于保持对话聚焦、逐步收敛需求识别约束条件规划技能明确要求回答以下四个问题哪些层会受影响Java 后端openmetadata-service/、React 前端openmetadata-ui/、Python 采集ingestion/、JSON Schemaopenmetadata-spec/各自是独立的验证单元是否有可遵循的既有模式检查同类的已有实现尽量贴合仓库既有的代码风格与结构而不是自创一套是否需要数据库迁移若需要走bootstrap/sql/migrations/下的 Flyway 迁移仓库中bootstrap/sql/migrations/flyway与bootstrap/sql/migrations/native分别存放两套 SQL 迁移脚本详见 bootstrap/sql/migrations 目录是否需要 Schema 变更若需要改动位于openmetadata-spec/的 JSON Schema 定义。从仓库结构看上述分层与 OpenMetadata 的实际模块划分完全对应Java 服务端集中在 openmetadata-service、采集与 Python SDK 集中在 ingestion、UI 资源位于 openmetadata-ui/src/main/resources/ui、Schema 定义位于 openmetadata-spec/src/main/resources/json/schema包含 entity、type、metadataIngestion、governance 等二十余个 Schema 分类目录。这一阶段产出的受影响层清单将直接决定 Phase 3 的任务排序。Phase 2提出候选方案——用结构化模板对齐方向规划技能要求为每个任务给出2~3 个候选方案并使用固定的模板结构化呈现以换取利益相关者的对齐alignment。推荐模板如下## Approach A: [方案名称] - How it works: [1-2 句话说明原理] - Pros: [优点列表] - Cons: [缺点列表] - Files affected: [受影响文件列表] - Risk: [low/medium/high] ## Approach B: [方案名称] ... ## Recommendation: [A 或 B] because [理由]要点与规则每个方案都要明确列出受影响文件与风险等级低/中/高让决策者有足够的判断依据最后必须给出明确的推荐结论A 或 B及推荐理由在用户批准之前不得进入下一阶段。规则部分重申User approves before code用户批准后才写代码、Never skip Phase 2绝不跳过第二阶段——即使方案看起来显而易见也要先陈述以达成一致。这条规则同时约束人类开发者与 AI Agent避免想到就写带来的返工。Phase 3创建实施计划——Schema 优先的有序任务清单方案获批后将其拆解为有序任务。每个任务必须满足三个条件单个聚焦步骤即可完成任务粒度要小到可以一次性做完避免改后端这种模糊的大任务明确指定内容列出要创建或修改的确切文件路径、要做的具体改动而非模糊描述以及验证命令要运行的测试、要检查的构建按依赖关系排序Schema 变更先于模型生成后端先于前端。OpenMetadata 任务排序模式Schema 优先skills/planning/SKILL.md给出了 OpenMetadata 特有的标准任务排序这是全文最关键的实战模板1. JSON Schema changes (openmetadata-spec/) 2. Run: make generate (regenerate Pydantic models) 3. Java backend changes (openmetadata-service/) 4. Run: mvn spotless:apply mvn test-compile 5. Python ingestion changes (ingestion/) 6. Run: cd ingestion make py_format make py_format_check make unit_ingestion_dev_env 7. Frontend changes (openmetadata-ui/.../ui/) 8. Run: yarn lint yarn test 9. Database migrations if needed (bootstrap/sql/) 10. Full verification: mvn test or relevant integration tests各步骤在仓库中的实现依据第 1~2 步Schema 先行 模型再生成。OpenMetadata 的数据模型以openmetadata-spec/src/main/resources/json/schema下的 JSON Schema 为单一事实源Java、Python 与前端类型都由它派生。因此凡是触及数据模型的改动必须从修改 JSON Schema 开始。改完 Schema 后执行make generate根目录 Makefile 中该目标会调用scripts/datamodel_generation.py重新生成ingestion/src/metadata/generated下的 Pydantic 模型并随后执行py_antlr、js_antlr重新生成 Python 与 JavaScript 的 FQN 解析器再对生成代码做一次 ruff 自动修复并重装 ingestion 模块。这说明Schema → 生成 → 各层消费是仓库强制的开发循环。第 3~4 步Java 后端。模型就绪后在 openmetadata-service服务端主模块源码规模最大中实现或调整 API 逻辑。验证命令mvn spotless:apply mvn test-compile中spotless 插件在根 pom.xml 配置为com.diffplug.spotless:spotless-maven-plugin:2.41.1使用 Google Java FormatGOOGLE 风格格式化src/main/java与src/test/java下的全部 Java 源码并移除未使用导入——这解释了为什么任务要求先执行spotless:apply再test-compile先统一格式再验证编译。第 5~6 步Python 采集层。后端契约确定后改动 ingestion 中的采集源码。ingestion/Makefile被根 Makefile 通过include ingestion/Makefile引入定义了三件套的语义make py_format基于 ruff 对 ingestion 与 openmetadata-airflow-apis 做 lint 修复与格式化并调用scripts/check_ruff_suppressions.py --prune清理过期的 suppressionmake py_format_check校验代码是否已正确格式化CI 侧对应的只读检查make unit_ingestion_dev_env运行本地开发用 Python 单元测试专门忽略依赖难以安装的用例如需要 pymssql 的test_azuresql_sampling.py以及所有 airflow 相关用例其注释明确标注仅用于本地开发。第 7~8 步React 前端。最后改 UI。openmetadata-ui/src/main/resources/ui/package.json中定义了lint对./src/**/*.{js,jsx,ts,tsx,json}执行 lint与testjest脚本任务中的yarn lint yarn test即对应这两个脚本确保前端改动不引入 lint 错误与单测回归。第 9~10 步迁移与整体验证。若改动需要变更数据库结构在 bootstrap/sql/migrations 下追加 Flyway/native 迁移脚本注意原文档明确要求迁移放在任务清单的靠后位置即模型与代码稳定之后。最后执行mvn test或相关集成测试做全量验证收尾整个计划。Phase 4执行——按计划推进受阻即停执行阶段的行为准则逐任务推进每完成一个就在计划上标记完成保持进度可见遇到阻塞立即停下讨论不要悄悄偏离计划——这是规划技能明确强调的红线因为未对齐的偏离会重新引入 Phase 2 本应消除的方向风险全部任务完成后运行最终验证任务清单中的第 10 步确认整个改动闭环通过。四条核心规则规划技能以四条规则收束整个流程可视为该技能的行为契约绝不跳过 Phase 2即使方案看起来显而易见陈述方案本身就能达成对齐不允许占位代码No placeholder code计划中的每一步都必须描述真实、完整的改动不能用TODO或待补充搪塞Schema 优先Schema-first功能一旦触及数据模型必须从openmetadata-spec/的 JSON Schema 改动开始让类型系统自上而下地传导变更用户批准后才写代码计划获批前不落任何代码。结合 AGENTS.md 与 CLAUDE.md 等仓库顶层协作文档可以推断这套规划技能与 OpenMetadata 的多语言、多模块工程结构深度绑定——没有 Schema 优先与分层验证的纪律一次跨层改动很容易在模型、后端、采集、前端之间出现契约漂移。而本文梳理的四阶段工作流正是把这种纪律固化为可重复执行的标准动作先读代码、再提方案、获批后拆解、按层验证。把它作为你下一次 OpenMetadata 特性开发的起点能够显著降低跨层改动的返工成本。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考