RESTful API的设计从来不是写几个Controller、加上@RestController注解那么简单。很多团队把Spring Boot当成一个快速生产的魔盒，塞进一堆@GetMapping和@PostMapping，结果上线后接口混乱、版本爆炸、错误响应千奇百怪——这根本不是在开发API，而是在制造技术债务。API是系统的门面，每一个端点都代表着一次与调用方的契约。从设计到部署，Spring Boot给了你强大的工具，但也给了你足够的空间犯错。今天，我们不聊Hello World，直接解剖一个从零构建RESTful API的完整链路，包括那些几乎没有人教你的细节。
设计：资源建模是第一道关卡
打开Spring Boot官方文档，你会发现它教你如何快速创建一个Controller，但他们不会告诉你：在写第一行代码之前，你应该用纸笔定义好你的资源。RESTful的核心不是URL漂亮，而是资源与动词的语义对应。
很多人把URL当RPC用：/getUser?id=1或者/deleteUser?id=1。这是对REST最大的误解。HTTP动词（GET、POST、PUT、PATCH、DELETE）本身就代表了操作语义。你的URL只需要描述是什么资源，剩下的交给动词。例如：GET /users/1表示“读取ID为1的用户资源”；DELETE /users/1表示“删除该资源”。坚持这种映射，你的API会自文档化，调用方不需要看注释就能猜出意图。
更深层的问题在于：一个资源的不同表现形态该如何定义？比如，用户列表需要分页、排序、过滤，这时候不能简单地把参数塞进查询字符串了事。我见过有人把过滤条件写成/users?filter[name]=john&filter[age]=gt 18，这其实是在模仿GraphQL的查询语法，但用在REST上反而加重了解析负担。更明智的做法是约定一套标准查询参数：/users?page=1&size=20&sort=createdAt,desc&name=john。然后，在Spring Boot中用Pageable和@RequestParam来接收，再用Specification或QueryDSL动态构建查询。拒绝“一刀切”的万能接口，每个资源都应该有清晰的查询边界。
另一个容易被忽视的是错误响应设计。当API出错时，调用方需要知道：发生了什么、哪个字段错了、建议怎么做。Spring Boot默认的DefaultErrorAttributes返回的信息远不够用。你需要自定义ResponseEntityExceptionHandler，统一输出一个包含code、message、details的JSON结构。例如：
{ "code": "USER_NOT_FOUND", "message": "用户ID 123 不存在", "details": { "userId": 123 } }
好的错误响应是API和调用方之间的信任桥梁，而不是抛出500然后留下一行内部堆栈。
工程落地：分层代码与领域隔离
设计文档画好之后，到了真正的编码环节。很多人习惯在Controller里直接调用Repository，或者把业务逻辑写在Controller方法里。Controller只应做三件事：参数解析、调用Service、结果渲染。任何业务判断、数据校验、权限检查都应该下沉到Service层或独立的验证层。
我推荐使用“五层架构”：Controller -> Application Service -> Domain Service -> Repository -> DB。但这并不意味着每个项目都需要五层，但至少你要保证：Entity（实体类）绝不能直接暴露给API外部。很多开发者偷懒，直接在Controller里返回JPA的User实体。结果就是：当数据库字段变化时，API响应也跟着变，导致前端崩溃。你需要用DTO（数据传输对象）或VO（视图对象）来隔离内部模型与外部契约。
Spring Boot中，你可以在Controller的方法里手动装配DTO，或者使用ModelMapper、MapStruct等库。我个人偏好在Service层返回DTO，因为Service是真正的业务边界。例如：
public UserDTO getUserById(Long id) { User user = userRepository.findById(id) .orElseThrow(() -> new UserNotFoundException(id)); return userMapper.toDTO(user); }
VO和DTO的最大区别在于：VO是特定于某个视图的响应结构，DTO是跨场景的数据载体。如果API列表页和详情页的字段差异很大，应该返回不同的VO，而不是同一个DTO带一堆null。
另一个关键点是参数校验。Spring Boot提供了@Valid和@Validated配合javax.validation.constraints，但这只完成了“输入格式”的校验。真正的业务校验，比如“用户邮箱不能与其他已激活用户重复”，你应该放在Service层通过@Transactional和数据库查询来完成。不要迷信注解，注解解决的是语法，业务逻辑需要用代码捍卫。
此外，事务边界要牢记：Update类的操作，尽量在Service层加@Transactional，默认只对RuntimeException回滚。我见过有人对CheckedException也想自动回滚，结果写了rollbackFor = Exception.class，导致一些非业务异常也导致大量数据被回滚。请理解Spring事务的机制：只有未捕获的RuntimeException才会触发当前事务回滚。如果你需要捕获异常并决定是否回滚，请使用TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()。
安全与验证：每个入口都是战场
API一旦暴露在公网，你就无法信任任何输入。每一个请求参数、Header、甚至路径变量都可能是恶意载荷。Spring Security是你的第一道防线，但大部分人只会配个HTTP Basic认证就扔上去。现代RESTful API最常用的认证方式是JWT（JSON Web Token）。你不是在写一个登录状态管理，而是在颁发一个自包含的令牌。
JWT的核心在于：服务端不保存会话，令牌本身携带用户信息和权限。Spring Boot集成JWT并不复杂，但你需要自己实现OncePerRequestFilter来解析Header中的Bearer Token并设置SecurityContextHolder。关键点在于：签名密钥绝对不要硬编码，而是通过环境变量或配置中心获取。另外，JWT过期时间要合理：访问令牌（Access Token）建议15-30分钟，刷新令牌（Refresh Token）7天或更长。刷新令牌本身应该存储在服务端（比如Redis），且支持主动吊销。
权限控制方面，很多人给所有接口都加上@PreAuthorize("hasRole('ADMIN')")。这种粗粒度控制意味着你必须对角色做死板划分。更好的做法是用资源ID与用户ID的关系来动态鉴权。例如：只有资源的owner才能删除它，而不是任何拥有USER角色的人都能删。Spring Security的@PostAuthorize可以帮你拿到返回结果后进行校验，但更常见的是在Service层里显式检查currentUserId.equals(resource.getOwnerId())。
参数校验不止于格式。对于数字ID，需要校验是否是正数；对于字符串，需要防范XSS。你可以利用Jackson的@JsonFilter或者全局的StringTrimmerEditor来对输入做清洗。永远不要在Controller层接收原始JSON后直接传递给Service，至少要做一次反序列化转义。我还会在全局配置里禁用Jackson的@JsonAutoDetect，防止Entity中的敏感字段泄露。
测试：让修改有底气
没有测试的API就像没有护栏的悬崖——你永远不知道下一次重构会摔得多惨。很多程序员认为测试是QA的事，这是一种灾难性的傲慢。Spring Boot对测试的支持堪称豪华，从@WebMvcTest到@DataJpaTest，再到@SpringBootTest，你能以极低的成本构建测试金字塔。
先讲单元测试：对Service层的方法，你应该用Mockito模拟Repository，只测试业务逻辑。例如，当用户不存在时，是否可以抛出正确的异常？当权限不足时，是否返回403？一个Service方法至少覆盖三个分支：正常流程、边界条件、异常路径。很多人只写了正常路径，结果异常情况从未被验证。
然后是集成测试：用@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)结合TestRestTemplate或WebTestClient，对完整的HTTP请求链做验证。这里有一个关键点：永远不要依赖外部服务的真实性。使用@AutoConfigureMockMvc搭配WireMock来模拟第三方接口，或者用H2内存数据库测试JPA查询。对于API响应的完整结构，你可以用JSON path断言来验证字段类型和值。
还有一类容易被忽略的测试：契约测试（Contract Testing）。当你和前端团队约定好API格式后，你应该写一个测试，专门验证响应中所有字段的命名、类型、以及必选/可选性。Spring Cloud Contract或Pact都是很好的工具。契约测试是API团队协作的“双保险”，一但修改了DTO，测试会立刻告诉你是否破坏了外部约定。
我见过太多团队在测试上走了极端：只写了几个Controller层的示例测试，覆盖率不到10%，然后自我安慰“我们功能稳定”。直到某天有人在Service层改了数据库字段名，Controller层忘记映射，生产上爆出一堆空指针。测试不是为了凑数，而是为了让你能放心地迭代。
部署：容器化是最好的封装
当你把Spring Boot应用打成一个Jar包，扔到服务器上运行，用过的人都知道这个过程的痛苦：环境不一致、Java版本不匹配、配置硬编码。容器化（Docker）几乎是现代API部署的标配。
一个基础的Dockerfile很简单：用OpenJDK基础镜像，Copy Jar包，暴露端口，ENTRYPOINT执行java -jar。但这里有一个暗坑：不要把Jar包放在根目录下直接运行，而是用-Dspring.profiles.active指定环境，并且使用-XX:+UseContainerSupport让JVM感知容器内存限制。如果你用的是Spring Boot 2.3+，还可以通过构建分层镜像来加速镜像构建和上传。例如，把依赖层和应用代码层分开，这样每次修改代码时，依赖层可以直接用缓存，部署速度能提升数倍。
部署到Kubernetes（K8s）后，你还要处理健康检查。Spring Boot Actuator提供了/actuator/health端点，但默认只返回简单的UP/DOWN。你应该定制HealthIndicator，检查数据库连接、Redis连接、甚至外部依赖的状态。Liveness探针用于判断容器是否死掉，Readiness探针用于判断容器是否可以接收流量。这两个探针的配置非常讲究：Liveness的失败次数不能太少，否则偶发的GC停顿会导致Pod被重启；Readiness的初始延迟时间应大于应用启动完成的时间。建议结合Spring Boot的/actuator/info端点暴露版本号和构建时间，方便排错。
环境配置是另一个重灾区。永远不要将数据库密码或者Secret写在application.yml里。Spring Boot原生支持通过环境变量覆盖：SPRING_DATASOURCE_PASSWORD。更推荐的方式是用K8s的Secrets或Vault来管理敏感信息。对于多环境（dev/staging/prod），你可以在application-{profile}.yml中配置差异，然后用--spring.profiles.active指定。配置即代码，变更配置需要走版本控制和审批流程，而不是SSH到服务器上修改properties文件。
监控：部署不是终点，而是起点
API上线之后，你的工作才真正开始。你不知道用户会怎么调用你的API，你也不知道你的服务何时会挂。Spring Boot Actuator提供了/actuator/metrics，可以暴露JVM内存、线程数、GC次数、HTTP请求计数等指标。配合Micrometer和Prometheus，你可以构建一套完整的监控面板。
但光有指标还不够，你还需要结构化日志。不要把日志打成纯文本，然后用grep去查。推荐使用Logstash Encoder输出JSON格式的日志，包含traceId、userId、请求耗时、响应码。这样ELK（Elasticsearch, Logstash, Kibana）才能直接解析。微服务环境下的故障排查，靠的是分布式追踪，而不是看服务器日志的毫秒级时间戳。Spring Cloud Sleuth可以自动为每个请求生成traceId和spanId，并跨服务传递。如果你没有追踪机制，当用户报错“订单创建后余额没有变化”时，你可能得翻遍五六个服务的日志才能找到线索。
另外，API的响应时间是用户体验的指路牌。你应该记录每个端点的p50、p95和p99延迟。如果p99突然从200ms飙升到2s，说明某个上游服务或数据库出了异常。Actuator的/actuator/httptrace可以记录最近100个请求的详细信息，包括Header和耗时，但注意在生产环境下关闭包含敏感Header的trace，或者用自定义的过滤器只记录关键信息。
不要等到线上出故障才去监控，而是从一开始就把监控写入API的运行基线。我习惯在每个Controller中增加一道AOP切面，记录每个方法的执行耗时和异常情况。配合自定义的@Timed注解，你几乎可以实时看到每个API的健康度。
维护：API的进化与版本管理
再完美的设计也无法预知未来。业务会变，调用方会变，你的API的版本管理必须前置。最常见的错误是把API版本号直接写在URL里：/v1/users、/v2/users。这样做虽然明显，但会污染URL空间，而且当你升到v3时，v1和v2的代码你还要保留，导致代码冗余。
更好的做法是用请求头或者Media Type版本。例如，客户端在Accept头里指定application/vnd.myapp.v1+json。Spring Boot可以通过ContentNegotiationStrategy或者自定义RequestMappingHandlerMapping来解析。这种方法的好处是URL保持纯净，版本与资源解耦。如果你的项目迭代速度快到需要同时维护多个版本，建议对所有过期版本设置一个太阳落山的时间（EOL），并在响应Header中加入Deprecated标记。
每个API都应该提供文档，不是手写的Word文档，而是交互式文档。SpringDoc OpenAPI（替代Swagger）可以自动生成符合OpenAPI 3.0规范的JSON，并且通过Swagger UI让前端和测试人员直接尝试调用。但要注意：生产环境必须禁用Swagger UI，否则会暴露所有API的详细信息。你可以通过springdoc.api-docs.enabled=false和springdoc.swagger-ui.enabled=false来关闭，或者配置swagger-ui只对内部网络开放。
最后，记住：API是一次性编写，但需要终身维护。任何对已有接口的改动（包括新增字段、修改字段类型、改变错误码）都必须是向后兼容的，除非你明确告知升级并预留足够长的过渡期。你需要一个清晰的变更管理流程：写CHANGELOG，标记弃用，给调用方足够的时间迁移，然后才删除代码。
从设计到部署，Spring Boot只是工具，真正的功夫在工具之外。那些看似枯燥的约定——资源建模、DTO隔离、测试覆盖、容器化部署——每一个环节，都会在未来你半夜被报警电话吵醒时，证明它们的价值。好的API是沉默的：它把自己隐藏在最简单的语义背后，但它的内部却经得起任何规格的审查。如果你能从现在开始，在构建每个端点时都问自己“如果明天这个接口被调用10万次，会不会出问题？”，那么你离写出高质量RESTful API就不远了。
