简介面向数据采集与数据治理人员一套基于Java的数据库元数据采集工具源码可自动抓取指定目标库中的所有表、字段、主外键与统计信息帮助开发者在数据盘点、指标梳理时快速掌握库表全貌。压缩包共100个文件整体体积仅115KB以84个Java类为核心实现同时包含5个YAML配置、2个SQL脚本、XML/PROPERTIES等辅助文件Java代码负责数据库连接、元数据解析与记录封装YAML与SQL则便于按环境调整采集参数和查询模板。目前已有120人学习下载适合需要深度理解数据库结构、设计数据资产目录或进行数据治理的初中级开发者。通过通读服务实现层、抽象接口及Hive等JDBC客户端使用者不仅能掌握跨数据源元数据采集的通用流程还能将其中分层设计与连接池思路复用到自有项目中显著降低从零开发同类工具的成本。1. 元数据采集从“表很多”到“结构可查”的第一步很多数据团队在表数量超过一千张之后都会遇到同一个问题数据库里到底有哪些表每张表的字段和注释是什么居然没有一个人能完整说清楚。手动维护数据字典在业务快速迭代时几乎不可用而元数据采集正是解决这个问题的自动化基线能力。它抓取指定目标库的所有表信息包括表名、字段名、类型、注释、分区和统计信息最终形成可查询、可对比的数据集。本文基于一份Java编写的元数据采集项目源码拆解从JDBC连接、Hive客户端封装到表字段元数据落库的完整实现路径并提供可直接改装的代码。适合数仓工程师、数据平台研发和数据治理落地团队参考。2. 目标库表信息的采集模型从AbstractGatherDataBaseInter到GatherServiceImpl元数据采集和普通的数据查询看着像但实际差异很大。普通查询只需要满足当下业务条件元数据采集却要稳定地拿到整个目标库的结构全貌并且让后续的数据治理任务能依赖这份结构数据。因此代码不能写成一坨一次性脚本必须有清晰的采集模型。2.1 元数据采集的分层逻辑生产环境中要面对不同目标库的方言差异和网络边界所以代码必须分层。这个项目里AbstractGatherDataBaseInter是抽象基类把“采集一张表信息”拆成一组固定步骤GatherServiceImpl是编排者只负责触发任务MetadataServiceImpl负责把采集到的结构记录持久化。这个分层的好处是换一个目标库类型不需要重写服务层只需要新增一个继承AbstractGatherDataBaseInter的实现类重写连接和查询逻辑即可。类似模板方法模式采集流程的骨架由父类定义实际SQL由子类填充。在此基础上MetadataServiceImpl不是简单把表列表保存下来它同时维护表信息与字段信息的关联关系。拿Hive来举例一个目标库database下有多个表每个表有多个字段。如果不做关联后续解析字段血缘时就得反复连库采集数据集的可用性会大打折扣。实际项目中这个类还会负责幂等写入同一时间点重复执行采集任务不能重复插入同一张表的元数据。2.2 DsgGatherTableRecord与DsgGatherTableFieldsRecord两级采集对象在Java源码里这两条Record类不是普通临时对象而是贯穿采集链路的数据载体。DsgGatherTableRecord描述目标库中的一张表DsgGatherTableFieldsRecord描述这张表的一个字段。值得注意的是它们都带有“Dsg”前缀在真实项目中通常是数据治理组Data Stewardship Group的缩写说明这套代码从一开始就是为治理场景设计的。用表格把这组对象的常用字段写清楚方便改造时对齐采集对象核心字段说明示例DsgGatherTableRecorddbName目标库名odstableName表名user_ordertableType表类型MANAGED_TABLEtableComment表注释用户订单明细partitionKeys分区字段dtcreateTime建表时间2024-06-01 10:00:00DsgGatherTableFieldsRecorddbName目标库名odstableName表名user_orderfieldName字段名user_idfieldType字段类型bigintfieldComment字段注释用户IDfieldOrder字段顺序1字段顺序非常重要。很多元数据工具容易忽略它导致后面用PowerDesigner反向建模时属性乱序。fieldOrder直接取INFORMATION_SCHEMA.COLUMNS.ORDINAL_POSITION或者Hive中DESCRIBE返回的行号。代码里用一个计数器就能生成不需要额外查询。接下来是记录转换代码示例// 将JDBC查询结果转换为表字段记录 public DsgGatherTableFieldsRecord toFieldRecord(ResultSet rs, int order) throws SQLException { DsgGatherTableFieldsRecord record new DsgGatherTableFieldsRecord(); record.setDbName(rs.getString(TABLE_SCHEMA)); record.setTableName(rs.getString(TABLE_NAME)); record.setFieldName(rs.getString(COLUMN_NAME)); record.setFieldType(rs.getString(DATA_TYPE)); record.setFieldComment(rs.getString(COLUMN_COMMENT)); record.setFieldOrder(order); return record; }这段代码做的事情很直接从ResultSet里取元数据列映射成内部Record。注意TABLE_SCHEMA在不同数据库里的语义不同在MySQL里对应数据库名SQL Server里对应schema名在Hive里则对应database。所以把这个值留在Record里很重要后续做跨库校验时不需要重新推断来源。2.3 GatherServiceImpl如何调度一次“全表扫描”GatherServiceImpl是整个采集任务的入口。它拿到“指定目标库”之后先创建相应数据库类型的采集工作器挨个读取表列表再逐表读取字段列表最后把结果交给MetadataServiceImpl保存。下面是一个简化但是保留了关键链路的调度代码public void gatherDatabase(AbstractGatherDataBaseInter worker, String targetDb) { long start System.currentTimeMillis(); ListDsgGatherTableRecord tables worker.fetchTableList(targetDb); for (DsgGatherTableRecord table : tables) { ListDsgGatherTableFieldsRecord fields worker.fetchFieldList(table); metadataService.saveTableFields(targetDb, table, fields); } saveStatistics(targetDb, tables.size(), System.currentTimeMillis() - start); }这里的worker.fetchTableList查的是目标库的表清单worker.fetchFieldList查的是单张表的字段清单。把“查表”和“查字段”拆成两个方法是为了在不同数据库上做优化。例如Oracle查询所有表要用ALL_TABLES字段要用ALL_TAB_COLUMNS而Hive里用SHOW TABLES加DESCRIBE就够。如果合并成一个SQL反而会增加耦合。注意这个调度方法里没有在循环内打印每条表的明细日志原因是几百张表时日志量会非常大也会拖慢采集速度。实际生产中我一般只在表数量超过一百张时按表名分组打INFO日志再配合后文会讲的统计记录来观测进度。3. Hive元数据抓取的关键实现HiveJdbcClient与MetadataServiceImpl目标库如果是Hive就不能简单套用MySQL JDBC思路。HiveServer2提供的JDBC驱动支持jdbc:hive2://协议底层走Thrift默认端口10000。HiveJdbcClient这个类的作用就是屏蔽Hive JDBC的细节让上层不需要感知认证方式和HTTP传输模式。3.1 Hive JdbcClient的连接参数配置时最容易踩坑的是URL格式和认证参数。HiveServer2从2.0开始支持多种认证方式未开启Kerberos时可以使用用户名/密码模式但很多生产集群会启用LDAP或Kerberos。下面是一份常用的连接参数表标注了用与不用时的注意点参数示例值是否常见使用说明jdbcUrljdbc:hive2://10.0.1.20:10000/ods必填指定HiveServer2地址和默认databaseuserdata_gather推荐连接用户名需要目标表查询权限password密文存储推荐密码建议通过配置中心注入而非写在代码transportModehttp按需若HiveServer2启用HTTP传输需要配合httpPathhttpPathcliservice按需HTTP传输模式下的cliservice路径principalhive/hostREALM按需Kerberos认证时必填zooKeeperNamespacehiveServer2选配通过ZooKeeper动态发现Server时使用HiveJdbcClient一般会封装DriverManager.getConnection(jdbcUrl, props)并设置hive.resultset.use.unique.column.names为false否则查询SELECT *时重名列会被自动改名导致解析元数据时字段名对不上。可以在连接属性中显式设置props.setProperty(hive.resultset.use.unique.column.names, false)。3.2 用JDBC获取目标库所有表的两种方式方式一执行Hive专有命令。用Statement.executeQuery(SHOW TABLES IN targetDb)可以拿到表名列表。这种方式最通用兼容便宜但返回结果只有一列拿不到表注释、表类型、建表时间适合快速遍历。方式二查询INFORMATION_SCHEMA。Hive从3.0开始支持INFORMATION_SCHEMA.TABLES和INFORMATION_SCHEMA.COLUMNS视图能一次拿到更完整的结构信息。但要注意视图数据来自Hive Metastore的缓存如果集群Metastore跟HiveServer2版本比较旧可能查不到需要先确认版本。下面这段代码演示了HiveJdbcClient中如何获取表列表并补齐必要信息public ListDsgGatherTableRecord fetchTableList(Connection conn, String targetDb) throws SQLException { String sql SELECT TABLE_NAME, TABLE_TYPE, CREATE_TIME, COMMENT FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA targetDb ; ListDsgGatherTableRecord result new ArrayList(); try (Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(sql)) { while (rs.next()) { DsgGatherTableRecord record new DsgGatherTableRecord(); record.setDbName(targetDb); record.setTableName(rs.getString(TABLE_NAME)); record.setTableType(rs.getString(TABLE_TYPE)); record.setCreateTime(rs.getTimestamp(CREATE_TIME)); result.add(record); } } return result; }这段代码最需要注意的坑是字符串拼接SQL。生产环境里库名来自配置中心不会出现恶意输入但为了安全建议用setString参数化查询。Hive JDBC对参数化Query支持不稳定所以我在这里没有用PreparedStatement而是在进入方法前对targetDb做了白名单校验只允许字母、数字、下划线。这个取舍在元数据采集场景里是合理的。3.3 字段级元数据的组装与类型映射表信息抓回来之后下一步是抓字段。Hive里最可靠的方式是DESCRIBE FORMATTED但从3.0也可以直接查INFORMATION_SCHEMA.COLUMNS。字段类型在不同数据源之间差异很大采集后一定要做归一化。比如Hive的BIGINT应该归一化成度量语义的bigintDECIMAL(10,2)要保留精度参数。下面这张映射表是采集Hive目标库时默认使用的归一化规则其他数据库可以参照扩展Hive原始类型归一化类型说明TINYINTtinyint保留原类型名SMALLINTsmallint保留原类型名INT / INTEGERint统一为intBIGINTbigint统一为bigintFLOATfloat保留原类型名DOUBLEdouble保留原类型名DECIMAL(p,s)decimal(p,s)精度和小数位保留STRING / VARCHARstring业务上按字符串处理TIMESTAMPtimestamp统一时间类型ARRAY...array复杂类型按大类归一MAP...map复杂类型按大类归一代码里做映射通常是一个静态Map加一个回退逻辑遇到不认识的类型就返回原始类型而不是抛异常。因为下一个Hive版本很可能又有新类型元数据采集工具不应该因为一个类型没录到就中断整个任务。相关的DsgGatherTableFieldsRecord构造逻辑可以直接从INFORMATION_SCHEMA.COLUMNS里拉出全部列再逐行写入HashMap。4. 实战抓取指定目标库的所有表信息前两章把模型和关键类讲透了这一章节直接落到工程实现。一个可以跑起来的元数据采集任务需要把依赖、配置、执行逻辑和结果落库串起来。4.1 准备阶段依赖、配置、启动入口一个可运行的采集工程至少需要三块Hive JDBC驱动、连接配置、主程序。依赖不建议在代码里写死Hive版本因为Hive的JDBC接口相对稳定由连接的目标集群决定就行。Maven里通常这样引入dependency groupIdorg.apache.hive/groupId artifactIdhive-jdbc/artifactId version${hive.version}/version /dependency很多踩坑文章没有提醒的是hive-jdbc会传递依赖大量的Hadoop包启动时容易出现Jackson、Guava冲突。我一般会把hive-jdbc的provided置为true再单独把运行所需的Hadoop客户端包放在执行环境里避免污染采集服务自身的依赖树。连接配置建议写成外部化配置文件至少要包含以下参数配置项示例值说明target.dbods指定目标库采集该库下的所有表信息hive.urljdbc:hive2://hiveserver2:10000/odsHiveServer2 JDBC地址hive.usergather_user采集任务专用账号避免使用roothive.password******密码或keytab路径我一般会把连接串放在配置中心而不是写死在application.properties里因为采集服务通常不止连一个目标库改库不需要重新发版。配置完毕启动入口可以直接用main方法也可以封装成Spring Boot的定时任务这个不影响链路本身。4.2 核心流程代码演示有了配置就可以写一个简单的执行入口。下面省略了异常处理和日志框架细节突出采集链路本身public class MetadataGatherRunner { public static void main(String[] args) throws Exception { String targetDb props.getProperty(target.db); String hiveUrl props.getProperty(hive.url); try (Connection conn DriverManager.getConnection(hiveUrl, props)) { HiveJdbcClient client new HiveJdbcClient(conn); ListDsgGatherTableRecord tables client.fetchTableList(targetDb); ListDsgGatherTableFieldsRecord allFields new ArrayList(); for (DsgGatherTableRecord table : tables) { ListDsgGatherTableFieldsRecord fields client.fetchFieldList(table); allFields.addAll(fields); System.out.printf(gathered %s.%s, columns%d%n, targetDb, table.getTableName(), fields.size()); } MetadataServiceImpl metadataService new MetadataServiceImpl(); metadataService.saveTableInfo(tables); metadataService.saveFieldInfo(allFields); } } }这里有一个容易被忽略的性能点fetchFieldList每张表执行一次查询如果目标库有几百张表就需要几百次往返。生产中我一般会在HiveJdbcClient里增加一个批量方法一次查出整库字段列表再在内存里按表名分组把往返次数从“表数量”降为“1”。这样采集时间可以从几十分钟降到分钟级。参数hive.url里的database需要和target.db保持一致否则INFORMATION_SCHEMA查询结果可能出现跨库信息这不是期望的结果。4.3 采集结果与统计信息落库采集完成后的数据不能只留在内存里要落库供后续查询。落表设计上标题里的“数据集”语义就体现出来了。我会把表信息、字段信息、统计信息拆成三张表统计信息以DsgGatherStatisticsRecord为代表。统计表结构在MySQL或Hive中都可以这样建CREATE TABLE metadata_gather_stats ( target_db STRING COMMENT 目标库名, gather_time TIMESTAMP COMMENT 采集时间, table_count INT COMMENT 表数量, field_count INT COMMENT 字段数量, cost_ms BIGINT COMMENT 耗时ms, status STRING COMMENT SUCCESS/FAILED ) COMMENT 元数据采集统计记录;采集完成后GatherServiceImpl会向这张统计表写入一条记录。线上运维时只要查最近一次采集的status和cost_ms就能快速判断元数据任务是否正常运行。这里再补充一个细节DsgGatherStatisticsRecord.java里保存的字段数量一定要用整库累计值不要只记录最后一次循环的数字否则运行到一半失败会把错误信息带进统计表。正确的做法是在进入循环前初始化一个AtomicInteger每张表采集完就累加字段数最后统一写入统计记录。5. 进阶技巧用DateTimeUtil与统计记录做增量元数据采集全量抓取是基线增量则是日常。这里分享一个不引入复杂CDC工具的轻量方案核心用到了源码里的DateTimeUtil。5.1 基于DateTimeUtil的表结构变更检测如果每天全量抓取一次几百张表虽然能做基线但变更发现不及时。常见做法是利用DateTimeUtil统一处理采集时间让统计表和元数据快照都使用同一个时间戳。这样每次采集结果与上一次快照比对时就能准确判断表结构是否发生变更。比如在MetadataServiceImpl里加一个diffWithLastSnapshot方法读取上次采集的表字段哈希与本次生成的字段列表做比对把前后不一致的表输出到diff结果集。代码示意String snapshotKey db . tableName; String currentFingerprint fields.stream() .map(f - f.getFieldName() : f.getFieldType()) .sorted() .collect(Collectors.joining(|));这里用排序后的字段名和类型拼接成指纹比较两个时间点是否一致。加了新字段、改了类型、调整了顺序都会被识别为结构变更。不要只比较表数量因为表数量不变也有可能字段已经变化。DateTimeUtil在这里的作用是让每次快照都带上业务时间语义避免因为服务器时区不一致导致比较错位。5.2 元数据采集的排错与验证实际运行中遇到最多的三个问题我分别说判断方法。第一Unable to open transport说明HiveServer2服务不可达或端口不通用telnet确认端口再查beeline能否手动连接。第二认证失败出现在开启LDAP或Kerberos的集群需要检查principal和keytab路径可以对比集群中已经正常运行的Beeline命令。第三SHOW TABLES能返回结果但字段抓取为空多半是当前用户对表的DESCRIBE权限不足这是Hive的授权策略导致的。验证采集结果是否完整可以用一行SQL对比源端和目标端SELECT COUNT(*) FROM metadata_gather_tables WHERE db_name ods; SELECT COUNT(*) FROM metadata_gather_fields WHERE db_name ods;两条记录数一致才能确认元数据没有漏采。这套验证方法也可以直接落到调度平台的自动化检查里不需要额外开发复杂框架。实际推进数据治理时把这份元数据采集结果接入字段血缘解析就能形成从表结构到任务依赖的完整治理链路。本文还有配套的精品资源点击获取