编程开发 通用 中文 English API 设计 为 [feature \/ domain] 设计 REST API。目标:一个一致、有文档且经过验证的 API,使其他开发者能够… 生成后的提示词 为 `[feature \/ domain]` 设计 REST API。目标:构建一个一致、有文档且经过验证的 API,使其他开发者能够自信地理解并集成。 ## 步骤 1. **理解领域** - 阅读现有代码库、数据模型以及任何现有 API 路由。识别资源、它们之间的关系以及所需操作。不要凭空设计——让 API 扎根于代码当前的实际行为。 2. **定义资源和路由** - 资源使用基于名词的 URL(`\/users`、`\/projects`),操作使用 HTTP 动词(GET、POST、PUT、PATCH、DELETE),并保持一致的嵌套深度(最多 2 层)。遵循代码库中现有的 API 约定。 3. **设计请求\/响应模式** - 定义带类型的请求体、查询参数和响应结构。在所有端点中使用一致的错误响应格式。为列表端点包含分页。 4. **添加验证和错误处理** - 指定输入验证规则、有意义的错误消息和正确的 HTTP 状态码。记录边界情况:冲突、未找到或未授权时会发生什么。 5. **编写 OpenAPI 规范** - 生成一个有效的 OpenAPI 3.x YAML\/JSON 规范,覆盖所有端点、模式和错误响应。为每个端点包含示例。 6. **验证** - 检查规范能否干净地通过验证(使用 `swagger-cli validate` 或等效工具)。确认路由不会冲突,并且命名始终一致。 ## 验证 - [ ] 每个端点都映射到代码库中存在的真实数据或操作;没有一个是虚构的。 - [ ] URL 基于名词,HTTP 动词承载操作,并且嵌套保持在两层或更少。 - [ ] 分页和错误响应格式在每个列表端点中完全相同。 - [ ] 每个错误情况都标明其状态码,并覆盖冲突、未找到和未授权。 - [ ] 规范能通过仓库自身的验证器干净地验证,并显示输出。 ## 规则 - 绝不要虚构不映射到代码库中实际数据或操作的端点。 - 绝不要使用基于动词的 URL(例如 `\/getUser`)——而应使用 HTTP 动词。 - 保持 API 一致:如果一个列表端点使用 `?page=`,那么所有列表端点都应使用。 - 如果代码库已有 API 约定,请严格遵循它们——不要引入并行风格。 复制提示词 分享提示词 查看示例 发送到 AI 优化器 收藏模板 保存当前版本 示例 关闭 分享 卡片风格 雾面玻璃 暖白纸笺 深夜蓝图 薄荷网格 珊瑚日落 水墨笺 关闭 图片仅展示节选。