一、前言在 Spring Boot 项目中调用第三方 HTTP 接口常见方案有 RestTemplate、HttpClient、Feign、WebClient 等。retrofit-spring-boot-starter 把 Square 的 Retrofit 封装成了 Spring Boot Starter用「接口 注解」的方式声明式地调用 HTTP 接口代码简洁和 Spring 生态融合好非常适合中小项目快速接入。注意事项及使用示例yml中配置前缀 http:scg-device:http://127.0.0.1:4430/cloud/sysdeviceaccess/thirdParty/# 注意事项路径最后边加上/在service中使用packagecom.hel.linked.service;importcom.github.lianjiatech.retrofit.spring.boot.core.RetrofitClient;importcom.hel.linked.vo.DeviceListRequestVo;importretrofit2.http.Body;importretrofit2.http.POST;RetrofitClient(baseUrl${http.scg-device})publicinterfaceDeviceCeacessService{POST(deviceList)StringgetDeviceList(BodyDeviceListRequestVodeviceListRequestVo);}注意事项一定不要再路径最前边加上/不然最后的路径就拼成了http://127.0.0.1:4430/deviceList二、环境要求项目 要求JDK 1.8Spring Boot 1.4.2 ~ 2.x对应 2.x 版本3.x / 4.x对应 3.x / 4.x 版本构建工具 Maven / Gradle网络 能访问目标接口⚠️ 版本匹配很重要Spring Boot 3.x 必须用 retrofit-spring-boot-starter 的 3.x 及以上版本否则启动会报兼容性错误。maven依赖dependencygroupIdcom.github.lianjiatech/groupIdartifactIdretrofit-spring-boot-starter/artifactIdversion3.0.2/version/dependency导包// 2.x 版本importcom.github.lianjiatech.retrofit.spring.boot.annotation.RetrofitClient;// 3.x / 4.x 版本importcom.github.lianjiatech.retrofit.spring.boot.core.RetrofitClient;四、基本使用流程4.1 配置文件里定义 baseUrl# application.yml http: remote-api: https://third-party-domain.com/api/device RetrofitClient 的 baseUrl 支持 ${} 占位符会从 Spring 配置中读取。4.2 定义请求体 VODatapublicclassDeviceListRequestVo{privateStringip;privateIntegercurrentPage;privateIntegerpageNum;}4.3 定义 Retrofit 接口javaRetrofitClient(baseUrl “${http.remote-api}”)public interface RemoteDeviceService {POST(list) String getDeviceList(Body DeviceListRequestVo vo);}4.4 在业务代码里注入使用javaServicepublic class DeviceServiceImpl {Resource private RemoteDeviceService remoteDeviceService; public Result? getDeviceList() { DeviceListRequestVo vo new DeviceListRequestVo(); vo.setIp(123); vo.setCurrentPage(1); vo.setPageNum(10); String result remoteDeviceService.getDeviceList(vo); return Result.OK(result); }}✅ Retrofit 接口会被自动扫描并注册为 Spring Bean直接 Resource / Autowired 注入即可不需要写实现类。五、GET / POST 写法大全5.1 GET 请求1URL 固定参数 动态 Query 参数GET(/api/report/getList.do?type1sourcetest_searchfalse)StringgetList(Query(startTime)StringstartTime,Query(endTime)StringendTime);2路径参数GET(user/{id})StringgetUser(Path(id)Longid);5.2 POST 请求1JSON 请求体最常用POST(list)StringgetDeviceList(BodyDeviceListRequestVovo);2表单提交 application/x-www-form-urlencodedFormUrlEncodedPOST(list)StringgetDeviceList(Field(ip)Stringip,Field(currentPage)intcurrentPage,Field(pageNum)intpageNum);⚠️ FormUrlEncoded 和 Body 不能同时使用。3URL 查询参数 JSON Body 混合POST(report/list.do?type1)StringgetList(Query(startTime)StringstartTime,Query(endTime)StringendTime,BodySomeBodybody);5.3 参数注解对照表注解 用途 出现位置Query | URL 查询参数 ?keyvalue | GET / POST 均可Path | 路径占位符 {id} | GET / POST 均可Body | JSON 请求体 | POST / PUTField | 表单字段需配 FormUrlEncoded | POSTHeader | 请求头 | 任意HeaderMap | 多个请求头 | 任意六、⭐ 路径拼接规则重点踩坑这是最容易出错的地方必须搞清楚。Retrofit 拼接 URL 遵循 RFC 3986 标准POST(“…”) 里的值会被当成相对 URL 用 HttpUrl.resolve() 解析。规则总结baseUrl POST 写法 最终 URL 结果 https://host/a/b/clisthttps://host/a/b/c/list ✅ 正确 https://host/a/b/c/listhttps://host/list ❌ 前缀被替换 https://host/a/b/c/listhttps://host/a/b/c/list ✅ 正确 https://hosta/b/c/listhttps://host/a/b/c/list ✅ 正确七、返回值处理7.1 返回 String原始响应POST(list)StringgetDeviceList(BodyDeviceListRequestVovo);拿到的是原始 JSON 字符串需要自己解析StringdeviceListremoteDeviceService.getDeviceList(vo);JSONObjectjsonObjectJSONObject.parseObject(deviceList);JSONObjectdatajsonObject.getJSONObject(data);ListDeviceOnLineVorecordsdata.getJSONArray(records).toJavaList(DeviceOnLineVo.class);7.2 返回对象推荐自动反序列化POST(list)ApiResponseDevicePagegetDeviceList(BodyDeviceListRequestVovo);对应的类DatapublicclassApiResponseT{privateStringcode;privateStringmessage;privateTdata;}DatapublicclassDevicePage{privateListDeviceOnLineVorecords;privatelongtotal;privatelongsize;privatelongcurrent;privatelongpages;}DatapublicclassDeviceOnLineVo{privateStringudid;privateStringip;privateIntegeronlineStatus;}7.3 各种返回类型对照方法返回类型 得到的结果 String 原始响应体字符串 ResultT/ 实体类 自动反序列化后的对象 CallString异步调用对象需 enqueue ResponseString含状态码、响应头等完整响应