用SpringBoot搭建RESTful服务：常见误区与建议
接手一个号称“RESTful”的SpringBoot服务，往往从URL就能看出灾难的雏形：/saveUser、/getUserById、/updateUser、/deleteUser，动词满天飞，名词无处藏。你以为在用RESTful，其实只是把HTTP当作了一个能跑通的管道，顺手把方法调用焊死在URL上。REST的核心在于资源与状态转移，而不是把服务端的方法名翻译成英文路径。真正的问题是，很多人从未理解“资源”的含义，就开始写@RestController了。
动词与HTTP方法：谁才是主角？
用SpringBoot写RESTful，最典型的误区就是把HTTP方法当成装饰品，把操作动词塞进路径。有人会说“POST也能做事，为什么非得用DELETE？”——这不是换不换方法名的问题，而是语义混乱会直接导致客户端无法安全预测行为。一个GET /api/user?id=1和一个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、List<Order>，压根没有统一的响应包装。前端拿到数据后，得靠HTTP状态码猜成败，一旦服务端抛出业务异常，返回内容变成一段HTML错误页，前端哭都哭不出来。另一种是裹粽子派：所有接口都套上三层壳{code, message, data}，甚至{status, error, errors, data}，连成功响应也要塞一个message: "操作成功"。没有约定的包装就是垃圾，但有约定的包装也未必是佳话。关键在于包装必须与错误码体系配套，并且要能区分系统异常、业务异常和参数异常。
更隐蔽的问题是：很多团队把HttpStatus和自定义code搞成两套话语体系。明明返回200，body里却写着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。更别忽略HttpMessageNotReadableException，JSON解析失败时，前端需要知道是哪个字段类型不对。异常处理器的粒度，决定了你的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走天下？
很多接口张嘴就返回List<User>，也不管有多少数据。等数据量到了十万，接口超时，前端卡死，运维骂娘。不提供分页的查询接口，是不负责任的。Spring Data提供了Pageable抽象，你完全可以在Controller里接一个Pageable参数，用Page类型返回。但这里也有个误区：把Page对象整个序列化给前端，前端被迫解析totalPages、totalElements、number、size——太臃肿。
更好的做法是返回一个轻量分页响应：{items: [], page: 1, size: 20, total: 100}。别让Pageable成为一把万能钥匙，你要显式约束size的最大值，防止有人一次取一万条。至于过滤，别靠拼SQL字符串，更别用@RequestParam Map<String, String>来接收所有条件，那是灾难。设计一个明确的过滤对象，配合JPA Specifications或MyBatis的Provider，让你的查询逻辑可维护、可测试、可预测。
版本管理：URL里的v1是堕落的开始？
API需要演进，版本管理就绕不开。最常见的俗手是在URL上写/api/v1/users、/api/v2/users。这么做简单粗暴，但一旦你开始在每个URL里写版本号，就相当于告诉客户端：你们必须跟着我的升级节奏走。更好的选择是用Header或MediaType来协商版本，比如Accept: application/json;version=2。不过要承认，在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服务的性能问题，往往发生在没人关注的地方：N+1查询、大对象序列化、连接池耗尽。没有监控指标，就没有优化方向。你可以用Micrometer把请求的@Timed注解或自动配置的http.server.requests指标接入Prometheus，再配Grafana看板。做好了这些，当有人问你“最近API为什么慢”时，你至少能用数据说话，而不是梗着脖子说“我觉得不慢”。
回到最开始的问题：用SpringBoot搭建RESTful服务，不是把注解写上就万事大吉。REST是一种风格，但更是一种纪律。URL里不要有动词，返回体要有统一但灵活的契约，异常要交给专门处理器，参数要交给校验框架，分页过滤要显式设计，版本要有清晰策略，文档测试可观测缺一不可。这些教训背后是你对“服务”二字的理解——你要交付的不只是一堆接口，而是一个健壮的、可协商的、能让人安心使用的边界。如果你现在正攥着写满@GetMapping的Controller，不妨先停下来，问一问自己：这个服务真的算得上RESTful吗？若不算，那就从今天开始，把一个接口一个接口地修好。别等到API被无数前端调用之后，再回头舔自己曾犯过的错。
最后送上一句刻薄但真实的话：在SpringBoot里搭个能跑的接口只要十分钟，但把一个接口设计成RESTful，可能需要你一辈子去体会。这不是劝退，而是提醒：用脚步丈量规范，比用口号粉饰平庸重要得多。成长发生在一个个认真定名的资源路径里，发生在一段段没有try-catch污染的Controller代码里，发生在你愿意为返回体多写一个错误码的深夜。所谓专业，就是愿意在这些细节上和自己较劲。