业务 API 契约设计

原名：api-design-principles

在开发前统一资源、请求体、错误、分页和版本规则，让接口调用有明确契约。

中文 Skills 技能说明

OPC 产品准备连接桌面端或合作系统时，可让产品经理与 API 测试工程师先整理接口规范。提供业务流程、调用方、权限边界和既有返回格式，技能比较 REST 与 GraphQL 的适用条件，交付资源定义、请求响应示例和验收清单。保留现有兼容要求，不随意改地址或把敏感权限放入 URL。此技能生成设计草稿，不会自动开放 CEOFans 私有接口；实现和契约测试需授权代码环境，鉴权、数据范围及上线须人工审核。

上游能力依据

上游原始适用说明：Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

上游 SKILL.md 主要章节（保留原文标题）：

When to Use This Skill
Core Concepts
1. RESTful Design Principles
2. GraphQL Design Principles
3. API Versioning Strategies
Detailed patterns and worked examples
Best Practices
REST APIs
GraphQL APIs
Common Pitfalls

使用边界

先读取项目约定、依赖版本和现有测试，再提出最小改动。写文件、运行脚本、提交代码或发布前应检查差异并保留回退路径。

作者、翻译与许可证

原作者: Seth Hobson（wshobson）与 agents contributors
中文翻译: CEOFans翻译
许可证: MIT
上游来源: https://github.com/wshobson/agents/tree/46891e7e60da0e52baf1050b7b6391b64e84c6d9/plugins/backend-development/skills/api-design-principles

适用范围

平台：linux、macos、windows；标签：架构与规划、业务 API 契约设计、开源技能

安全提示

基础静态扫描不等于绝对安全。技能可能调用命令、浏览器、云服务或本地文件，请在最小权限环境中使用，高风险操作必须人工确认。

如发现侵权、许可证或安全问题，可在本页前台提交投诉，管理员复核后可立即下架。