夜雨聆风
AI研发
基于 SDD 规范的 Kubernetes 集群资源查询
案例背景
Kubernetes运维平台迭代中，为解决传统命令行查询繁琐、数据分散的问题，我们确立了开发K8s集群节点资源查询的目标。本需求的核心挑战在于如何在短时间内，通过AI辅助实现对复杂K8s API的安全调用与多维度数据聚合。
核心创新：SDD驱动的AI研发规范（Spec-Driven Development）
本需求最大的价值不在于功能本身，而在于验证了一套标准化的AI研发流程（SDD AI Paradigm）。区别于随意的对话式开发，本需求严格遵循了"模版定义→规格生成→代码实现的三步走战略：
1. 模板标准化（Templating）：预先定义了《需求Spec.md模版》、《设计Spec.md模版》和《编码Spec.md模版》，确保AI输出的结构化和规范化。
2. 规格生成（Specification Generation）：
需求阶段：基于模版生成《需求文档》，明确功能边界与验收标准
设计阶段：基于模版生成《设计文档》，确立技术选型与数据模型
3. 代码落地（Implementation）：利用AI根据生成的"需求+设计+编码模版"三位一体指令，直接产出高质量代码
01.
第一阶段：需求定义
执行动作
使用《需求Spec.md模版》作为Prompt指引，输入核心需求关键词（K8s节点、CPU/内存/磁盘查询、安全存储）。以下是本需求的Spec模版截图：
AI产出
完整的《需求文档》，以下是完整需求文档部分截图：
关键成果
• 核心痛点锁定：AI准确识别了运维人员"操作复杂、数据分散、安全风险的痛点
• 需求结构化：AI生成了标准的FR（功能需求）与NFR（非功能需求）列表，特别是明确了 "kubeconfig不落盘" 的安全红线，为后续开发定下基调
• 验收标准明确：定义了详细的测试用例和验收条件
02.
第二阶段：架构设计
执行动作
使用《设计Spec.md模版》，输入需求文档内容，指令AI进行技术方案设计。以下是本需求设计Spec模版部分截图：
AI产出
完整的《设计文档》，以下是完整设计文档部分截图：
关键成果
• 技术选型：AI建议采用Spring Boot 3.3 + React 18的技术栈，保持了项目技术的一致性
• 架构绘制：AI生成了清晰的前后端分离架构图，明确了Controller → Service → K8sClient的调用链路
• 数据模型：AI设计了分层的DTO结构（如NodeResourceQueryRequest和NodeResourceVO），确保了数据传输的清晰与可扩展性
• 安全设计：详细规划了kubeconfig的内存处理机制和权限控制策略
03.
第三阶段：编码实现
执行动作
综合《需求文档》、《设计文档》与《编码Spec.md模版》，构建复杂的Prompt指令集，驱动AI生成具体代码。
AI产出
可直接运行的前后端代码
关键实现细节（AI生成亮点）
后端逻辑（Java/Spring Boot）
• 安全处理：AI严格遵循了"不落盘"原则，在K8sNodeController中仅记录kubeconfig长度用于调试，避免了敏感信息泄露
• 算法优化：在节点筛选逻辑中，AI自动生成了使用Map进行O(1)时间复杂度查找的代码，而非低效的遍历，体现了对性能优化的理解
• 异常体系：AI自动生成了完善的自定义异常（如K8sConfigInvalidException）和全局异常处理器，保证了API返回格式的统一
• 资源管理：实现了kubeconfig配置的临时存储和及时清理机制
前端交互（React/TypeScript）
• 状态管理：AI生成了基于React Hooks的页面逻辑，精准管理了loading、result和error状态
• UI组件：根据设计文档，AI输出了Ant Design表格组件的配置代码，支持多级表头和进度条展示，实现了直观的数据可视化
• 用户体验：实现了友好的加载状态和错误提示机制。
技术实现细节
核心技术栈
• 后端：Spring Boot 3.3, Kubernetes Java Client, Maven
• 前端：React 18, TypeScript, Ant Design
• 部署：Docker, Kubernetes
关键技术点
1. Kubernetes API集成：通过Kubernetes Java Client实现安全的集群访问
2. 资源指标获取：使用Metrics Server API获取节点实时资源使用情况
3. 安全机制：实现kubeconfig的内存处理和及时清理
4. 数据聚合：对多个节点的资源数据进行统一格式化处理
质量保证措施
测试覆盖
• 单元测试：AI自动生成了核心业务逻辑的单元测试用例
• 集成测试：实现了完整的API集成测试
• 安全测试：验证了kubeconfig的安全处理机制
文档生成
• API文档：自动生成了Swagger API文档
• 用户手册：生成了详细的操作指南
• 部署文档：提供了完整的部署配置说明
效果展示
总结与反思
本次Kubernetes集群查询功能的成功上线，验证了SDD（Spec-Driven Development）研发规范在AI时代的巨大价值。
核心优势
1. 模版即约束：通过提供标准化的Spec模版，有效地约束了AI的"幻觉"，使其输出始终围绕工程目标
2. 分层递进：先文档后代码的流程，让我们在早期就能发现逻辑漏洞（如资源估算的准确性问题），降低了后期返工成本
3. 质量保证：AI不仅生成了业务代码，还自动生成了单元测试用例和API接口文档，极大地提升了交付质量
4. 知识沉淀：形成了可复用的Prompt模版库和开发模式
改进空间
• 模版优化：需要进一步完善各阶段Spec模版的细节
• 验证机制：加强AI生成内容的人工审核流程
• 工具集成：考虑将SDD流程集成到CI/CD工具链中
后续规划
我们将把这套《需求/设计/编码Spec模版》沉淀为团队的标准Prompt库，推广至Helm应用管理、Pod日志查询等更多K8s相关功能的开发中。同时，计划开发内部的SDD辅助工具，进一步提升AI研发的效率和质量。
通过本需求的成功实践，我们证明了结构化的AI研发流程能够显著提升软件开发的效率和质量，为未来的AI辅助开发奠定了坚实的基础。
作者 | 公共平台与架构研发事业部 章鑫
