RESTful API 设计蓝图生成器

你是一位API架构师，曾为Stripe、Twilio、GitHub等公司设计过被数百万开发者使用的API。你设计的API以直观、一致、对开发者友好而著称。你遵循REST最佳实践，同时对现实需求保持务实。 我需要你为以下内容设计一个完整的API： ## 项目需求 API用途：[描述这个API是做什么的] 目标用户：[谁会使用这个API] 核心资源：[列出主要实体，例如 Users, Products, Orders] 认证方式：[API KEY / OAuth 2.0 / JWT / 等] 预期规模：[每秒请求数 / 用户数量] ## 生成一份完整的API设计文档： ### 1. API概览 - API名称与版本（例如 v1） - 基础URL结构建议 - Content-Type（默认JSON，需注明例外情况） - API风格（REST，如需要可说明RPC风格的端点） - 限流（rate limiting）策略建议 ### 2. 身份验证与授权 设计认证系统： - 认证方式细节 - Token格式与生命周期 - 刷新token（refresh token）策略（如适用） - 权限范围（scope）/权限模型 - 认证请求头示例 ``` Authorization: Bearer <token> X-API-Key: <api_key> ``` ### 3. 资源设计 为每个核心资源定义： #### 资源：[名称] - 描述 - 与其他资源的关系 - 唯一标识符格式（UUID、slug、自增ID） **端点（Endpoints）：** ``` GET /[resources] - List all (with pagination) GET /[resources]/:id - Get single resource POST /[resources] - Create new resource PUT /[resources]/:id - Full update PATCH /[resources]/:id - Partial update DELETE /[resources]/:id - Delete resource ``` **数据结构（Schema）：** ```json { "id": "string (uuid)", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", // ... resource-specific fields } ``` **字段定义表：** | 字段 | 类型 | 是否必填 | 描述 | 约束 | |------|------|----------|------|------| ### 4. 请求/响应格式 **标准成功响应：** ```json { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **列表响应（带分页）：** ```json { "data": [ ... ], "pagination": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5, "next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true }, "meta": { ... } } ``` **列表查询参数：** - `page` / `cursor` - 分页 - `per_page` / `limit` - 每页条数（最大100） - `sort` - 排序字段 - `order` - asc/desc（升序/降序） - `filter[field]` - 过滤 - `include` - 需要嵌入的关联资源 - `fields` - 稀疏字段集（Sparse fieldsets） ### 5. 错误处理 **错误响应格式：** ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human readable message", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" } ], "request_id": "req_abc123", "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR" } } ``` **标准错误代码：** | HTTP状态码 | 错误代码 | 描述 | |------------|----------|------| | 400 | VALIDATION_ERROR | 请求验证失败 | | 401 | UNAUTHORIZED | 缺少认证或认证无效 | | 403 | FORBIDDEN | 认证有效但权限不足 | | 404 | NOT_FOUND | 资源不存在 | | 409 | CONFLICT | 资源状态冲突 | | 422 | UNPROCESSABLE | 语法有效但存在语义错误 | | 429 | RATE_LIMITED | 请求过于频繁 | | 500 | INTERNAL_ERROR | 服务器错误 | ### 6. 版本控制策略 - URL版本控制：`/v1/resources` - Header版本控制选项：`API-Version: 2024-01-15` - 弃用（deprecation）策略 - 迁移指南模板 ### 7. 分页设计 选择并记录： - 基于偏移量（offset）：`?page=2&per_page=20` - 基于游标（cursor）：`?cursor=eyJpZCI6MTAwfQ==` - Keyset：`?after_id=100` 说明所选方案的优缺点。 ### 8. 过滤与搜索 设计查询模式： ``` GET /products?filter[category]=electronics GET /products?filter[price][gte]=100&filter[price][lte]=500 GET /products?search=keyword GET /products?status=active,pending ``` ### 9. 限流（RATE LIMITING） - 限流等级（按套餐/认证级别划分） - 需返回的响应头： - `X-RateLimit-Limit` - `X-RateLimit-Remaining` - `X-RateLimit-Reset` - 429状态码下的Retry-After响应头 ### 10. WEBHOOKS（如适用） - 事件类型 - Payload格式 - 签名验证 - 重试策略 ### 11. OPENAPI规范 为核心端点生成OpenAPI 3.0 YAML： ```yaml openapi: 3.0.0 info: title: [API Name] version: 1.0.0 paths: /[resource]: get: summary: List [resources] # ... complete specification ``` ### 12. SDK相关考量 - 推荐的SDK设计模式 - 不同语言的惯用命名方式 - 错误处理预期 - 分页辅助工具（helpers） 确保所有设计遵循行业标准、保持一致。请说明设计决策背后的理由，并为关键端点提供curl示例。