Name: 05-api-guidelines
Author: YueGod

Instruction file imported from YueGod/dating-chat-ai-cursor (.cursor/rules/05-api-guidelines.mdc). Copyright stays with the author.

API指南

RESTful API设计

URL结构

使用名词而非动词表示资源端点
使用复数名词表示集合资源
遵循层次化的资源关系
基础URL格式：/api/v1/{resource}

HTTP方法

GET - 获取资源
POST - 创建新资源
PUT - 完全更新资源
PATCH - 部分更新资源
DELETE - 删除资源

响应状态码

200 OK - 成功
201 Created - 资源已创建
204 No Content - 成功但无响应体
400 Bad Request - 无效输入
401 Unauthorized - 需要认证
403 Forbidden - 权限不足
404 Not Found - 资源未找到
500 Internal Server Error - 服务器错误

API文档

Swagger/Knife4J注解

控制器类使用@Api
各个端点使用@ApiOperation
方法参数使用@ApiParam
模型使用@ApiModel和@ApiModelProperty

请求/响应模型

为请求和响应创建专用的DTO类
使用一致的命名：{资源}{动作}Req和{资源}{动作}Resp
在请求DTO上添加验证注解
使用@ApiModelProperty文档化所有属性

响应格式

标准响应结构

{
  "code": "000000",        // 状态码，000000表示成功
  "msg": null, // 状态消息或错误描述
  "data": {         // 实际响应数据（可为空）
    // 响应负载
  }
}

{
  "code": "000500",        // 状态码，0表示成功
  "msg": "服务端异常，请稍候重试", // 状态消息或错误描述
  "data": {         // 实际响应数据（可为空）
    // 响应负载
  }
}

错误处理

自定义异常处理

创建领域特定的异常类
使用@ControllerAdvice实现全局异常处理器
返回一致的错误响应格式
包含适当的HTTP状态码
使用上下文信息记录异常日志

输入验证

使用Bean Validation (JSR-380)注解
为复杂业务规则实现自定义验证器
返回详细的验证错误消息

API版本控制

在URL路径中包含版本：/api/v1/{resource}
至少为前一个版本提供向后兼容性
记录各版本之间的API变更

Install 05-api-guidelines and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

{ "ocm": "1", "id": "yuegod-dating-chat-ai-cursor-05-api-guidelines-rule", "kind": "skill", "name": "05-api-guidelines", "description": "API指南", "publisher": "YueGod", "version": "1.0.0", "capabilities": { "domains": [ "coding", "math" ], "tags": [ "skill-md", "github-cursor-rules" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "API指南" ], "primary": false, "metadata": { "source": { "provider": "github-cursor-rules", "repository": "https://github.com/YueGod/dating-chat-ai-cursor", "path": ".cursor/rules/05-api-guidelines.mdc", "ref": "1dd8df40dcd695213714cf553cbd0f17d356238f", "url": "https://github.com/YueGod/dating-chat-ai-cursor/blob/1dd8df40dcd695213714cf553cbd0f17d356238f/.cursor/rules/05-api-guidelines.mdc", "key": "YueGod/dating-chat-ai-cursor/.cursor/rules/05-api-guidelines.mdc" } }, "instructions": "# API指南\n\n## RESTful API设计\n\n### URL结构\n- 使用名词而非动词表示资源端点\n- 使用复数名词表示集合资源\n- 遵循层次化的资源关系\n- 基础URL格式：`/api/v1/{resource}`\n\n### HTTP方法\n- `GET` - 获取资源\n- `POST` - 创建新资源\n- `PUT` - 完全更新资源\n- `PATCH` - 部分更新资源\n- `DELETE` - 删除资源\n\n### 响应状态码\n- `200 OK` - 成功\n- `201 Created` - 资源已创建\n- `204 No Content` - 成功但无响应体\n- `400 Bad Request` - 无效输入\n- `401 Unauthorized` - 需要认证\n- `403 Forbidden` - 权限不足\n- `404 Not Found` - 资源未找到\n- `500 Internal Server Error` - 服务器错误\n\n## API文档\n\n### Swagger/Knife4J注解\n- 控制器类使用`@Api`\n- 各个端点使用`@ApiOperation`\n- 方法参数使用`@ApiParam`\n- 模型使用`@ApiModel`和`@ApiModelProperty`\n\n### 请求/响应模型\n- 为请求和响应创建专用的DTO类\n- 使用", "cost": { "context_tokens": 313 } }

05-api-guidelines

About