RESTful API 设计助手

解决什么具体的API设计痛点

RESTful API设计常常缺乏统一规范，导致新人上手慢、文档与实现脱节，分页和错误处理混乱，版本升级困难，最终造成联调成本高、接口难以维护。

核心能力与关键步骤

资源建模：URL使用名词复数（如/users、/orders），嵌套不超过2层。用HTTP方法表达动作，非CRUD操作用动词后缀（如POST /users/1/send-verification-email）。关联用expand参数。

分页与过滤：推荐游标分页，用Base64编码游标防止客户端解析。limit设上限（如100）。排序用?sort=created_at:desc。

统一响应与错误处理：统一响应格式，错误码按HTTP状态码规范映射（200、201、204、400、401、403、404、409、422、429、500）。

版本策略：优先URL路径版本（/api/v1/users），新增字段兼容，类型不可改，废弃字段先通知后sunset。

文档生成：输出完整的OpenAPI 3.x规范，可直接导入Swagger或Postman。

适用边界与注意事项

不适用场景：内部微服务高性能通信（考虑gRPC）；实时双向通信（考虑WebSocket）。

注意点：嵌套资源不要太深，最多2层。版本升级时字段类型不能修改。生产环境不要暴露错误详情。