接手一个号称“RESTful”的SpringBoot服务往往从URL就能看出灾难的雏形/saveUser、/getUserById、/updateUser、/deleteUser动词满天飞名词无处藏。你以为在用RESTful其实只是把HTTP当作了一个能跑通的管道顺手把方法调用焊死在URL上。REST的核心在于资源与状态转移而不是把服务端的方法名翻译成英文路径。真正的问题是很多人从未理解“资源”的含义就开始写RestController了。动词与HTTP方法谁才是主角用SpringBoot写RESTful最典型的误区就是把HTTP方法当成装饰品把操作动词塞进路径。有人会说“POST也能做事为什么非得用DELETE”——这不是换不换方法名的问题而是语义混乱会直接导致客户端无法安全预测行为。一个GET /api/user?id1和一个POST /api/user/query并存前端调用时无所适从网关做缓存时一脸茫然监控系统统计时更是雾里看花。正确的姿势是让资源名保持名词复数让HTTP方法表达动作GET /users取列表POST /users新建DELETE /users/{id}删除。这不是洁癖而是契约清晰带来的工程效率。有人反驳我用的就是GET但业务复杂查询条件一大堆写进Query String又长又丑。于是他们退回POST甚至发明了POST /api/search/advanced。复杂查询不是滥用POST的理由而是提醒你该设计查询对象和分页参数了。SpringBoot里你完全可以用一个DTO来接收查询条件再配合RequestParam或RequestBody做过滤。关键是别让“方便”二字掩盖了设计上的懒惰。返回体设计裸奔或裹粽子都是悲剧第二个高频误区是返回体结构的两极分化。一种是裸奔派所有接口直接返回User、ListOrder压根没有统一的响应包装。前端拿到数据后得靠HTTP状态码猜成败一旦服务端抛出业务异常返回内容变成一段HTML错误页前端哭都哭不出来。另一种是裹粽子派所有接口都套上三层壳{code, message, data}甚至{status, error, errors, data}连成功响应也要塞一个message: 操作成功。没有约定的包装就是垃圾但有约定的包装也未必是佳话。关键在于包装必须与错误码体系配套并且要能区分系统异常、业务异常和参数异常。更隐蔽的问题是很多团队把HttpStatus和自定义code搞成两套话语体系。明明返回200body里却写着code: 500前端就不得不双判断。真正舒服的做法是让HTTP状态码承担传输层语义让body里的code承载业务层语义两者要对应但别混为一谈。比如创建成功返回201业务上不允许删除返回409参数不对返回400——SpringBoot里用ResponseEntity或ResponseStatus就能干净地控制这一切。你不需要处处用全局异常处理器但必须有统一的错误体模板。异常处理try-catch是万能的很多新手在Controller里写满try-catch然后catch到Exception后返回一个Map。这既让代码肿胀又让异常信息随意泄露。Controller里不该有try-catch而应该让异常处理器去接管。SpringBoot提供了RestControllerAdvice这正是为了把“捕获异常”和“转换成响应”这件事集中化。没有它你的服务就像一个没有保安的大楼每个房间都要自己防贼。但RestControllerAdvice也不是银弹。太多人把所有异常捕获后统一返回500前端只能看到“服务器内部错误”几个字。你要分门别类地处理MethodArgumentNotValidException该给400字段错误明细BusinessException该给具体业务码NoResourceFoundException该给404。更别忽略HttpMessageNotReadableExceptionJSON解析失败时前端需要知道是哪个字段类型不对。异常处理器的粒度决定了你的API好不好调试。参数校验别让异常替你打工RESTful服务里参数校验经常被放到Service层甚至Controller层手工判断if (user.getName() null) { throw ... }。这种代码写多了你会发现自己成了if-else的搬运工。SpringBoot集成Bean Validation是那么自然的事在DTO字段上标NotBlank、Email、Min再用Valid或Validated触发让校验框架替你挡掉第一道垃圾请求。这不仅是代码量减小的问题更是可读性与一致性的提升。有人觉得参数校验是小事数据库NotNull约束就能兜底。但RESTful服务是系统的门面烂参数必须在门口就拦住而不是等它穿透到数据库层再报错。更推荐的做法是把校验错误信息整理成列表用统一的结构回给客户端。别忘了SpringBoot的Validated还支持分组校验可以针对创建和更新场景分别定义规则。把自己从重复判断中解放出来你就有精力处理真正复杂的业务逻辑了。分页与过滤一个List走天下很多接口张嘴就返回ListUser也不管有多少数据。等数据量到了十万接口超时前端卡死运维骂娘。不提供分页的查询接口是不负责任的。Spring Data提供了Pageable抽象你完全可以在Controller里接一个Pageable参数用Page类型返回。但这里也有个误区把Page对象整个序列化给前端前端被迫解析totalPages、totalElements、number、size——太臃肿。更好的做法是返回一个轻量分页响应{items: [], page: 1, size: 20, total: 100}。别让Pageable成为一把万能钥匙你要显式约束size的最大值防止有人一次取一万条。至于过滤别靠拼SQL字符串更别用RequestParam MapString, String来接收所有条件那是灾难。设计一个明确的过滤对象配合JPA Specifications或MyBatis的Provider让你的查询逻辑可维护、可测试、可预测。版本管理URL里的v1是堕落的开始API需要演进版本管理就绕不开。最常见的俗手是在URL上写/api/v1/users、/api/v2/users。这么做简单粗暴但一旦你开始在每个URL里写版本号就相当于告诉客户端你们必须跟着我的升级节奏走。更好的选择是用Header或MediaType来协商版本比如Accept: application/json;version2。不过要承认在SpringBoot里实现自定义MediaType版本协商需要多写一点配置很多人就放弃了。实际上RESTful的版本策略不是技术问题而是业务契约问题。你的下游是外部开发者那就要保守如果是内部前后端完全可以激进一点把老接口直接改掉而不是平行新增v2。有一种折中方法在URL里保留版本号但只保留一个主版本同时用兼容性策略处理微小变化。关键是别同时维护五六个版本那会让代码里充满if (version 1)的分支最终变成一锅粥。没有一个版本策略是永恒的但你应该明确地“选择不兼容”或“选择兼容”而不是任由接口随代码更新而漂移。文档与测试不做就等着被怼接口写好了没有文档前端只能看着你的代码猜。SpringFox时代大家用Swagger注解后来SpringDoc出现但注解不是越多越好你完全可以通过openapi规范生成器来约束文档即契约。SpringBoot的springdoc-openapi可以扫描RestController自动生成文档还能配合注解补充字段说明。但更要紧的是让文档与实际行为保持一致否则文档就是谎言。很多团队的Swagger文档停留在第一次启动时生成的状态代码改了十次文档还在展示旧接口。解决之道是把接口测试做成自动化契约测试用MockMvc或TestRestTemplate验证响应结构再生成文档——凡是测试覆盖不到的接口文档就不可信。说到测试很多人写SpringBoot服务只做启动即成功测试真正的业务逻辑全靠人肉跑。不写测试的RESTful服务就是定时炸弹。你至少要为每个Controller写一个集成测试请求正确时返回200且body不空参数错误时返回400带错误码未登录时返回401。用WebMvcTest配合MockBean可以快速实现成本没那么高。别用“没时间”来推脱一个接口在交付后因为回归问题返工耗费的时间是写测试的十倍。监控与日志服务上线盲人摸象最后一个陷阱是上线后服务崩了你靠看前端报错来猜原因。RESTful服务必须自带可观测性否则就是黑盒。SpringBoot有Actuator添加依赖后就能提供/actuator/health、/actuator/metrics等端点。但很多人只是加了个依赖然后从不看指标。健康检查不能只返回“UP”就完事你应该自定义可用性探针比如检查数据库连接、消息队列、磁盘空间。更关键的是日志每个请求应该有一个traceId贯穿整个链路日志里要记录请求方法、路径、状态码、耗时。SpringBoot的RestControllerAdvice里也可以记录异常日志但别把堆栈打太多否则日志系统会爆。RESTful服务的性能问题往往发生在没人关注的地方N1查询、大对象序列化、连接池耗尽。没有监控指标就没有优化方向。你可以用Micrometer把请求的Timed注解或自动配置的http.server.requests指标接入Prometheus再配Grafana看板。做好了这些当有人问你“最近API为什么慢”时你至少能用数据说话而不是梗着脖子说“我觉得不慢”。回到最开始的问题用SpringBoot搭建RESTful服务不是把注解写上就万事大吉。REST是一种风格但更是一种纪律。URL里不要有动词返回体要有统一但灵活的契约异常要交给专门处理器参数要交给校验框架分页过滤要显式设计版本要有清晰策略文档测试可观测缺一不可。这些教训背后是你对“服务”二字的理解——你要交付的不只是一堆接口而是一个健壮的、可协商的、能让人安心使用的边界。如果你现在正攥着写满GetMapping的Controller不妨先停下来问一问自己这个服务真的算得上RESTful吗若不算那就从今天开始把一个接口一个接口地修好。别等到API被无数前端调用之后再回头舔自己曾犯过的错。最后送上一句刻薄但真实的话在SpringBoot里搭个能跑的接口只要十分钟但把一个接口设计成RESTful可能需要你一辈子去体会。这不是劝退而是提醒用脚步丈量规范比用口号粉饰平庸重要得多。成长发生在一个个认真定名的资源路径里发生在一段段没有try-catch污染的Controller代码里发生在你愿意为返回体多写一个错误码的深夜。所谓专业就是愿意在这些细节上和自己较劲。