Spring Boot+Vue全栈应用开发实践 课件16 RESTful API 设计原则

罗荣良RESTfulAPI设计原则本节学习目标1.理解REST架构风格的核心理念2.掌握API设计的“名词”与“动词”规则3.熟练运用HTTP标准状态码(200,400,401,500)4.学会设计清晰、规范、易扩展的URL路径5.了解API版本控制与过滤排序规范痛点引入：API的“方言”时代API混乱的命名：/getUser,/saveUser,/delete_user,/updateUserByIdAPI规范命名：/users(GET,POST,PUT,DELETE)文字：没有标准，前端后端对接就是灾难。规范意识与工匠精神什么是REST？全称：RepresentationalStateTransfer(表现层状态转换)本质：一种软件架构风格，而非标准。核心：面向资源(Resource)编程。定义：网络上的一个实体(用户、图片、订单)。标识：使用URI(统一资源标识符)指向资源。规则：URI中只包含名词，不包含动词。❌/getAllStudents✅/students核心概念一：资源(Resources)核心概念二：动作(Verbs)既然URL里没有动词，怎么操作资源？答案：使用HTTP方法。GET->查询(Read)POST->新增(Create)PUT->修改(Update)DELETE->删除(Delete)CRUD映射对照表让我们来看这张对照表，这一页非常重要。要查询所有学生时，发送GET请求到/students。要查询ID为1的学生时，发送GET请求到/students/1。要新增一个学生时，发送POST请求到/students，数据放在Body里。要删除ID为1的学生时，发送DELETE请求到/students/1。URL非常干净，全是名词。动作全藏在HTTPHeader的Method里URL设计最佳实践1.使用复数名词：/users比/user好。2.层级结构：/users/1/orders(查询1号用户的订单)。3.连字符：使用-而不是_(如/student-cards)。4.小写字母：避免大小写混用。核心概念三：状态码(StatusCodes)状态码是服务器对客户端的“心情表达”。2xx(成功)：200OK(通用成功)201Created(创建成功)204NoContent(删除成功，无返回)错误状态码：4xx(客户端锅)400BadRequest：参数错了401Unauthorized：没登录403Forbidden：登录了但没权限404NotFound：资源不存在405MethodNotAllowed：方法用错了(如对GET接口发POST)500InternalServerError：服务器代码报错(Bug)502BadGateway：网关错误503ServiceUnavailable：服务不可用(超载/维护)错误状态码：5xx(服务器锅)进阶：过滤、分页与排序不要改变URL的路径，使用Query参数。❌/getActiveUsers✅/users?status=active✅/users?page=1&size=10✅/users?sort=age,desc进阶：版本控制(Versioning)为什么要版本控制？防止破坏现有客户端。方法一(推荐)：URL路径/api/v1/users方法二：HeaderAccept:application/pany.v1+json幂等性：操作一次和操作N次效果一样。安全的:GET(只读，不管几次都一样)幂等性:PUT,DELETE(删一次和删十次，结果都是没了)非幂等性:POST(点两次创建两个，危险！)安全性与幂等性(Idempotency)统一响应结构回顾结合REST，我们的JSON结构应该是：{"code":200,(业务码)"msg":"success","data":{...}}注意：HTTP状态码用于协议层，JS