你必须从“接口能跑”进化到“接口能用、能扛、能演进”。SpringBoot让REST接口的开发门槛低到尘埃里，一个@RestController加上几个注解，五分钟就能拼出一个看似完美的API。可正是这种低门槛，让无数团队在接口上线后陷入泥潭——要么被调用方抱怨状态码语义混乱，要么被安全扫描报告直接打回，要么被一次流量峰值击穿性能底线。REST接口的魔鬼从来不在框架本身，而在你如何对待HTTP协议、数据类型与边界条件。这篇长文，我们把那些最容易被忽略、却足以决定接口生死的细节，一个个拎出来晒晒太阳。

状态码不是你想用，想用就能用

太多人把HTTP状态码当成一种“返回格式”，而不是协议语义的一部分。返回200表示“请求成功”，可里面塞着一堆业务错误码，这种做法看似灵活，实则让调用方彻底丧失了对HTTP层的信任。200不等于成功，它只等于“服务器收到了请求并做出了响应”。如果参数校验失败，你应该返回400 Bad Request，而不是200加上{"code":10001}。如果资源不存在，请干脆地返回404，而不是让调用方解析响应体才发现“哦原来查无此人”。

更隐蔽的是状态码的“滥用”和“混用”。有人为了图省事，把所有业务异常都映射为500 Internal Server Error——这是最懒惰的偷懒方式。500只该留给那些真正的服务器内部错误：空指针、数据库连接超时、未捕获的未知异常。把你的业务校验失败伪装成服务器错误，等于把责任推给运维，还让监控系统天天给你发红色警报。另一个极端是把所有请求都返回200，然后靠code字段区分，这等于把HTTP这个现成的状态机扔进垃圾桶，自己重造一个更差的。

正确做法是建立一张状态码映射表：参数类问题统一用400，认证失败用401，权限不足用403，资源不存在用404，请求撞上业务规则冲突用409 Conflict。分类明确的好处是调用方能在不解析body的情况下快速做出容错决策，比如401直接跳登录页，403直接禁用按钮，404直接提示用户。状态码是你和API消费者之间最朴素的契约，破坏契约的人终将被契约反噬。

异常处理：别让你的堆栈裸奔

SpringBoot默认的异常响应是一段带时间戳、状态码、error、message和path的JSON。看着挺全，可那里面直接暴露了内部异常信息——甚至包括SQL语句、类名、方法名。生产环境开着这样的响应，等于把系统的底裤展示给所有恶意调用者。异常信息的颗粒度，决定了一个接口的安全级别。对外，你只需要告诉调用方“哪个字段错了、为什么错了、怎么改”；对内，完整堆栈的详细日志才是排查问题的真正依据。

用@RestControllerAdvice做全局异常处理是基本功，但细节在于如何分层。建议至少拆三层：第一层处理参数校验异常（MethodArgumentNotValidException、ConstraintViolationException），统一返回字段路径和错误消息；第二层处理自定义业务异常，携带业务错误码和HTTP状态码映射；第三层兜底所有未预期异常，返回状态码500，同时把完整的堆栈写入日志追踪系统。没有人能写出不抛异常的代码，但你至少能让异常在到达客户端之前被体面地驯化。

还有个细节常被忽略——异常处理和响应体的结构必须一致。不能校验异常返回{"code":400,"message":"bad"}，业务异常返回{"errorCode":5001,"msg":"failed"}，兜底又变成{"status":"error","detail":"..."}。这种混乱会让调用方为每一种异常写一套解析逻辑。约定一个统一的响应信封，比如{ "code":0, "data":..., "message":"ok" }，成功和失败都用同一套结构，这才是降低沟通成本的根本。

参数校验：从入参的第一刻就拒绝脏数据

很多接口对参数的防御只停留在if (name == null)的原始阶段，可一旦字段多起来，这种散落各处的校验既难维护又容易漏掉。SpringBoot内置的javax.validation（或jakarta.validation）配合@Valid注解，能让你在DTO字段上用声明式方式完成80%的校验需求：@NotNull、@Size、@Pattern、@Min、@Max、@Email。声明式校验的最大价值不是减少代码量，而是让“该字段允许什么值”成为接口文档的一部分，而不是藏在方法体里的逻辑谜语。

但校验不止于注解。几个容易翻车的细节：第一，@Valid用在@RequestBody参数上时，校验失败会抛MethodArgumentNotValidException，可如果你的Controller还接收@RequestParam，则需要单独校验，因为SpringBoot 3.x之后@RequestParam的校验需要类上标注@Validated。第二，集合元素的校验要用List<@Valid Item>这种泛型约束写法，否则集合里的每一个对象都不会被递归校验。第三，String类型除了判空，还要考虑空白字符串——@NotBlank和@NotNull的选择是个陷阱。

更高级的细节是“分组校验”——同一份DTO在不同场景下约束不同。比如创建用户时userId必须为空，更新用户时userId必须非空。用@Validated(UpdateGroup.class)配合@NotNull(groups = UpdateGroup.class)，比写两个DTO强得多。此外，千万别忘了给校验错误配一个友好的、可操作的message。“name不能为空”比“字段非法”有价值一百倍，因为前者告诉人怎么修，后者只是把人当猴耍。

DTO设计：别把实体类当传话筒

最常见的坏味道是直接拿JPAEntity或MyBatis的POJO做接口的返回结果。一个User实体带着密码hash、内部flag、数据库时间戳，全量序列化成JSON输出，先不说字段冗余，单是password字段泄漏就是安全事故。REST接口的“资源表示”应当是为客户端量身定制的DTO，而不是数据库表的倒影。你需要专门定义请求DTO（RequestDTO）和响应DTO（ResponseDTO），并做显式映射。

请求DTO和响应DTO隔离的好处是显而易见的：当数据库加字段时，你只改映射逻辑，而不破坏已有的API契约；当客户端需要新字段时，你只动响应DTO和对应转换器。写一个Mapper接口（比如MapStruct）或者手写转换静态方法，都比在Controller里逐个set干净得多。一旦你的Controller方法里出现了连续十几个set，那就是重构的警钟。

另一个细节是DTO的“空心化”问题——所有字段都是String类型，全部可空，美其名曰“灵活”，实际上把类型安全和约束全扔了。比如birthDate用String传，然后服务端去解析，解析失败就返回500，这简直是自己挖坑。DTO的字段类型必须与业务语义严格对应：日期用LocalDate或Instant，金额用BigDecimal，枚举用枚举类型（配合@JsonCreator做宽容反序列化）。让不能表达的值在反序列化阶段就失败，而不是等到业务逻辑里再去猜。

版本管理：给你的API留一条生路

REST接口只要上线，就会被无数客户端依赖。你不可能让所有调用方跟着你同时升级，所以版本管理不是可选项，而是生存必需品。没有版本管理的接口，每一次改动都是一场危机。

常见策略有三种：URL路径版本（/api/v1/users）、请求头版本（X-API-Version: 1）、媒体类型版本（Accept: application/vnd.example.v1+json）。URL路径最直观、最容易调试，适合对外的公开API；请求头版本更“RESTful”但隐藏性高，适合内部服务，不过容易因为客户端忘记带请求头而默认落到最新版本，然后挂掉。媒体类型版本最优雅但实现成本高，适合严格控制API语义的场景。

版本策略的实质是允许新旧版本共存，而不是逼着所有人迁移。你必须制定清晰的废弃策略：每周发布v2，至少保留v1半年，在v1的所有响应里加Deprecation响应头，并在文档里高亮提醒。细节上，SpringBoot可以用@RequestMapping(value="/api", headers="API-Version=1")实现基于请求头的分流，也可以用路径前缀加多个Controller实现。宁可多写一个Controller，也不要在一个方法里用if-else判断版本分支，那样迟早变成地狱。

分页与排序：细节里藏着性能炸弹

列表接口如果不做分页，就是在给数据库判处死刑。但很多人的分页参数设计极其随意，page从0开始还是从1开始？pageSize最大允许多少？排序字段能否由客户端任意指定？这些问题如果不明确，就会成为调用方与后端之间的扯皮点。

分页参数必须统一约定。建议page从0开始（和Spring Data Pageable默认一致），size默认20、最大100，超过则自动钳制或返回400。响应体里不光要有数据列表，还要有total总数、page、size，让调用方可以正确渲染分页控件。排序参数用sort=field,direction的格式，但白名单机制是必须的——你不能让客户端传sort=privateField直接排序，更不能传sort=subquery引发SQL注入。用枚举或Set预定义可排序字段，以字段名到数据库列名的映射做严格限制。

还有一个细节：总数统计在数据量大时非常昂贵。如果你的列表查询涉及多表join或复杂过滤条件，count()可能比数据查询本身还慢几倍。对于前台API，要么用缓存记录总数，要么直接不返回total，只返回“是否还有下一页”。很多Feed流接口根本不显示总数，这反而更贴合实际。别让一个分页接口拖垮整个数据库，这是性能优化的第一课。

并发与幂等：保护你的资源不被玩坏

REST接口天然要面对并发。一次用户点击抢购，前端防重只能挡住一半，后端必须靠幂等设计兜底。幂等性是指同一个请求重复执行多次，资源状态与执行一次完全一致。GET、PUT、DELETE天然是幂等的，POST却不是——但你可以用幂等键（Idempotency-Key）给POST加上幂等语义。

实现思路不复杂：客户端在Header里带一个UUID作为幂等键，服务端用一个哈希表或Redis记录已经处理过的幂等键以及对应结果。当相同键的请求再次到达时，直接返回上一次的结果，而不是重新执行业务。注意缓存结果的TTL要合理（比如30分钟），并在并发环境下用原子操作（setIfAbsent）避免两个并发请求同时拿到“未处理”的读数。你的接口拦不住重复提交，但至少不能让重复提交造成重复扣款。

另一个并发细节是乐观锁。当两个客户端同时更新同一个资源，先提交的应该成功，后提交的应该收到409 Conflict或者被版本号拒绝。经典做法是在表里加version字段，更新时带上前一次读到的version，SQL里带上WHERE version = ?。SpringData JPA的@Version注解可以轻松实现。别小看这个细节，它能让你的接口从“被并发bug撕碎”变成“优雅地拒绝覆盖写”。

文档与契约：让你的API不再只靠口口相传

写接口不写文档，等于把调用方推入火坑。SpringBoot生态里最好的答案无疑是springdoc-openapi（Swagger 3），它能从代码自动生成OpenAPI文档。但自动生成的文档也有坑：默认暴露了所有Controller和实体字段，文档里包含内幕字段；默认描述模糊，让人看不懂每个参数的含义和是否必填。

文档的第一原则是：让机器可读，让人也可读。用@Operation注解写清接口操作说明，用@Parameter描述每个参数的含义和示例，用@Schema为DTO字段补充注释。更关键的是为文档设置访问控制，生产环境要么关闭文档，要么架设内网白名单。文档不是摆设，它是最基础的接口测试工具，也是新同事入门的最大捷径。

比文档更进一步的是契约测试。用SpringCloud Contract或Pact生成契约文件，消费者和生产者分别基于契约测试自己侧的逻辑。在微服务或多团队协作中，契约测试能在接口被破坏前发出警报，而不是等到上线联调时才互相甩锅。你的接口有没有被破坏，不应当由上线后的第一个消费者来发现。

安全细节点：那些容易被忽视的防护

REST接口默认暴露在公网，安全细节一个都不能少。CORS不能全局放行，除非你的接口不需要任何凭证。当跨域请求需要携带Cookie或Authorization头时，allowedOrigins必须明确指定具体的域名，且不能与allowCredentials(true)同时使用。更安全的设计是让网关或Nginx统一处理CORS，应用层只关心业务。

参数校验要预防注入，但很多人忽略了JSON反序列化时的类型混淆。如果接口接收一个Map<String,Object>再通过反射转换，攻击者可能通过@type之类的字段触发安全漏洞。建议永远使用具体DTO类型的@RequestBody，不要用泛型Map接收复杂对象。拒绝toString、拒绝拼SQL、拒绝反射动态调用，这三条红线能挡掉大部分安全攻击。

速率限制也是REST接口的“第二层防火墙”。SpringBoot里用Bucket4j或者Redis+Lua实现令牌桶限流，按用户或者按IP限流。流量不会因为你没做过防刷而变少，接口的资源预算只会在被打爆时让你肉疼。对于那些高频接口（验证码、登录、查询），限流阈值要更严格；给超限的请求返回429 Too Many Requests，并在Retry-After响应头里告诉客户端等多久。这才是规范且实用的自我保护。

测试你的接口，别把肉手当工具

最后聊测试。很多人的“接口测试”就是在Swagger页面点几下“Try it out”，看返回200就完了。这种测试只能证明“请求被受理”，不能证明“行为正确”。真正的接口测试应该覆盖正常路径、异常路径、边界条件、并发条件和安全条件。

用MockMvc做Controller层测试，用@WebMvcTest切片测试，用Testcontainers起真实数据库跑集成测试。所有状态码映射、所有异常响应结构、所有参数校验失败场景，都要有对应的测试用例。一个没有测试的接口，跟一条没有护栏的悬崖公路没有区别——你只是今天运气好没掉下去。

特别要提的是契约测试和服务降级测试。当下游服务超时或返回500时，你的接口应该返回什么？是跟着500还是返回一个合理的降级响应？这个场景如果没测试过，等到线上依赖挂掉时，你只能看着千篇一律的“Internal Server Error”干瞪眼。时刻记住：接口不是你自己的作品，而是整个系统的零件，零件的健壮性决定了整机的可靠性。

SpringBoot给了你快速起跑的捷径，但跑得远不远，靠的是你对HTTP协议、数据建模、安全边界和工程纪律的持续打磨。每一个细节都是一次对“认真”的投票，而你的API消费者会用自己的代码和日志，为你投出真实的一票。别把“能跑”当作终点，把“好用、可靠、可演进”当作基本盘，你的接口才会成为团队引以为豪的资产，而不是又一座需要后人填坑的债务山。