api-builder

API 构建器 - 完整 API 开发工作流

概述

此技能通过协调 API 架构师、集成专家和文档专家，提供端到端的 API 开发服务。它将 API 需求转化为可用于生产环境的 API，并提供全面的设计、文档、测试和集成能力。

主要能力：

• 🏗️ 多协议 API 设计 - RESTful API、GraphQL、gRPC 和 WebSocket 实现
• 📚 全面的文档 - 自动生成 API 文档、交互式测试和开发者指南
• 🔧 集成架构 - API 网关、中间件和第三方服务集成
• 📊 API 分析与监控 - 使用情况跟踪、性能监控和错误分析
• 🛡️ API 安全与治理 - 身份验证、速率限制和 API 生命周期管理

何时使用此技能

适用场景：

• RESTful API 设计与实现
• GraphQL 架构开发和解析器实现
• API 网关设置和中间件配置
• API 文档生成和开发者门户创建
• API 集成模式和第三方服务连接
• API 版本控制和生命周期管理

触发语句：

• “为 [application] 设计并实现 REST API”
• “创建具有 [features] 的 GraphQL API”
• “设置带有 [middleware] 的 API 网关”
• “生成全面的 API 文档”
• “实现与 [service] 的 API 集成”

API 开发专家小组

API 架构师（API 设计与架构）

• 重点：API 设计模式、协议选择、架构决策
• 技术：RESTful 设计、GraphQL 架构设计、API 组合
• 考量因素：可扩展性、可维护性、开发者体验、性能

集成专家（API 集成与中间件）

• 重点：API 网关、中间件、第三方集成
• 技术：API 组合、服务网格、事件驱动架构
• 考量因素：延迟、可靠性、安全性、监控

文档专家（API 文档与开发者体验）

• 重点：API 文档、开发者门户、交互式测试
• 技术：OpenAPI/Swagger、GraphQL 文档、API 测试框架
• 考量因素：开发者体验、文档准确性、可发现性

API 安全专家（API 安全与治理）

• 重点：API 安全、身份验证、授权、治理
• 技术：OAuth 2.0、API 密钥、速率限制、威胁防护
• 考量因素：安全设计、合规性、易用性

性能工程师（API 优化与监控）

• 重点：API 性能、缓存、监控、分析
• 技术：响应优化、缓存策略、负载均衡
• 考量因素：响应时间、吞吐量、资源利用率

API 开发工作流

阶段 1：API 需求分析与设计规划

适用时机：启动 API 开发或 API 现代化改造时

使用的工具：

/sc:analyze api-requirements
API Architect: API design requirements and constraints
Integration Specialist: integration points and dependencies
Documentation Expert: documentation requirements and developer needs

活动：

• 分析业务需求并将其转化为 API 规范
• 确定 API 协议和架构模式
• 定义 API 契约和数据模型
• 规划集成点和外部依赖项
• 制定 API 治理和版本控制策略

阶段 2：API 架构与协议设计

适用时机：设计 API 结构并选择协议时

使用的工具：

/sc:design --type api restful-architecture
/sc:design --type graphql schema
API Architect: comprehensive API design and protocol selection
Integration Specialist: integration architecture and patterns

活动：

• 设计 API 架构并选择协议（REST/GraphQL/gRPC）
• 创建 API 规范和数据契约
• 设计端点结构和资源关系
• 规划 API 组合和编排模式
• 定义错误处理和响应格式

阶段 3：API 实现与开发

适用场景：编写实际的 API 代码和业务逻辑

使用的工具：

/sc:implement api-endpoints
API Architect: API implementation patterns and best practices
Integration Specialist: middleware and integration implementation
API Security Specialist: security controls and authentication

活动：

• 实现 API 端点和业务逻辑
• 创建用于身份验证、验证和错误处理的中间件
• 实现数据验证和序列化
• 创建 API 版本控制和向后兼容性
• 为 API 端点编写单元测试和集成测试

阶段 4：API 文档与开发者体验

适用场景：创建全面的 API 文档和开发者资源

使用的工具：

/sc:implement api-documentation
Documentation Expert: API docs and developer portal creation
API Architect: API specification validation and examples
Integration Specialist: integration guides and SDKs

活动：

• 生成 OpenAPI/Swagger 规范
• 创建交互式 API 文档和测试界面
• 开发 SDK 和客户端库
• 编写集成指南和代码示例
• 创建开发者门户和入门材料

阶段 5：API 网关与集成设置

适用场景：设置 API 网关、中间件和集成

使用的工具：

/sc:implement api-gateway
Integration Specialist: API gateway configuration and middleware
API Security Specialist: security policies and access control
Performance Engineer: caching, rate limiting, and optimization

活动：

• 配置 API 网关的路由和策略
• 实现用于身份验证、速率限制和日志记录的中间件
• 设置 API 组合和编排
• 配置缓存和性能优化
• 实现 API 监控和分析

阶段 6：API 测试与质量保证

适用场景：确保 API 的可靠性、性能和安全性

使用的工具：

/sc:test api-comprehensive
Performance Engineer: load testing and performance validation
API Security Specialist: security testing and vulnerability assessment
Documentation Expert: documentation accuracy and usability testing

活动：

• 实现全面的 API 测试套件（单元测试、集成测试、端到端测试）
• 进行负载测试和性能基准测试
• 执行安全测试和漏洞评估
• 验证 API 契约和文档准确性
• 测试错误场景和恢复机制

集成模式

SuperClaude 命令集成

命令	用例	输出
/sc:design --type api	API 设计	完整的 API 架构
/sc:implement restful	REST API	可用于生产环境的 REST 端点
/sc:implement graphql	GraphQL API	GraphQL 架构和解析器
/sc:implement gateway	API 网关	已配置的 API 网关
/sc:test api	API 测试	全面的测试套件

API 协议集成

协议	角色	功能
RESTful	标准 API	语义规范的基于 HTTP 的 REST API
GraphQL	灵活的 API	灵活的查询语言和类型系统
gRPC	高性能 API	面向高性能场景的二进制协议
WebSocket	实时 API	实时双向通信

MCP 服务集成

服务	专长	用例
Sequential	API 推理	复杂的 API 设计和问题解决
Web Search	API 模式	最新的 API 设计趋势和最佳实践
Firecrawl	API 测试	外部 API 集成和测试

使用示例

示例 1：完整的 REST API 开发

User: "Create a complete REST API for an e-commerce platform with user management, products, and orders"

Workflow:
1. Phase 1: Analyze e-commerce API requirements and design constraints
2. Phase 2: Design RESTful API architecture with proper resource modeling
3. Phase 3: Implement API endpoints with authentication and validation
4. Phase 4: Generate comprehensive API documentation and developer portal
5. Phase 5: Set up API gateway with rate limiting and monitoring
6. Phase 6: Test API performance, security, and documentation accuracy

Output: Production-ready e-commerce API with complete documentation and monitoring

示例 2：GraphQL API 实现

User: "Implement a GraphQL API for a social media platform with real-time features"

Workflow:
1. Phase 1: Analyze GraphQL requirements and schema design needs
2. Phase 2: Design GraphQL schema with types, queries, and mutations
3. Phase 3: Implement resolvers with proper data fetching and caching
4. Phase 4: Create GraphQL documentation with schema explorer
5. Phase 5: Set up GraphQL gateway with subscriptions and real-time features
6. Phase 6: Test GraphQL queries, mutations, and subscription performance

Output: Feature-rich GraphQL API with real-time capabilities and comprehensive documentation

示例 3：API 网关与集成

User: "Set up an API gateway to integrate multiple microservices with proper security and monitoring"

Workflow:
1. Phase 1: Analyze integration requirements and service dependencies
2. Phase 2: Design API gateway architecture with routing and policies
3. Phase 3: Implement gateway with authentication, rate limiting, and logging
4. Phase 4: Configure service discovery and load balancing
5. Phase 5: Set up monitoring, analytics, and alerting
6. Phase 6: Test gateway performance, security, and failover mechanisms

Output: Enterprise-grade API gateway with comprehensive security and monitoring

质量保证机制

多层 API 验证

• 设计验证：API 架构和契约验证
• 实现测试：全面的端点和集成测试
• 文档准确性：文档验证和开发者反馈
• 性能测试：负载测试和性能基准测试

自动化质量检查

• 契约测试：自动化 API 契约验证和合规性检查
• 安全测试：自动化漏洞扫描和安全评估
• 性能监控：实时性能跟踪和告警
• 文档测试：自动化检查文档的准确性和完整性

持续改进 API

• 使用分析：跟踪 API 使用情况并提供优化建议
• 开发者反馈：监控并改善开发者体验
• 性能优化：持续监控和优化性能
• 安全监控：持续进行安全评估和威胁防护

交付成果

主要交付成果：完整的 API 系统

api-system/
├── endpoints/
│   ├── controllers/              # API endpoint implementations
│   ├── middleware/               # Authentication, validation, error handling
│   ├── routes/                   # API routing and endpoint definitions
│   └── validators/               # Request/response validation
├── schemas/
│   ├── openapi/                  # OpenAPI/Swagger specifications
│   ├── graphql/                  # GraphQL schemas and resolvers
│   ├── models/                   # Data models and DTOs
│   └── contracts/                # API contracts and interfaces
├── documentation/
│   ├── api-docs/                 # Interactive API documentation
│   ├── developer-portal/          # Developer portal and guides
│   ├── examples/                 # Code examples and tutorials
│   └── sdks/                     # Client libraries and SDKs
├── gateway/
│   ├── config/                   # API gateway configuration
│   ├── policies/                 # Gateway policies and rules
│   ├── middleware/               # Custom gateway middleware
│   └── monitoring/               # Gateway monitoring and analytics
├── tests/
│   ├── unit/                     # Unit tests for API endpoints
│   ├── integration/              # Integration tests for API interactions
│   ├── contract/                 # API contract tests
│   └── performance/              # Load and performance tests
└── config/
    ├── development/              # Development environment configuration
    ├── staging/                  # Staging environment configuration
    └── production/               # Production environment configuration

配套材料

• API 规范：完整的 OpenAPI/Swagger 和 GraphQL 架构
• 文档门户：交互式 API 文档和开发者指南
• SDK 和客户端：适用于多种编程语言的客户端库
• 集成指南：分步集成说明和示例
• 性能报告：API 性能基准和优化建议

高级功能

智能 API 设计

• AI 驱动的 API 设计建议和优化
• 自动生成并验证 API 契约
• 智能分组和组织端点
• 自动化 API 版本管理和迁移策略

高级 API 网关

• 集成服务网格和高级路由
• AI 驱动的 API 组合与编排
• 动态策略执行与调整
• 实时 API 分析和优化

增强开发者体验

• 交互式 API 测试与探索
• 自动生成适用于多种语言的 SDK
• 实时协作和 API 设计工具
• 全面的入门和学习资源

API 分析与智能

• 高级使用分析和洞察
• 性能预测与优化
• 异常检测和告警
• 商业智能集成

故障排查

常见 API 开发挑战

• 设计问题：使用适当的 API 设计模式和架构原则
• 集成问题：制定清晰的契约并妥善处理错误
• 性能瓶颈：优化查询、实现缓存并使用适当的索引
• 文档缺失：使用自动化文档生成并定期更新

API 网关和集成问题

• 路由问题：使用适当的网关配置和服务发现
• 安全问题：实施全面的身份验证和授权
• 性能问题：优化网关配置并实施适当的缓存
• 监控缺失：实施全面的日志记录、监控和告警

最佳实践

API 设计

• 遵循 RESTful 原则或 GraphQL 最佳实践
• 以可扩展性和可维护性为设计目标
• 使用适当的 HTTP 状态码并妥善处理错误
• 实施适当的版本管理和向后兼容

API 实现

• 使用适当的身份验证和授权机制
• 全面验证和清理输入
• 妥善处理错误并记录日志
• 编写全面的测试和文档

API 文档

• REST API 使用 OpenAPI/Swagger
• 创建包含示例的交互式文档
• 提供清晰的集成指南和 SDK
• 确保文档保持最新且准确

API 网关配置

• 实施适当的安全策略和速率限制
• 使用全面的日志记录和监控
• 配置适当的负载均衡和故障转移
• 实施缓存和优化策略

---

这项 API 构建器技能将复杂的 API 开发流程转化为有指导且有专家支持的工作流，确保构建出设计完善、文档齐全、可用于生产环境的 API，并具备全面的集成和监控能力。