简介基于SpringBoot框架整合京东开放平台接口的完整IDEA工程源码专为需要对接京东订单、工单等业务的Java后端开发者准备导入后即可运行学习。压缩包内含137个文件主要由98个XML映射与配置文件、27个Java源码文件、5个JSON测试数据文件以及yml配置、SQL建库脚本、JAR依赖等构成整体仅501KB轻量便于阅读。项目沉淀了“获取任务工单”等京东接口的实际调用范例通过修改serverUrl、accessToken等参数即可连通服务同时采用Controller、Service、DAO分层结构配合统一异常处理与单测入口可直观理解请求参数组装、HTTP调用、响应解析及错误处理全过程。已有842人学习下载适合希望快速掌握京东API对接技巧或借鉴成熟分层设计搭建第三方接口集成项目的开发者参考。1. 京东接口集成先从工程视角回答「完整项目」缺什么很多人在找「Java集成京东接口的完整idea项目源码」时下载到的往往是一堆散落文件导入IntelliJ IDEA后连编译都过不了。真正拿到京东开放平台的应用凭证后才发现困难不在业务参数而在签名不一致、网关地址选错、返回的result字段被当成普通对象解析。京东开放平台不像微信支付那样提供大一统SDK常见做法是自己封装客户端因此在IDEA里维护一套「签名 HTTP 业务解析」三层结构清晰的Maven工程才是集成时最省时间的路径。这篇博文按日常开发习惯讲清楚如何用IDEA社区版建立工程写出可复用的Java京东接口客户端并给出连调、排错和并发调用时需要注意的参数细节。无论电商ERP、选品工具还是数据平台这套工程都能演化成你自己的源码模板。2. 京东接口签名与网关选型先把调用规则拆开2.1 京东开放平台网关与凭证体系京东开放平台对外提供两类常用接口一类是宙斯开放平台API网关地址通常为https://gw-api.360buy.com/api另一类是京东联盟API网关为https://router.jd.com/api。严格来说网关并不是统一的不同接口可能挂在不同域名下所以要先把网关地址放到配置里而不是写死在某个接口调用片段中。我一般会在application.properties里配置jd.gateway.url方便在不同环境间切换。调用京东接口的凭证是AppKey和AppSecret。申请应用后AppSecret只显示一次后续只能在控制台重置。不少集成事故就出在把AppKey和AppSecret用错位置或者把AppSecret打进日志里。正确做法是用环境变量或配置中心管理这两个值避免提交到Git仓库。此外京东接口的权限是分接口授权的不是有了应用就能调所有API例如联盟商品查询和订单查询需要单独申请。对应到工程里就是一个接口一个权限检查错误码返回15通常就是没有权限。容易被忽略的是网关选型会影响公共参数的命名。比如宙斯API使用method和app_key联盟API也有一套公共参数。最稳妥的做法是打开对应接口文档页直接看「请求示例」以文档里的参数列表为准而不是套用网上零几年的旧代码。2.2 签名参数排序与MD5的九个细节京东接口的签名算法不算难但细节很多也是java面试题里常被拿来问的实现。标准流程是这样把所有请求参数放入一个Map剔除sign本身对参数名按ASCII码升序排序拼接成key1value1key2value2的形式在拼接字符串末尾追加AppSecret对整个字符串做MD5加密转成大写得到签名。这里有几个细节值得单独列出来。第一排序时用TreeMap保证顺序不要手工排序。第二拼接时value不需要做URL编码直接用原始字符串。第三值为null的参数要跳过不能让keynull参与签名。第四时间戳timestamp格式通常是yyyy-MM-dd HH:mm:ss参与签名时保持原始字符串不要重新格式化否则验签必失败。第五MD5加密后的结果必须大写sign_method固定为md5。第六数字参数如商品ID要转成字符串用String.valueOf。第七不要用JSONObject.toJSONString整体作为签名源串除非文档明确要求。第八如果业务参数里有嵌套对象例如批量查询的skuIds是JSON数组参与签名的值是数组的JSON字符串并且字符串内的引号、逗号要和实际发送时完全一致。第九也是踩得最多的坑AppSecret末尾可能有空格或换行符导致签名看似相同但MD5不同。建议读取Secret后做一次trim()。下面给出一个最小签名生成的Java代码便于在IDEA里写单元测试验证。import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.Map; import java.util.TreeMap; public class JdSignUtil { public static String buildSign(MapString, String params, String appSecret) { TreeMapString, String sorted new TreeMap(params); StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sorted.entrySet()) { if (entry.getValue() null || entry.getKey().equals(sign)) { continue; } sb.append(entry.getKey()).append() .append(entry.getValue()).append(); } sb.setLength(sb.length() - 1); // 去掉末尾 sb.append(appSecret.trim()); // 拼接密钥 return md5(sb.toString()).toUpperCase(); } private static String md5(String src) { try { MessageDigest md MessageDigest.getInstance(MD5); byte[] bytes md.digest(src.getBytes(StandardCharsets.UTF_8)); StringBuilder hex new StringBuilder(); for (byte b : bytes) { hex.append(String.format(%02x, b)); } return hex.toString(); } catch (Exception e) { throw new IllegalStateException(MD5签名失败, e); } } }代码里TreeMap负责按ASCII排序setLength抹掉末尾的拼上appSecret后统一按UTF-8做MD5。注意toUpperCase()放在最后转大写后服务端校验才对得上。建议在本地先打印签名源串与文档调试工具里的示例对比确认无误再继续联调。2.3 请求公共参数与响应包裹结构公共参数每个接口都要带以京东联盟API为例表格如下参数名示例说明methodjd.union.open.promotion.common.get接口标识app_key你的AppKey应用标识timestamp2025-04-27 10:00:00发请求时间formatjson响应格式v1.0版本号sign_methodmd5签名算法sign2AEF...签名结果这组参数会连同业务参数一起做签名。响应外层通常是{响应体key:{result:{\code\:200,...}}}这里有一个隐藏坑result值不是普通JSON对象而是JSON字符串需要先取出来再二次解析。3. 在IDEA里把京东接口集成项目从0搭成Maven骨架3.1 IDEA社区版建Maven工程与JDK配置用IntelliJ IDEA社区版做这个项目完全够用。打开IDEA后选择File - New - Project在左侧选JDK版本我平时用JDK 8因为大多数电商技术栈还停留在Java 8上中文教程和面试题也大多围绕这个版本展开。不勾选任何模板直接点Next生成一个干净的Maven项目。IDEA社区版对Maven的支持很完整在Settings - Build, Execution, Deployment - Build Tools - Maven里能配置settings.xml、本地仓库和镜像地址。如果新建后没有src/main/java目录需要右键目录选择Mark Directory as Sources Root。IDEA社区版首次构建时会下载Maven插件和依赖国内网络经常很慢在settings.xml里配好阿里云镜像会顺利很多。另外IDEA长时间编译大工程偶尔会卡顿如果出现莫名的自动关闭可以在Help - Edit Custom VM Options里把-Xmx调大到2048m这是团队里最常见的解法。3.2 pom.xml依赖HttpClient、Fastjson与Lombok接口客户端不需要引入Spring全家桶一个干净的pom.xml就能跑。下面这套依赖是企业里最常见的组合兼容IDEA社区版与JDK 8project modelVersion4.0.0/modelVersion groupIdcom.demo/groupId artifactIdjd-union-client/artifactId version1.0-SNAPSHOT/version properties maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target /properties dependencies dependency groupIdorg.apache.httpcomponents/groupId artifactIdhttpclient/artifactId version4.5.14/version /dependency dependency groupIdcom.alibaba/groupId artifactIdfastjson/artifactId version1.2.83/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version1.18.30/version scopeprovided/scope /dependency /dependencies /projecthttpclient负责发送HTTPS请求fastjson处理JSON解析和序列化lombok在编译期生成getter/setter。三个依赖定位不同httpclient管网络、fastjson管数据格式、lombok只是编译期工具不会打进最终产物。如果不熟悉lombok需要在IDEA里安装Lombok插件并开启Annotation Processing否则编译时一调用getter就会报错。如果想用Spring Boot则在这个基础上追加spring-boot-starter-web和spring-boot-starter-test。IDEA中还可以借助Docker插件快速打包运行环境在Run Configuration里新建Dockerfile运行项指定镜像名和jar包路径点运行即可把整个服务封装为镜像省去手敲docker build命令这对后续部署到服务器很实用。3.3 按「签名、HTTP、业务」三层规划源码目录能长期维护的京东接口集成项目目录结构不应该把代码全堆在一个类里。我常用的工程结构如下src/main/java/com/demo/jdunion/ ├── config # 配置读取AppKey、Secret、网关地址 ├── client # JdClient统一的请求执行入口 ├── model # 请求/响应POJO │ ├── parameter # 各接口业务参数 │ └── result # 响应解析模型 ├── service # 业务层具体接口的调用与转换 └── util # JdSignUtil、StringUtil等这样分层有明确理由签名工具类属于纯函数可以直接写单元测试client层只负责「签名 - 发HTTP - 拿到result字符串」service层负责把result字符串解析成业务对象。当京东升级接口版本只需改model和service不会影响HTTP逻辑。如果之后要处理多线程批量查询service层的实现还可以和线程池方便地组合把并发参数外置到配置文件里运维时不用改代码。4. 用Java写一个能应对签名和二次解析的JdClient4.1 请求对象与签名生成代码先定义一个统一的JdRequest对象把公共参数和业务参数分开。业务参数这里直接用TreeMap接收而不是为每个接口建一个DTO理由是京东接口的「可空」字段很多DTO反而增加了维护成本Map更贴近文档结构。package com.demo.jdunion.model; import lombok.Getter; import lombok.Setter; import java.util.Map; import java.util.TreeMap; Getter Setter public class JdRequest { private String method; private String appKey; private String timestamp; private String format json; private String v 1.0; private String signMethod md5; private MapString, String bizParams new TreeMap(); public MapString, String toParamMap() { TreeMapString, String map new TreeMap(); map.put(method, method); map.put(app_key, appKey); map.put(timestamp, timestamp); map.put(format, format); map.put(v, v); map.put(sign_method, signMethod); map.putAll(bizParams); return map; } }toParamMap把公共参数和业务参数合并到同一个TreeMap中后续签名时自动按key排序。bizParams声明为TreeMap是为了让业务参数内部也保持有序虽然最终签名是按整体排序但有序结构在打印调试信息时更直观。用lombok的Getter Setter后IDEA里写调用代码时也能直接提示方法名。4.2 基于HttpClient的POST封装与超时控制下面是JdClient核心类的HTTP调用部分。京东接口普遍要求POST表单提交Content-Type为application/x-www-form-urlencoded。使用HttpClient的连接池管理连接并设置三组超时时间。package com.demo.jdunion.client; import com.demo.jdunion.model.JdRequest; import com.demo.jdunion.util.JdSignUtil; import org.apache.http.NameValuePair; import org.apache.http.client.config.RequestConfig; import org.apache.http.client.entity.UrlEncodedFormEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.impl.conn.PoolingHttpClientConnectionManager; import org.apache.http.message.BasicNameValuePair; import org.apache.http.util.EntityUtils; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.List; import java.util.Map; public class JdClient { private final String appKey; private final String appSecret; private final String gatewayUrl; private final CloseableHttpClient httpClient; public JdClient(String appKey, String appSecret, String gatewayUrl) { this.appKey appKey; this.appSecret appSecret; this.gatewayUrl gatewayUrl; PoolingHttpClientConnectionManager cm new PoolingHttpClientConnectionManager(); cm.setMaxTotal(50); cm.setDefaultMaxPerRoute(20); this.httpClient HttpClients.custom() .setConnectionManager(cm) .setDefaultRequestConfig(RequestConfig.custom() .setConnectTimeout(3000) .setConnectionRequestTimeout(3000) .setSocketTimeout(5000) .build()) .build(); } public String execute(JdRequest request) throws Exception { MapString, String params request.toParamMap(); params.put(sign, JdSignUtil.buildSign(params, appSecret)); ListNameValuePair form new ArrayList(); for (Map.EntryString, String entry : params.entrySet()) { form.add(new BasicNameValuePair(entry.getKey(), entry.getValue())); } HttpPost post new HttpPost(gatewayUrl); post.setEntity(new UrlEncodedFormEntity(form, StandardCharsets.UTF_8)); try (CloseableHttpResponse response httpClient.execute(post)) { return EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8); } } }连接池的MaxTotal和DefaultMaxPerRoute要结合并发量调整。单线程跑任务时这两个值设小点没问题如果后续用线程池并发调用DefaultMaxPerRoute至少要等于最大并发线程数否则高并发时请求会在连接池里排队。超时时间也有讲究京东大促时部分接口响应会接近3秒socketTimeout给5秒算是一个平衡值做批量查询的场景可以单独放宽到10秒而不是在同一份配置里改。4.3 泛型响应解析与JSON字符串result处理实际上execute返回的字符串不能直接JSON.parseObject成目标业务对象。京东响应体常见结构是{ jd_union_open_promotion_common_get_responce: { result: {\code\:200,\data\:{...}} } }内层result是一个被转义过的JSON字符串。封装一个泛型方法先解析外层再取出result最后转成指定类型public T T executeForObject(JdRequest request, String resultKey, ClassT clazz) throws Exception { String respBody execute(request); JSONObject outer JSON.parseObject(respBody); JSONObject response outer.getJSONObject(resultKey); if (response null) { throw new RuntimeException(接口响应缺少外层key resultKey); } String result response.getString(result); JSONObject resultObj JSON.parseObject(result); if (resultObj.getIntValue(code) ! 200) { throw new RuntimeException(业务错误 resultObj.getString(message)); } return resultObj.getObject(data, clazz); }resultKey是每个接口响应外层独有的key例如jd_union_open_promotion_common_get_responce。把它作为方法的参数是为了让同一个解析逻辑适配不同接口而不是为每个接口单独写一个解析方法。业务层只需要一行GoodsDetailResp resp jdClient.executeForObject( req, jd_union_open_goods_detail_query_responce, GoodsDetailResp.class);这里经历的完整动作是签名、发POST、解析外层、校验code、取data。service层保持干净后续调整解析逻辑也不会影响业务代码。4.4 并发查询时用CompletableFuture等待线程完成批量查询商品时单个接口对商品数量有限制串行循环会慢。常见做法是用固定大小的线程池并发执行多个请求最后等所有任务完成后汇总。这里使用CompletableFuture比手写Future加CountDownLatch更直观也和 java juc 包的设计思路一致ExecutorService pool Executors.newFixedThreadPool(8); ListCompletableFutureGoodsDetailResp futures new ArrayList(); for (String skuId : skuIds) { CompletableFutureGoodsDetailResp future CompletableFuture.supplyAsync(() - { JdRequest req buildSkuRequest(skuId); return jdClient.executeForObject(req, ...responce, GoodsDetailResp.class); }, pool).exceptionally(e - { log.error(查询SKU {} 失败, skuId, e); return null; }); futures.add(future); } CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();allOf().join()会等待所有线程完成再返回结果exceptionally保证单个任务失败不会让整个批量流程卡死。并发数不能无脑调大京东接口有QPS限制超过后返回频率控制错误码这时要做退避重试。合理做法是在线程池外层加一个Semaphore把全局并发控制在20以内线程池大小和信号量手数都可以从配置文件读取。5. 连调验证与三个高频坑从签名原串到错误码排查5.1 用JUnit跑通第一个真实接口不要一上来就启动Web应用先在src/test/java里写一个JUnit用例。测试代码里通过环境变量传入AppKey和AppSecret避免密钥硬编码。Test public void testQueryGoods() throws Exception { JdClient client new JdClient( System.getenv(JD_APP_KEY), System.getenv(JD_APP_SECRET), https://router.jd.com/api); JdRequest req new JdRequest(); req.setMethod(jd.union.open.goods.query); req.setTimestamp(new SimpleDateFormat(yyyy-MM-dd HH:mm:ss).format(new Date())); req.getBizParams().put(goodsReq, {\keyword\:\手机\}); String body client.execute(req); System.out.println(body); }时间戳格式必须和签名时完全一致。第一次连调大概率遇到sign not correct最快的定位方法是在JdSignUtil.buildSign里打印签名源串再核对MD5结果。不要直接拿拼接了AppSecret的签名串去在线工具算密钥可能泄露建议写个本地main方法做单向验证。5.2 三个高频坑第一个坑是AppSecret没有trim()。复制粘贴容易带上换行或空格读取配置后统一trim()是成本最低的防御代码。第二个坑是接口无权限错误码15时不是签名问题而是应用没有申请该接口权限。在开放平台控制台找到对应接口申请并等待审核审核通过后通常需要十分钟到两小时才生效。第三个坑是result是JSON字符串却被当成对象直接解析会抛JSONException看到JSON parse error: expect {时先打印response.getString(result)它大概率是带引号的字符串。用前面封装好的executeForObject可以天然规避这个问题。5.3 生产前压测时重点看连接池全链路跑通后建议用JMeter做一个十分钟的小压测重点看两个指标线程池排队时间和连接池的占用数。如果出现ConnectionPoolTimeoutException不是网关变慢而是DefaultMaxPerRoute小于并发数需要同时调大MaxTotal。另外HTTPS网关握手开销不小尽量复用同一个JdClient实例不要每次请求都重新创建连接池。最后送你一个习惯把「打印签名源串」做成一个可配置的开关测试环境打开生产环境关闭。这样线上真的出现验签失败时不用改代码也能第一时间看到签名原串这个开关能救回很多次棘手的联调问题。本文还有配套的精品资源点击获取