场景

订单接口从 /getOrder、/updateOrder 演变出大量动作名后，调用方难以预测路径、状态码和重试行为，网关缓存与监控也无法统一。

原理

REST 把服务能力抽象为资源，使用 URI 表达身份、HTTP 方法表达操作语义。GET 应安全且幂等，PUT 表示整体替换并应幂等，PATCH 表示局部修改，POST 常用于创建或非幂等命令。状态码与响应体共同描述结果。

设计步骤

先识别订单、支付等稳定名词并设计层级；再定义读取、创建、修改、删除的前置条件；为分页、排序和过滤采用统一查询参数；错误体包含稳定错误码、可读消息和追踪号；最后用 OpenAPI 固化契约并做兼容性测试。

权衡

纯粹资源化并不适合所有业务动作，例如退款审批可建成子资源，也可采用命令端点。前者语义统一但模型增多，后者直观却容易退化为 RPC。HATEOAS 解耦流程，但客户端实现和团队成本较高。

实践建议

不要把数据库表直接暴露为 API；创建接口返回 201 与 Location，异步处理可返回 202；幂等写入支持业务幂等键；版本升级优先做向后兼容。对 400、401、403、404、409、429 明确区分，能显著降低联调和排障成本。

落地检查

上线前还应做一次桌面演练：准备正常、边界、超时、重复与恶意输入，确认系统的返回、日志和指标彼此对应；在预发布环境模拟依赖不可用、进程重启和配置回滚，验证降级路径不会放大故障。上线时采用小流量观察，提前定义停止条件与负责人。稳定后复盘真实数据，删除没有收益的复杂度，并把新发现的约束补进测试、监控和设计记录，使方案能够随业务持续演进，而不是停留在一次性评审结论。