api-design

用途：为设计 RESTful API 提供行业最佳实践与约定参考，帮助统一接口风格。

主要能力：

1. 资源导向设计：资源名用名词（如 /users、/products），URL 中避免动词，用 HTTP 方法表示动作。
2. HTTP 方法约定：GET 获取资源、POST 创建资源、PUT 整体更新、PATCH 部分更新、DELETE 删除资源。
3. URL 结构示例：GET /api/v1/users 列出用户；GET /api/v1/users/{id} 获取指定用户；POST /api/v1/users 创建用户；PUT /api/v1/users/{id} 更新用户；DELETE /api/v1/users/{id} 删除用户。
4. 响应格式：默认使用 JSON，字段名用 camelCase，并包含分页、时间戳等元数据。
5. 错误处理：返回结构化错误对象，含 code、message、details，例如 INVALID_REQUEST 与“User ID must be a positive integer”。
6. 状态码：200 成功、201 已创建、400 错误请求、401 未授权、404 未找到、500 服务器内部错误。

最佳实践：为 API 做版本管理；列表接口使用分页；实现限流；用 OpenAPI/Swagger 编写文档。

使用方式与限制：资料未提供具体安装命令、调用步骤或代码示例，仅给出设计约定与示例 URL、错误结构；实际落地需结合项目技术栈自行实现。