接口设计原则#

核心原则：

1. RESTful：GET查/POST增/PUT改/DELETE删
2. 统一响应：{code, message, data}
3. 版本控制：URL(/v1/)或Header
4. 幂等性：查询天然幂等，写操作需设计
5. 安全：鉴权/限流/参数校验/SQL注入防护

我在设计接口时主要遵循五个原则。第一是 RESTful 语义化，GET 用于查询、POST 用于新增、PUT 用于修改、DELETE 用于删除，不要所有接口都用 POST。第二是统一响应格式，所有接口都返回 {code, message, data} 的标准结构，方便前端统一处理。第三是版本管理，URL 里加版本号比如 /v1/users，保证接口升级时老版本不受影响。第四是幂等性设计，查询天然幂等，写操作需要通过唯一请求 ID 或数据库唯一索引来防止重复提交。第五是安全防护，包括接口鉴权、限流、参数校验和 SQL 注入防护。另外分页方面，我推荐用游标分页替代 offset 分页，因为 offset 在深分页时性能很差，比如 offset 十万时 MySQL 要扫描十万零 N 行然后丢弃前面的，而游标方式用 WHERE id > lastId LIMIT N 直接定位，效率高得多。

追问方向：

• “版本管理怎么做？”→ URL 路径加版本号（/v1/users）最直观，或者用 Header（Accept-Version: v2）；旧版本保持兼容运行一段时间，新功能只加到新版本，通过网关路由不同版本
• “接口幂等怎么设计？”→ 查询天然幂等；写操作通过唯一请求 ID（客户端生成 UUID 放 Header）+ 服务端 Redis SETNX 去重，或者用数据库唯一索引兜底防止重复插入
• “分页用 offset 还是 cursor？”→ offset 简单但深分页性能差（MySQL 要扫描 offset+limit 行再丢弃前面的）；cursor 用 WHERE id > lastId LIMIT N 直接定位效率高，适合无限滚动场景；需要跳页的场景只能用 offset

易错点：

• ❌ 所有接口都用 POST——违反 RESTful
• ❌ 返回 200 就行——不同场景用不同状态码