REST API 开发有哪些实用原则？

直接回答

让资源、HTTP方法、状态码和输入输出契约表达真实业务；明确验证、授权、分页、幂等和错误格式，再配可重复测试与文档。Boot能提供Web与序列化工具，但不会替你决定这些契约。“所有接口返回200加一个code”或“把实体全部序列化”都不是通用最佳实践。

讲清原理

读取与写操作分开设计，列表限制规模，错误使用适当状态，敏感字段不进入公开模型。需要幂等的写操作应有业务去重与冲突处理，而不是只依赖HTTP方法名。

请求语法正确、字段约束通过、当前用户有权操作是不同层次。版本演进还要考虑旧客户端、字段默认和兼容窗口，不能在服务端改名后假定自动文档会替所有调用方迁移。

例子与易错点

例如订单创建返回清楚资源标识，重复请求按稳定幂等键识别；无权访问不能伪装成成功列表。先给典型成功、错误与越权路径写契约测试，再补文档示例。

以下为 Java 21 类成员示例，放入同一外部类中使用，依赖 Boot4.1.2 / Framework7.0.10。固定ID仅演示HTTP契约，不保存订单，也未模拟完整认证与幂等创建。

record CreatedOrder(long id) { }
@org.springframework.web.bind.annotation.RestController
static class OrdersApi {
    @org.springframework.web.bind.annotation.PostMapping("/orders")
    org.springframework.http.ResponseEntity<CreatedOrder> create() {
        return org.springframework.http.ResponseEntity.created(java.net.URI.create("/orders/7"))
            .body(new CreatedOrder(7));
    }
}

相关题：第 16 题、第 26 题、第 29 题、第 57 题。