第4章 元数据接入实战
第4章 · 元数据接入实战
章节摘要：接入是数据地图的外业采集阶段，也是整个项目里踩坑最密集的环节：平台部署半天就能完成，而让几十种数据源的元数据稳定流入、血缘正确成边，往往要持续数周。本章把接入讲透：pull 与 push 两种模式的取舍、官方连接器从配置到搜索可见的完整操作、自定义连接器的开发骨架、一份按症状索引的排错实录，以及一个从部署到血缘可见的真实项目全程复盘。读完本章，你应当具备独立完成一次接入落地的全部动手能力。
学习目标
读完本章，你应当能够：
- 根据数据源的特性（能否直连、是否有钩子机制、时效要求）在 pull 与 push 两种模式间做正确选择；
- 用官方连接器完成一次数据库元数据的接入，让目标表在搜索中可见且详情完整；
- 配置调度系统与 SQL 解析两类血缘来源，让表级与字段级血缘自动成边；
- 按"元数据源接入框架"开发一个自定义连接器，处理增量采集与错误上报；
- 面对"搜不到、连不上、血缘缺、权限拒"四类接入故障，按决策树定位根因；
- 规划一个接入项目的阶段划分与验收标准，预判人力投入的高峰在哪一段。
核心概念速览
接入体系围绕一个判断展开：元数据从哪来、谁来推。pull 模式由平台的摄入执行器主动到源系统抓取，覆盖面广、上手快；push 模式由源系统在事件发生时主动推送，时效好、血缘准。两者不是单选题，成熟平台的接入栈必然是两者组合。
一句金句概括本章：接入的上限不取决于连接器数量，而取决于你对"血缘从哪来"这个问题想得多清楚。 五节内容都围绕这句话展开——模式决策是在回答血缘从哪个渠道来，排错是在回答血缘为什么没来，复盘是在回答组织为血缘付出了什么。读完任意一节，回到这句话检查自己是否又多了一层具体的答案。
子章节导航
- 4.1 摄入体系：pull 与 push 两种模式——两种模式的机制、适用场景与组合策略，接入架构的顶层设计。
- 4.2 连接器实操：从 MySQL 到搜索可见——手把手完成一次官方连接器接入，含时序图与配置逐项解读。
- 4.3 自定义连接器开发——当源系统没有现成连接器时，按框架开发一个，增量、重试、上报一个不少。
- 4.4 ingestion 排错实录——按症状组织的故障决策树，每类故障给出确认方法与修复动作。
- 4.5 全程复盘：一次血缘可见的落地项目——真实项目的时间线复盘，阶段投入、翻车点与验收标准全公开。
子章节之间的逻辑关系
五节按"决策、标准动作、进阶开发、故障应对、整体复盘"组织：4.1 定架构方向，4.2 走通标准路径，4.3 覆盖标准路径之外的源，4.4 承接前两节必然会遇到的故障，4.5 把全部内容串进真实项目的时间轴。排错时可直接跳读 4.4，按症状对号入座：
[4.1 模式决策] ──> [4.2 标准接入] ──> [4.3 自定义开发] ──> [4.4 排错兜底] └──> [4.5 项目复盘]（串起全章）
前置知识与后续延伸
本章动手量全册最大：需要能操作命令行、读懂 YAML 配置、最好有初级 Python 阅读能力（自定义连接器一节）。建议在测试环境边读边做，4.2 节的操作在干净环境里半小时内可完成。
给测试环境准备两条具体建议。其一，用一个低风险的源开练：备份库、测试库或某个不重要的业务从库，别拿生产主库练手——摄入虽然是只读操作，但新手配置限流时可能给源系统制造意外压力。其二，把练习用的配置文件从第一次就放进版本库，每排一个错就提交一次，一章读完你手里会多出一份带完整注释的配置演进史，它比任何笔记都诚实。
读完本章即可进入第 5 章的功能实战——接入的元数据正是搜索、血缘、治理功能的原料。若接入过程中在模型层遇到拦截，回到 3.3 检查实体与 Aspect 的定义；部署层面的问题则留在 6.1 统一解决。
动手前再确认一遍环境：一个能连的测试源、一份能跑的摄入配置、一个能看的平台界面，三样齐备，本章所有练习即可随读随做。