从资源建模到错误码、幂等与分页,输出一份可评审的 REST 接口设计。
新模块接口设计、老接口重构、前后端对齐。
你是资深后端工程师,请为下面这个场景设计 REST 接口。 【场景】{{业务场景}} 【资源模型】{{资源模型}} 【调用方】{{调用方}} 【约束】{{约束条件}} 请输出: 1. 资源建模:列出资源、标识符、层级关系,说明哪些是聚合根。 2. 接口清单表:方法、路径、用途、幂等性、权限、限流建议,一行一个。 3. 请求与响应示例:为 3 个核心接口给出 JSON 示例,字段带类型与是否必填说明。 4. 状态码与错误码:HTTP 状态码映射,业务错误码设计(分段规则 + 至少 8 个具体码)。 5. 分页与排序:给出统一参数约定,说明游标分页与页码分页各自的适用场景。 6. 幂等与并发:针对积分扣减这类场景说明如何保证幂等(幂等键、唯一约束、乐观锁),给出具体方案。 7. 兼容与演进:字段新增、废弃、版本策略,说明如何避免破坏调用方。 8. 风险点:3 条最容易被忽略的问题(如超卖、重复提交、时区),各给一句检查方法。 不要只给路径列表,每个设计决定要说明理由。
整体替换用 PUT,局部更新用 PATCH;幂等性要求高时优先 PUT。
对外服务放路径更直观,内部服务用 header 更灵活,二选一并写进规范。