mcpField
K
kafka-schema-review

kafka-schema-review

github.com/lensesio测试与质量6663 次安装10 周前更新
代码仓库

关于 kafka-schema-review

kafka-schema-review 是用于审查 Kafka Schema 变更的技能，检查兼容性与质量实践。它会对照代码库定义和集群中注册的 Schema，报告漂移、破坏性变更及迁移建议。

主要功能

  1. 01通过 Lenses MCP 获取已注册 Schema
  2. 02扫描代码库中的 Schema 定义
  3. 03检查兼容性与 Schema 质量
  4. 04比对代码库和集群 Schema
  5. 05报告问题并提供迁移建议

适用场景

  1. 01合并前审查 Schema 变更
  2. 02审计预发布环境中的 Schema
  3. 03排查消费者反序列化失败

MCP 相关

使用 Lenses MCP 工具获取主题和数据集的 Schema 元数据，并在需要时抽样实时数据。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lensesio/agentic-engineering-for-apache-kafka --skill kafka-schema-review

安装后在 Claude Code 中输入/kafka-schema-review确认已加载。

附带文件references/compatibility-rules.mdreferences/test-cases.md

详细介绍

Kafka Schema Evolution 审查

审查架构变更是否兼容，以及是否遵循演进最佳实践。单个破坏性架构变更就可能导致某个主题的所有消费者都无法工作。

目标环境：$ARGUMENTS

工作流

复制此检查清单并跟踪进度：

Schema Review Progress:
- [ ] Step 1: Fetch registered schemas
- [ ] Step 2: Scan codebase for schema files
- [ ] Step 3: Detect breaking changes
- [ ] Step 4: Check schema quality
- [ ] Step 5: Check schema drift
- [ ] Step 6: Generate report
  1. 获取已注册的架构：通过 Lenses MCP 获取集群的实时信息
  2. 扫描代码库：查找架构定义文件（文件类型见 references/compatibility-rules.md）
  3. 检测破坏性变更：依据 references/compatibility-rules.md 中的兼容性规则进行检查
  4. 检查架构质量：依据最佳实践进行检查
  5. 检查架构漂移：检查代码库与集群之间的差异
  6. 报告发现：提供迁移指导

第 1 步：获取已注册的架构

使用 Lenses MCP 工具获取集群中架构的当前状态：

  • list_topic_metadata - 获取针对主题注册的所有架构（键和值）
  • get_topic_metadata - 获取特定主题当前的架构
  • get_dataset - 获取数据集的字段级详细信息、策略和治理元数据
  • 使用 schema_format 筛选条件调用 list_datasets - 查找使用指定格式（AVRO、JSON、PROTOBUF）的所有主题

预期输出：主题与其已注册架构（键和值）的映射，包含格式和版本信息。

验证：如果未注册任何架构，请将此情况记为治理缺口，并继续仅基于代码库进行分析。

第 2 步：检查代码库

搜索代码库中的架构定义文件。有关完整的文件类型列表和搜索模式，请参阅 references/compatibility-rules.md。

如果在审查 PR，请使用 git diff 找出近期更改的架构文件。

第 3 步：兼容性检查

针对每项架构变更，依据 references/compatibility-rules.md 中的兼容性规则进行评估。根据主题配置的兼容性级别，检查向后兼容性、向前兼容性和完全兼容性。

第 4 步：架构质量检查

依据 references/compatibility-rules.md 中的质量检查项进行检查：

  • 缺少文档注解的字段
  • 可选字段缺少默认值
  • 命名规范不一致
  • 未使用或过于笼统的字段名

第 5 步：检测架构漂移

将代码库中的架构文件与集群中注册的架构进行比较：

  • 使用 execute_sql 抽样查询实时数据，并验证其是否符合预期架构
  • 标记代码库中与已注册架构不同的架构
  • 标记已注册架构但在代码库中没有对应文件的主题

成功标准

定量标准
  • 能响应 90% 的架构相关查询（使用 10-20 种不同表述进行测试）
  • 在 12 次工具调用以内完成审查（MCP + 代码库搜索）
  • 破坏性变更检测的误报数为 0
定性标准
  • 对破坏性变更提供明确的迁移指导
  • 报告架构漂移时同时列出代码库和集群中的版本
  • 质量问题无需外部文档即可采取行动

示例

示例 1：合并前架构审查

用户说：“审查此 PR 中的架构变更”

操作：

  1. 运行 git diff，查找已更改的 .avsc、.proto 或 .json 架构文件
  2. 通过 Lenses MCP 获取集群中当前已注册的架构
  3. 根据兼容性规则评估每项变更 结果：报告列出所有破坏性变更，并提供迁移指导
示例 2：全面架构审计

用户说：“审计 staging 环境中的所有架构”

操作：

  1. 通过 list_topic_metadata 获取所有已注册的架构
  2. 扫描代码库中的架构文件
  3. 检查代码库与集群之间的漂移
  4. 对所有架构进行质量检查 结果：提供涵盖兼容性、质量和漂移的全面报告
示例 3：调查消费者故障

用户表示：“消费者无法反序列化来自 orders.payment.completed 的消息”

操作：

  1. 通过 get_topic_metadata 获取该主题的已注册架构
  2. 使用 execute_sql 对实时数据进行抽样，查看实际消息格式
  3. 将实际格式与仓库中的架构文件进行比较 结果：诊断出架构不匹配，并提供修复步骤

故障排查

集群中未注册任何架构

原因：未配置 Schema Registry，或主题使用无架构格式（纯 JSON、CSV）。 解决方案：这属于有效发现，应将其报告为治理方面的差距，而非错误。建议添加架构注册。

检测到架构偏移，但这是有意的

原因：集群架构在仓库之外独立更新（例如，通过 Schema Registry 界面）。 解决方案：报告偏移情况，并建议将仓库同步为与集群一致，以集群为事实来源。

无法使用 execute_sql 对数据进行抽样

原因：主题为空、权限受限，或主题使用了不受支持的格式。 解决方案：在报告中注明此限制。可使用 get_topic_metadata 作为获取架构信息的备用方式。

输出格式

## Schema Review Report

### Environment: {name}

### Breaking Changes (must fix before merge)
- [schema-file] Description of the breaking change
  Affected topics: {list}
  Migration: {guidance}

### Compatibility Warnings
- [schema-file] Description of the issue
  Recommendation: How to fix it

### Schema Quality
- [schema-file:field] Description of the quality issue
  Recommendation: How to improve it

### Schema Drift
- [topic-name] Schema in repo differs from registered schema
  Repo version: {summary} | Cluster version: {summary}

### Summary
- X breaking changes found
- Y compatibility warnings found
- Z quality issues found
- Schema files scanned: N
- Topics with drift: M

评论

支持 Markdown