api-design-golisted

# Go API 设计专家 使用 Go 设计高质量 HTTP API：$ARGUMENTS --- ## 1. RESTful 设计原则 ### URL 设计规范 ``` # 资源命名（名词复数） GET /users # 列表 POST /users # 创建 GET /users/{id} # 获取 PUT /users/{id} # 全量更新 PATCH /users/{id} # 部分更新 DELETE /users/{id} # 删除 # 子资源 GET /users/{id}/orders # 用户的订单 # 正确的搜索/过滤 GET /users?status=active&role=admin # 批量操作（使用动作资源） POST /users/bulk-delete POST /orders/batch ``` ### HTTP 方法语义 | 方法 | 幂等 | 安全 | 用途 | |------|------|------|------| | GET | Y | Y | 获取资源 | | HEAD | Y | Y | 获取元信息 | | OPTIONS | Y | Y | 获取支持的方法 | | PUT | Y | N | 全量替换 | | DELETE | Y | N | 删除资源 | | POST | N | N | 创建资源 | | PATCH | N | N | 部分更新 | --- ## 2. 版本控制 - **URL 路径版本（推荐）**：`/api/v1/users`，路由注册 `r.PathPrefix("/api/v1").Subrouter()` - **Header 版本**：`API-Version` / `Accept-Version` header + 中间件注入 context - **版本弃用**：设置 `Deprecation: true` + `Sunset` + `Link: successor-version` 响应头 --- ## 3. 分页策略 ### 游标分页（推荐用于大数据集） - `CursorPage[T]` 结构：Items + NextCursor + HasMore - 游标编码：base64 of `{ID, CreatedAt}` JSON - 数据库查询：`WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC LIMIT N+1` ### 偏移分页（仅用于小数据集） - `OffsetPage[T]` 结构：Items + Total + Page + PageSize + TotalPages - 数据库查询：`LIMIT $1 OFFSET $2` + 单独 COUNT 查询 ### 分页选择指南 | 场景 | 推荐方式 | 原因 | |------|---------|------| | 实时数据流 | 游标 | 数据变化不会导致重复/遗漏 | | 大数据集 (>10K) | 游标 | 性能稳定，O(1) | | 静态小数据集 | 偏移 | 支持跳页 | | 搜索结果 | 偏移 | 用户习惯跳页 | --- ## 4. 错误处理 - **RFC 7807 Problem Details*