本项目 API 遵循RESTful架构风格达到Richardson 成熟度模型 Level 2行业标准级别。以下逐条列出证据。一、Richardson 成熟度模型定位Level要求本项目0HTTP 仅作传输单一 URL POST 处理一切已超越1资源导向URL 使用名词标识资源满足2HTTP 动词用 GET/POST/PUT/DELETE 表达操作语义满足3HATEOAS响应中包含超媒体链接引导客户端未实现行业共识Level 2 是绝大多数互联网公司Google、GitHub、Stripe的实际标准。Level 3 仅在超媒体驱动的特殊场景中使用Spring HATEOAS 成本高、收益低。二、原则一URL 使用名词不用动词规范URL 应标识资源是什么不应描述对资源做什么。证据—controller/UserController.java第 14 行RequestMapping(/api/users)// ✓ 名词 users非 getUsers 或 doQuery对比反面案例非 RESTful本项目RESTful/api/getUsersGET /api/users/api/addUserPOST /api/users/api/updateUserPUT /api/users/{id}/api/deleteUser?id1DELETE /api/users/{id}三、原则二HTTP 方法表达操作语义规范用 HTTP 方法区分操作而非在 URL 中体现。证据—controller/UserController.java第 23–68 行GetMapping// GET → 查询安全、幂等GetMapping(/{id})// GET → 查询单个安全、幂等PostMapping// POST → 新增非幂等PutMapping(/{id})// PUT → 全量更新幂等DeleteMapping(/{id})// DELETE → 删除幂等幂等性验证方法连续调用 2 次的结果幂等说明GET /api/users返回相同数据是只读POST /api/users新增 2 条记录不同 ID否每次创建新资源PUT /api/users/1第 2 次写入相同字段结果不变是全量替换DELETE /api/users/1第 2 次返回 404是资源已不存在POST 非幂等是正确的——新增操作每次产生新资源这是 RESTful 规范明确允许的。四、原则三HTTP 状态码传达结果规范用 HTTP 状态码而非 body 中的自定义字段告诉客户端操作结果。4.1 代码证据controller/UserController.javareturnResponseEntity.ok(...)// 200 OK — 第 31、40、57、67 行returnResponseEntity.status(201).body(...)// 201 Created — 第 46 行returnResponseEntity.status(404).body(...)// 404 Not Found — 第 38、53、64 行4.2 状态码使用对照场景HTTP 状态码代码行号查询全部成功200 OK第 31 行按 ID 查询成功200 OK第 40 行查询的 ID 不存在404 Not Found第 38 行新增成功201 Created第 46 行更新成功200 OK第 57 行更新的 ID 不存在404 Not Found第 53 行删除成功200 OK第 67 行删除的 ID 不存在404 Not Found第 64 行4.3 验证方法浏览器打开 F12 → Network 标签操作后可见200绿色 — 请求成功201绿色 — 资源已创建404红色 — 资源不存在状态码直接向浏览器、网关、监控系统传达结果无需解析 body。五、原则四无状态Stateless规范服务端不保存客户端会话状态每个请求独立且自包含。证据UserController中无HttpSession、无SessionAttributes、无Cookie 校验每个请求仅依赖 URL 参数和请求体不依赖上一个请求做了什么前端通过 Axios 每次独立发送请求不维持服务端 session// UserController 中没有以下任何代码// HttpSession session;// SessionAttributes// request.getSession()// Cookie cookie;六、原则五资源层级化规范资源的嵌套关系在 URL 中体现。证据/api/users ← 用户集合collection resource /api/users/1 ← 集合中的单个资源item resource单个资源的 ID 使用路径参数PathVariable而非查询参数?id1GetMapping(/{id})// ✓ /api/users/1publicResponseEntity...getById(PathVariableIntegerid)// ✓ 路径参数对比非 RESTfulRESTful本项目/api/users?id1查询参数/api/users/1路径参数/api/users/get?id1动词查询参数/api/users/1名词路径参数七、原则六统一响应格式规范成功和失败使用一致的 JSON 数据结构。证据— 所有接口返回Map.of(message, ..., data, ...)// 成功 — 200 OK{message:success,data:[{id:1,name:白眉鹰王,...}]}// 成功 — 201 Created{message:新增成功,data:{id:7,name:张无忌,...}}// 失败 — 404 Not Found{message:用户不存在,data:null}RestController的作用自动将返回的 Java 对象序列化为 JSON通过 Jackson无需手动调用JSON.stringify。八、合规总结RESTful 原则证据来源结论URL 用名词RequestMapping(/api/users)合规HTTP 方法语义GetMapping/PostMapping/PutMapping/DeleteMapping合规HTTP 状态码ResponseEntity.ok()/status(201)/status(404)合规无状态无 Session / 无 Cookie 依赖合规资源层级/api/users/{id}PathVariable合规统一 JSON 格式RestControllerMap.of(...)合规幂等性GET/PUT/DELETE 幂等POST 非幂等合规HATEOAS未实现超出 Level 2行业可接受结论本项目 API 完全符合 RESTful Level 2 标准达到生产环境可用的设计水平。