七七八八的接口设计相关问题

1. 接口版本控制策略 (API Versioning Strategy)

核心问题： 当你发布了 V1 版本后，某天需要修改接口字段（比如把 name 拆分为 first_name 和 last_name），如何保证老版本的 App 不会崩溃？

三种主流流派：

URI Path Versioning (推荐):
- 格式: https://api.example.com/v1/users
- 优点: 直观、易于调试、缓存友好。这也是 GitHub, Twitter, Google API 采用的主流方案。
- 落地: 我们在 Gin 的 Router Group 中直接体现：
  
  Go
```
v1 := r.Group("/api/v1")
{
    v1.GET("/users", ...)
}
```
Header Versioning:
- 格式: Header 中添加 Accept: application/vnd.myapi.v1+json
- 优点: URL 干净。
- 缺点: 调试麻烦（浏览器直接访问 URL 看不到结果），CDN 缓存配置复杂。不推荐 MVP 阶段使用。
Query Parameter:
- 格式: /users?version=1
- 评价: 看起来很土，通常不用于 RESTful API。

👉 你的策略： 坚定选择 URI Path Versioning (/api/v1)。只在发生破坏性变更 (Breaking Change) 时才升级到 v2。新增字段不算破坏性变更，不需要升级版本。

很多新手只会用 GET 和 POST。企业级 API 必须精准区分以下方法的含义：

方法	语义	幂等性 (Idempotency)	典型场景
GET	获取资源	✅ 是	获取文章列表、详情
POST	新建资源	❌ 否	发布新文章、提交评论
PUT	全量替换资源	✅ 是	修改文章（客户端发送文章的完整 JSON，没传的字段会被置空）
PATCH	局部更新资源	❌ 否 (理论上)	修改文章状态（只传 `{"status": "published"}`，其他字段不变）
DELETE	删除资源	✅ 是	删除文章

⚠️ 重点关注 PUT vs PATCH:

在 Go 语言中实现 PATCH 有点麻烦（因为 Go 的结构体默认值问题，你很难区分用户是传了 0 还是没传这个字段）。

最佳实践: 对于 CMS 这种表单复杂的系统，修改接口首选 PUT (全量)，或者针对特定状态修改提供独立接口（如 POST /articles/:id/publish）。如果必须做 PATCH，DTO 需使用指针类型 *string 来判断是否为 nil。

原则：URL 中只出现名词，不出现动词。

❌ 反例 (RPC 风格 - 不要这么做):
- /api/getUsers
- /api/createUser
- /api/deleteArticle?id=1
✅ 正例 (REST 风格):
- GET /api/v1/users (获取列表)
- POST /api/v1/users (创建)
- DELETE /api/v1/articles/1 (删除 ID 为 1 的文章)

复杂关系的嵌套设计：

你的 CMS 一定会有“文章列表”页面，这个接口是最复杂的。不要为每种查询都写一个新接口，要设计一个通用的查询接口。

最佳实践标准：

分页 (Pagination):
- 使用 page (页码) 和 page_size (每页条数)。
- URL 示例: /articles?page=2&page_size=20
- 注意: 要限制 page_size 的最大值（如 100），防止恶意用户一次请求 100 万条数据把数据库打挂。
排序 (Sorting):
- 使用 sort 参数。- 代表降序，无符号代表升序。
- URL 示例: /articles?sort=-created_at (按创建时间倒序)
- URL 示例: /articles?sort=view_count,-created_at (先按浏览量升序，再按时间倒序)
筛选 (Filtering):
- 直接使用字段名作为参数。
- URL 示例: /articles?category_id=1&status=published

不要永远只返回 200 OK！

前端开发最恨的就是：HTTP 状态码是 200，结果 Body 里写着 {"code": 500, "msg": "Error"}。这会让监控系统失效。

你需要遵守的“HTTP 状态码地图”：

2xx (成功):
- 200 OK: 通用成功。
- 201 Created: 创建成功 (POST 返回)。
- 204 No Content: 删除成功 (DELETE 返回，不带 Body)。
4xx (客户端错误 - 前端背锅):
- 400 Bad Request: 参数校验失败（如邮箱格式不对）。
- 401 Unauthorized: 未登录/Token 过期。
- 403 Forbidden: 登录了，但没权限（如普通用户想删文章）。
- 404 Not Found: 资源不存在。
5xx (服务端错误 - 你背锅):
- 500 Internal Server Error: 代码崩了/数据库挂了。

统一错误响应格式 (JSON Envelope):

无论发生什么错误，Body 必须保持结构一致，方便前端拦截：

JSON

{
  "code": 40001,           // 业务错误码 (你在 pkg/e 定义的)
  "message": "标题已存在",   // 给用户看的提示
  "request_id": "abc-123"  // 方便查日志的 Trace ID
}

概念： 用户因为网络卡顿，连续点击了 3 次“发布文章”按钮，你的系统会创建 1 篇文章还是 3 篇？

如何处理 POST 的幂等性？

对于关键业务（如支付、核心数据创建），通常要求前端在 Header 带一个 Idempotency-Key (UUID)。后端 Redis 记录这个 Key，如果短时间内收到相同的 Key，直接返回上次的结果，不执行数据库插入。

(注：MVP 阶段可以先不做，但面试或者做高可靠系统时必须知道)

请在心中建立这套标准：