version: "1.0.0" name: vibe-api-rules description: Use this skill to design API rules, standards, and guidelines for the project.

API规则文档设计工作流

1. 文档目的

规范API规则文档的设计流程，确保根据需求文档和架构文档制定严格的API和数据模型规则，为前后端开发提供明确的规范。

2. 工作流结构

一个简洁高效的API规则文档设计工作流应包含：

• 基本信息：项目名称、设计目标
• 前置步骤：文档检查、依赖项确认
• 执行步骤：详细的API规则设计流程和顺序
• 执行建议：专业建议和注意事项
• 成功标准：API规则文档完成的判定条件
• 失败处理：异常情况的应对措施
• 输出成果：明确的交付物和保存位置

3. 执行要求

• 严格按照步骤执行
• 与用户保持深度沟通
• 记录关键信息和结果
• 遇到异常时按失败处理机制执行
• 确保输出成果符合用户预期

4. 文档管理

• 执行后根据实际情况更新文档
• 进行版本管理，确保使用最新版本

工作流程

前置步骤：文档检查

1. 检查需求文档：

• 确认./项目文档/需求文档/目录下是否存在PDR需求文档
• 如果不存在，自动执行项目需求分析工作流

1. 检查架构文档：

• 确认./项目文档/技术文档/目录下是否存在框架设计文档
• 如果不存在，自动执行框架设计工作流

1. 读取相关文档：

• 读取PDR需求文档，了解项目的功能需求、非功能需求和技术栈偏好
• 读取框架设计文档，了解系统架构、模块划分和技术选型

第一步：API设计准备

1. 设计目标确认：

• 根据需求文档和架构文档，分析API设计的最佳标准和规范
• 优先选择RESTful规范，确保API设计符合行业最佳实践
• 明确API设计的核心目标：高性能、高可靠性、易于扩展和维护
• 基于架构文档中的技术栈选择，确定API设计的技术方向

1. API范围界定：

• 根据需求文档和架构文档，确定API的覆盖范围
• 明确需要设计的API模块和功能点
• 制定API设计的优先级和时间计划

1. 技术约束确认：

• 根据架构文档，确定API设计的技术约束和限制
• 确认数据传输格式、认证方式等技术细节
• 了解系统的性能和安全要求

第二步：API设计

1. RESTful API设计：

• 设计符合RESTful规范的API端点
• 确定HTTP方法、URL路径、请求参数和响应格式
• 设计API的错误处理机制和状态码

1. 数据模型设计：

• 根据需求文档，设计数据模型和数据结构
• 确定数据字段、类型、约束和关系
• 设计数据的验证规则和默认值

1. API文档结构设计：

• 设计API文档的结构和组织方式
• 确定文档的格式和内容要求
• 设计API示例和使用说明

第三步：API规则制定

1. 命名规范：

• 制定API端点、参数、字段的命名规范
• 确保命名的一致性和可读性
• 避免使用模糊或歧义的命名

1. 数据格式规范：

• 制定请求和响应的数据格式规范
• 确定JSON结构、字段类型和格式要求
• 设计数据验证和错误处理的标准格式

1. 认证授权规范：

• 制定API的认证和授权机制
• 确定访问控制策略和权限管理
• 设计安全的API调用流程

1. 版本管理规范：

• 制定API版本管理策略
• 设计版本控制的实现方式
• 确保API的向后兼容性

第四步：API文档生成

1. 文档内容编写：

• 根据设计结果，编写详细的API规则文档
• 确保文档包含：API设计原则、数据模型、API端点、请求响应示例、错误处理等关键信息
• 对文档内容进行审核和校对

1. 文档格式优化：

• 优化文档的格式和结构，提高可读性
• 添加目录、索引和导航，方便查阅
• 确保文档的一致性和准确性

1. 文档确认：

• 根据需求文档和架构文档，对API规则文档进行审核和确认
• 确保文档内容准确反映API设计的要求和规范
• 验证文档的完整性和一致性，确保符合行业标准

执行建议

1. 系统化设计：采用结构化的方法进行API设计，确保不遗漏关键环节
2. 技术与业务结合：基于需求文档和架构文档，平衡技术可行性和业务需求，提供合理的API设计方案
3. 文档质量：确保API规则文档内容完整、准确、清晰，便于前后端开发团队理解和遵守
4. 风险识别：在API设计过程中识别潜在的风险和挑战，提前制定应对措施
5. 可扩展性：在设计过程中优先考虑API的可扩展性，为未来的功能扩展预留空间
6. 安全性：确保API设计符合安全最佳实践，防止常见的安全漏洞
7. 一致性：保持API设计的一致性，确保命名、格式和行为的统一
8. 标准遵循：严格遵循RESTful规范和行业最佳实践，确保API设计的专业性和可靠性
9. 性能优化：在API设计中考虑性能因素，确保系统的响应速度和吞吐量
10. 可维护性：设计清晰的API结构和文档，确保系统易于维护和更新

成功标准

• API规则文档完整，包含所有必要的设计内容
• API设计符合RESTful规范和最佳实践
• 数据模型设计合理，满足业务需求
• 前后端开发团队认可并遵守API规则
• API设计具有良好的可扩展性和安全性
• 文档格式规范，内容清晰易读

失败处理

• 如果需求文档或架构文档不存在，自动执行相应的工作流
• 如果API设计过程中遇到技术难题，记录问题并寻求解决方案
• 如果API设计不符合要求，重新进行设计直到满足标准
• 如果遇到其他异常情况，记录问题并采取相应的应对措施

输出成果

1. 完整的API规则文档（包含API设计原则、数据模型、API端点、请求响应示例、错误处理等关键信息） - 保存至./项目文档/技术文档/目录
2. API设计规范文档（包含命名规范、数据格式规范、认证授权规范、版本管理规范等） - 保存至./项目文档/技术文档/目录

记住，一个优秀的API规则文档是前后端开发的重要指南。通过系统化的流程，确保设计出符合标准、易于理解和使用的API规则，为项目的顺利开发和维护提供坚实的基础。