SpringBoot系列06：RESTful接口开发，请求参数接收、全局跨域CORS完整配置-北京尧图网络

SpringBoot系列06RESTful接口开发请求参数接收、全局跨域CORS完整配置✅ 系列专栏SpringBoot零基础进阶实战系列✅ 适配版本SpringBoot 3.x / Java 17✅ 核心亮点零基础上手、全覆盖参数接收、三种全局CORS配置、生产级避坑、可直接复用✅ 阅读收益彻底掌握RESTful接口规范、所有请求参数接收场景、解决前后端99%跨域问题一、前言为什么必须学RESTful与CORS配置在前后端分离开发模式中RESTful API是目前行业统一的接口设计规范替代了传统杂乱的接口请求方式让接口语义清晰、统一规范、易于维护。而CORS跨域问题是前后端联调的高频痛点90%的接口联调报错都源于跨域配置不当。本文将从零开始手把手带大家实现标准RESTful接口开发全场景请求参数接收生产级全局CORS配置摒弃零散代码提供可直接用于项目的完整方案同时解析底层原理和常见踩坑点。本文核心知识点清单RESTful API设计规范四大HTTP方法对应增删改查SpringBoot五种核心请求参数接收方式全覆盖业务场景三种生产级全局CORS跨域配置方案优先级对比、场景适配跨域核心原理、常见报错原因与终极解决方案生产环境CORS安全配置避坑指南二、RESTful API核心设计规范RESTfulRepresentational State Transfer即表述性状态转移核心思想是用HTTP请求方法定义操作用URL定义资源URL只命名资源不包含操作行为。2.1 传统接口 vs RESTful接口对比传统接口风格不规范/user/add 新增用户/user/delete 删除用户/user/update 修改用户/user/get 查询用户RESTful规范风格标准统一HTTP方法业务操作接口地址说明GET查询资源/api/user查询用户列表GET查询单资源/api/user/{id}根据ID查询单个用户POST新增资源/api/user新增用户PUT全量修改资源/api/user/{id}根据ID完整更新用户信息PATCH局部修改资源/api/user/{id}局部更新用户字段DELETE删除资源/api/user/{id}根据ID删除用户2.2 RESTful核心约束资源唯一URL定位唯一资源名词复数命名user、order、goods方法语义化严格遵循HTTP方法对应增删改查无状态服务器不存储客户端状态每次请求独立返回统一格式统一JSON响应体包含状态码、信息、数据三、SpringBoot全场景请求参数接收实战SpringBoot RESTful接口中参数接收分为5种核心场景覆盖所有业务开发需求下面结合RESTful接口逐一实战演示所有代码基于SpringBoot3可直接运行。前置基础RESTful接口统一控制器注解// 组合注解 Controller ResponseBody直接返回JSON数据RestControllerRequestMapping(/api/user)publicclassUserRestController{}3.1 PathVariable 路径参数URL路径传参适用场景查询单个资源、删除、修改RESTful标准传参参数拼接在URL路径中请求示例GET /api/user/1001/** * 根据ID查询单个用户 * param id 用户ID路径参数 * return 用户信息 */GetMapping(/{id})publicResultgetUserById(PathVariableLongid){returnResult.success(查询成功,用户IDid);}进阶用法多路径参数、参数别名、必填控制// 多路径参数别名映射非必填GetMapping(/{userId}/role/{roleId})publicResultgetUserRole(PathVariable(userId)Longuid,PathVariable(requiredfalse)LongroleId){returnResult.success(多参数查询成功,用户IDuid角色IDroleId);}3.2 RequestParam 查询参数URL问号传参适用场景列表查询、条件筛选、分页参数参数拼接在URL?后请求示例GET /api/user/list?name张三page1size10/** * 用户条件分页查询 * param name 用户名非必填 * param page 页码默认1 * param size 每页条数默认10 * return 分页数据 */GetMapping(/list)publicResultgetUserList(RequestParam(valuename,requiredfalse,defaultValue)Stringname,RequestParam(defaultValue1)Integerpage,RequestParam(defaultValue10)Integersize){StringresString.format(筛选用户%s页码%d条数%d,name,page,size);returnResult.success(分页查询成功,res);}核心参数说明value前端参数名与后端形参名不一致时做映射required是否必填默认truedefaultValue参数为空时默认值3.3 RequestBody JSON实体参数POST/PUT核心适用场景新增、修改接口前端传递JSON格式请求体最常用的传参方式注意GET请求不支持RequestBody仅POST/PUT/PATCH可用第一步创建实体接收类importlombok.Data;DatapublicclassUserDTO{// 用户名privateStringusername;// 手机号privateStringphone;// 年龄privateIntegerage;}第二步编写新增接口/** * 新增用户JSON请求体传参 * param userDTO 用户信息 * return 新增结果 */PostMappingpublicResultaddUser(RequestBodyUserDTOuserDTO){returnResult.success(新增用户成功,userDTO);}常见报错415 Unsupported Media Type原因前端未设置Content-Type: application/json3.4 RequestHeader 请求头参数适用场景获取Token、请求设备信息、自定义请求头等/** * 获取请求头中的Token * param token 登录令牌 * return 校验结果 */GetMapping(/token)publicResultgetToken(RequestHeader(Authorization)Stringtoken){returnResult.success(获取Token成功,令牌token);}3.5 普通表单参数无注解接收适用场景form表单提交Content-Type: application/x-www-form-urlencoded无需任何注解直接通过形参接收参数名与前端一致即可PostMapping(/form)publicResultformSubmit(Stringusername,Stringpassword){returnResult.success(表单提交成功,账号username密码password);}3.6 统一响应结果封装规范REST返回值为满足RESTful接口统一返回规范封装通用Result工具类所有接口统一返回格式importlombok.Data;DatapublicclassResultT{// 响应码200成功 500失败privateIntegercode;// 响应信息privateStringmsg;// 响应数据privateTdata;// 成功响应publicstaticTResultTsuccess(Stringmsg,Tdata){ResultTresultnewResult();result.setCode(200);result.setMsg(msg);result.setData(data);returnresult;}// 失败响应publicstaticTResultTerror(Stringmsg){ResultTresultnewResult();result.setCode(500);result.setMsg(msg);returnresult;}}四、CORS跨域原理与报错原因4.1 什么是跨域浏览器同源策略限制协议、域名、端口三者任意一个不同即为跨域浏览器会拦截响应抛出跨域报错。同源判定规则http://localhost:8080后端与 http://localhost:3000前端端口不同跨域4.2 常见跨域报错Access to fetch at ‘xxx’ from origin ‘xxx’ has been blocked by CORS policy: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.核心原因后端接口未配置跨域许可未返回对应的跨域响应头。五、三种生产级全局CORS配置方案推荐收藏SpringBoot中跨域配置分为局部注解配置和全局配置局部配置仅对单个接口生效企业项目统一使用全局配置下面提供三种主流全局配置方案适配不同场景。5.1 方案一实现WebMvcConfigurer最推荐、轻量化适用场景绝大多数SpringBoot项目不影响SpringSecurity、拦截器等配置优先级适中核心优势代码简洁、侵入性低、适配SpringBoot3importorg.springframework.context.annotation.Configuration;importorg.springframework.web.servlet.config.annotation.CorsRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer;/** * 全局跨域配置方案一WebMvc配置 * 生产推荐精准配置域名禁止直接使用* */ConfigurationpublicclassCorsConfigimplementsWebMvcConfigurer{OverridepublicvoidaddCorsMappings(CorsRegistryregistry){// 匹配所有接口路径registry.addMapping(/**)// 允许跨域的前端域名生产环境替换为真实前端地址多个域名用逗号分隔.allowedOrigins(http://localhost:3000,http://127.0.0.1:3000)// 允许所有请求方法.allowedMethods(GET,POST,PUT,DELETE,OPTIONS)// 允许所有请求头.allowedHeaders(*)// 允许携带Cookie、Token凭证.allowCredentials(true)// 预检请求有效期1小时减少OPTIONS请求次数.maxAge(3600);}}5.2 方案二注册CorsFilter过滤器优先级最高、全局拦截适用场景需要优先执行跨域配置、整合SpringSecurity、高并发项目核心优势过滤器层级最高可解决拦截器、权限框架导致的跨域失效问题importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importorg.springframework.web.cors.CorsConfiguration;importorg.springframework.web.cors.UrlBasedCorsConfigurationSource;importorg.springframework.web.filter.CorsFilter;importjava.util.Arrays;/** * 全局跨域配置方案二CorsFilter过滤器 * 优先级高于WebMvc配置适合整合权限框架的项目 */ConfigurationpublicclassCorsFilterConfig{BeanpublicCorsFiltercorsFilter(){CorsConfigurationconfignewCorsConfiguration();// 允许的前端域名config.setAllowedOrigins(Arrays.asList(http://localhost:3000,http://127.0.0.1:3000));// 允许请求方法config.setAllowedMethods(Arrays.asList(GET,POST,PUT,DELETE,OPTIONS));// 允许请求头config.setAllowedHeaders(Arrays.asList(*));// 允许携带凭证config.setAllowCredentials(true);// 预检请求缓存时间config.setMaxAge(3600L);// 匹配所有接口UrlBasedCorsConfigurationSourcesourcenewUrlBasedCorsConfigurationSource();source.registerCorsConfiguration(/**,config);returnnewCorsFilter(source);}}5.3 方案三yml配置文件极简配置快速开发适用场景本地开发、快速测试不推荐生产使用灵活性差在application.yml中直接添加配置# 全局跨域配置spring:web:cors:allowed-origins:http://localhost:3000allowed-methods:GET,POST,PUT,DELETE,OPTIONSallowed-headers:*allow-credentials:truemax-age:36005.4 局部跨域配置了解即可通过CrossOrigin注解作用于类或方法仅对当前接口生效RestControllerRequestMapping(/api/user)CrossOrigin(originshttp://localhost:3000)publicclassUserRestController{// 所有接口自动跨域}六、生产环境CORS核心避坑指南必看6.1 禁止使用 allowedOrigins(“*”)致命错误开启allowCredentials(true)时不能配置*通配符会直接报错原因浏览器安全机制允许携带Cookie时必须指定具体域名不允许全局开放生产方案枚举所有前端合法域名或通过配置文件动态读取6.2 OPTIONS预检请求403报错复杂请求带Token、自定义请求头会先发OPTIONS预检请求必须手动放行OPTIONS方法否则权限框架会拦截6.3 配置优先级规则CorsFilter过滤器 CrossOrigin注解 WebMvc全局配置 yml配置项目中只保留一种全局配置多配置共存会导致跨域失效、冲突报错6.4 跨域失效常见原因SpringSecurity未放行OPTIONS请求自定义拦截器在跨域过滤器之前执行配置类未加Configuration注解未生效前后端端口、域名匹配错误URL拼写格式错误配置前端跨域域名时禁止出现多余引号、空格、非法字符如 http://127.0.0.1:3000 错误格式URL末尾不能带双引号、逗号等冗余字符会直接导致跨域配置解析失败、前端请求跨域报错域名协议不匹配后端配置http协议前端使用https协议或反之引发跨域拦截SpringSecurity未放行OPTIONS请求自定义拦截器在跨域过滤器之前执行配置类未加Configuration注解未生效前后端端口、域名匹配错误七、完整项目测试流程启动SpringBoot项目端口8080使用Postman/Apifox测试所有RESTful接口启动前端项目3000端口调用后端接口跨域问题彻底解决所有参数接收场景均可正常解析返回统一JSON格式八、总结与下期预告本文总结掌握RESTful标准化接口设计告别杂乱接口风格吃透5种请求参数接收方式覆盖100%业务传参场景掌握3种生产级全局CORS配置解决所有跨域问题熟悉生产环境跨域避坑要点规避线上故障下期预告SpringBoot系列07全局异常处理统一返回结果封装彻底消灭接口杂乱报错博主寄语RESTful接口开发和跨域配置是SpringBoot前后端分离的基础必修课看似简单但极易踩坑。建议大家收藏本文项目中直接复用配置规范代码风格提升开发效率。码字不易点赞关注持续更新SpringBoot干货有问题评论区交流秒回

SpringBoot系列06：RESTful接口开发，请求参数接收、全局跨域CORS完整配置

相关推荐

我终于搞定爬虫封IP！从零手写一套 Requests 自动轮换代理池（亲测可用）

嵌入式键盘矩阵设计：2x2矩阵+74HC32实现高效输入

Trae：基于MCP协议的AI Agent工作流操作系统

更多资讯

视觉语音交互技术：多模态融合与场景化应用

text-to-cad 实战：Python 参数化建模与 STEP/URDF 导出全链路

深入理解Linux基础IO机制与性能调优

Linux TCP/UDP协议实战：socket参数与内核排错

Python实现区块链时间胶囊：轻量级链上时间锚点方案

降维与度量学习：高维数据处理的核心技术解析

今日更新

Agent-Reach：打通大模型触达外部系统的最后一公里

深度学习图像隐写分析实战：从CNN原理到毕设源码全解析

AI赋能知识产权供需匹配：专利评估、需求挖掘与多路召回工程实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？