1. 用名词复数命名资源，别用动词
URL应该指向资源，不是动作。GET /users比GET /getUserList干净得多。新增用POST /users，删除用DELETE /users/1，更新用PUT /users/1。动词留给HTTP方法，URL只负责定位。别在路径里出现add、delete、update这些词，那是RPC风格，不是REST。
2. 版本号放URL里，别藏Header
/api/v1/users比在Header里塞Accept: application/vnd.api+json;version=1.0直观一百倍。调试时一眼看出调的是哪个版本，日志里也清晰。版本升级时，v1和v2可以并行跑，老客户端不受影响。别怕URL变长，可读性比简洁重要。
3. HTTP方法要用对，别全用POST
GET查、POST增、PUT改、PATCH局部改、DELETE删。GET必须幂等且无副作用，别用GET做删除。PUT是全量替换，PATCH是局部更新。很多团队图省事全用POST，结果缓存没法用，语义一团糟。方法用对，接口自解释。
4. 状态码要精准，别全返回200
200成功，201创建成功，204删除成功无内容，400参数错误，401未认证，403无权限，404不存在，409冲突，500服务器错误。别把错误塞在200的body里，那会让监控和网关无法正确判断。状态码是第一层错误标识，body是第二层细节。
5. 统一响应结构，别今天一个样明天一个样
建议格式：{ "code": 0, "message": "success", "data": {...} }。code为0表示业务成功，非0表示业务错误。HTTP状态码管传输层，code管业务层。前端只需判断一次，不用每个接口写一套解析逻辑。分页数据放data.list和data.total，别一会儿叫items一会儿叫rows。
6. 错误信息要给人看，别甩堆栈
"message": "用户名已存在"比"message": "SQLIntegrityConstraintViolationException"有用得多。错误信息要能让前端直接弹给用户，也要能让开发快速定位。敏感信息如SQL、堆栈、内部IP，绝不能暴露给客户端。日志里记详细，响应里给摘要。
7. 分页、排序、过滤要标准化
分页统一用page和size，或者offset和limit，别这个接口用pageNum，那个用current。排序用sort=created_at,desc，过滤用status=active&type=premium。参数名统一，前端不用记两套。默认分页大小设个上限，防止有人传size=100000拖垮数据库。
8. 幂等性设计，别让重复请求出大事
POST创建订单，网络超时客户端重试，结果生成两笔订单。解决办法：客户端传唯一请求ID，服务端用Redis或数据库唯一索引去重。PUT和DELETE天然幂等，POST必须加防重。支付、下单、扣库存，这些接口不做幂等，迟早出事故。
9. 安全鉴权别偷懒，Token放Header
用Authorization: Bearer <token>，别把token放URL参数里，那会留在日志和浏览器历史里。HTTPS必须上，敏感字段加密传输。接口限流防刷，关键操作加验证码。权限校验在网关或拦截器统一做，别每个接口写一遍。
10. 文档和契约要同步更新
用Swagger或OpenAPI自动生成文档，代码改了文档跟着变。接口定义就是契约，前端按契约写，后端按契约实现。字段类型、是否必填、示例值，写清楚。别让前端靠猜，猜错了联调时互相甩锅。契约先行，并行开发，效率翻倍。
接口设计没有银弹，但这10条能帮你避开八成坑。规矩定好，团队照做，联调时间砍半，线上故障少一半。别等到系统烂了才想起规范，那时候改的成本，够你重写三遍。
