api-design-principles

概览

什么是 api-design-principles？

api-design-principles 是一个面向 API 开发团队的复用技能，帮助构建直观、可扩展且易维护的 REST 或 GraphQL API。它提供实用的检查清单、代码模板和参考指南，助力您在实现前设计、审查和规范 API。

谁应该使用此技能？

• 设计新 REST 或 GraphQL API 的后端/API 开发者
• 建立或审查 API 设计标准的团队
• 进行实现前 API 审查的架构师和技术负责人
• 在 REST 和 GraphQL 之间迁移的任何人

解决的问题

• 确保一致且开发者友好的 API 设计
• 通过早期发现问题减少错误和返工
• 提供即用型最佳实践模板和检查清单
• 支持 REST 和 GraphQL 两种工作流程

使用方法

安装步骤

1. 使用以下命令将技能添加到您的代理或项目中：

   npx skills add https://github.com/wshobson/agents --skill api-design-principles
   

2. 从 SKILL.md 文件开始，了解技能的总体目的和使用场景。

关键文件和文件夹

• assets/api-design-checklist.md：全面的实现前检查清单，涵盖资源设计、HTTP 方法、状态码、分页、过滤、版本控制和错误处理。
• assets/rest-api-template.py：生产级 FastAPI 模板，实施 REST API 的最佳实践，包括分页、过滤和错误处理。
• references/graphql-schema-design.md：模块化、易维护的 GraphQL 模式设计模式和示例。
• references/rest-best-practices.md：关于 REST API URL 结构、HTTP 方法、状态码和查询参数使用的实用建议。

适应技能

• 审查并调整提供的检查清单和模板，以符合您团队的规范和技术栈。
• 在 API 设计审查中使用检查清单，确保一致性和质量。
• 在启动新 API 项目或重构现有端点时参考模板。

常见问题

api-design-principles 与其他 API 指南有何不同？

api-design-principles 结合了可操作的检查清单、真实代码模板和 REST 及 GraphQL 的参考指南，使您能轻松将最佳实践直接应用到工作流程中。

我可以同时用于 REST 和 GraphQL API 吗？

可以。该技能包含 REST（检查清单、FastAPI 模板、最佳实践）和 GraphQL（模式设计模式、模块化策略）的资源。

如何快速入门？

安装技能后，阅读 SKILL.md 和 assets/api-design-checklist.md，获得指导流程。使用 FastAPI 模板或 GraphQL 模式作为您 API 的起点。

哪里可以找到更多示例或参考资料？

浏览 assets/ 和 references/ 文件夹，获取更多模板和最佳实践文档。打开文件标签页，查看完整文件树，包括嵌套的参考和辅助脚本。

api-design-principles 适合生产项目吗？

适合。提供的模板和检查清单针对真实世界的 API 开发设计，可根据组织需求进行调整和定制。