简介这份资源面向需要与金蝶苍穹平台做系统集成的Java开发者聚焦第三方系统向苍穹上传附件、引入业务数据的接口实现。压缩包共8个文件全部为java源码整体约13KB涵盖登录鉴权、HTTP请求封装、文件上传服务及带附件的远程操作等核心类另含自定义保存插件示例便于直接参考改造。内容围绕接口调用、身份验证、文件编码压缩、异步处理、错误重试、数据安全与日志记录等关键环节展开可帮助读者理解苍穹附件管理的完整链路。目前已有326人学习下载适合具备一定Java与接口开发基础、希望快速打通苍穹文件上传流程的工程师通过阅读源码即可掌握可复用的集成思路与排错方向。1. 从一份 Java 源码包说起第三方系统怎么把附件塞进苍穹做过金蝶苍穹集成的人大概都遇到过这个场景OA 走完审批合同 PDF 要自动挂到苍穹的采购订单下面或者 MES 产出的质检报告得定时推到苍穹对应批次记录里。苍穹本身有附件管理但第三方系统怎么调、用什么身份调、文件流怎么传官方文档给的是接口定义真正落地时一堆细节没人告诉你。这份「上传文件至金蝶苍穹平台.zip」就是干这个的——里面是一套可读可改的 Java 源码围绕BizOperateService、HttpClientFactory、HttpService、AppLoginService、UserLoginService、FileUploadService、RemoteOperationWithAttachment以及一个BizCustomSaveWebApiPlugin插件类展开覆盖了从登录鉴权、构造 HTTP 请求、上传附件到业务数据保存的完整链路。适合正在做苍穹与外部系统对接的后端尤其是被附件上传卡过的人。2. 拆开源码包登录、请求、上传三条链路怎么串2.1 先搞清楚苍穹附件接口的调用模型苍穹的开放接口不是「一个 URL 传个文件」那么简单。它的附件上传通常分两步走第一步先调文件上传接口把二进制流推上去拿到一个文件标识fileId 或类似的东西第二步在保存业务数据时把这个标识挂到对应字段上。这个源码包里FileUploadService负责的就是第一步RemoteOperationWithAttachment更像是把「上传 业务保存」串起来的编排类而BizCustomSaveWebApiPlugin是苍穹侧的插件入口——也就是说它可能同时包含了调用方和服务端扩展两部分的示例。为什么要有AppLoginService和UserLoginService两个登录类这是苍穹鉴权的常见做法应用级登录拿的是应用身份用户级登录拿的是具体用户上下文。第三方系统如果代表某个操作员上传附件通常需要用户级令牌否则附件的创建人、所属组织可能对不上后续权限过滤会出问题。AppLoginService一般用于系统间无用户场景的数据同步UserLoginService用于需要记录操作人的场景。选哪个取决于你的附件要不要在苍穹界面上被人看到、被谁看到。HttpClientFactory和HttpService是基础设施层。前者管连接池、超时、重试策略后者封装 GET/POST、表单提交、文件 multipart 构造。很多团队自己写 HttpClient 也能跑但连接不复用、超时不设、异常不分类量一上来就是各种玄学超时。这个包里把工厂和门面分开思路是对的——工厂管生命周期Service 管业务语义。2.2 环境准备与依赖确认拿到 zip 之后先别急着跑。这类源码包通常不带完整工程文件你需要自己建一个 Maven 或 Gradle 项目把 Java 文件放进去然后补依赖。常见做法是# 解压后先看目录结构确认有没有 pom.xml 或 lib unzip 上传文件至金蝶苍穹平台.zip -d cangqiong-upload cd cangqiong-upload find . -name *.java | head -20 find . -name pom.xml -o -name *.jar | head如果包里没有pom.xml说明它是纯源码片段需要你自己补。核心依赖一般包括 HTTP 客户端和 JSON 处理!-- pom.xml 关键依赖版本按你项目统一管理 -- dependencies dependency groupIdorg.apache.httpcomponents/groupId artifactIdhttpclient/artifactId version4.5.14/version /dependency dependency groupIdorg.apache.httpcomponents/groupId artifactIdhttpmime/artifactId version4.5.14/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.15.2/version /dependency /dependencieshttpmime是必须的因为 multipart 上传要用MultipartEntityBuilder。如果你用 OkHttp 或 Java 11 的HttpClient也能实现但这个包里的HttpService大概率是基于 Apache HttpClient 写的跟着它的风格走改起来最省事。JDK 版本建议 8 以上苍穹服务端本身对 JDK 有要求但调用方这边 8 或 11 都能跑。2.3 登录鉴权AppLoginService 与 UserLoginService 的取舍先看登录。苍穹的登录接口一般需要传acctId账套、username、password或应用密钥返回一个 token。这个包里两个 Service 的差异从命名就能猜个大概// AppLoginService 典型调用形态根据源码结构还原 public class AppLoginService { private String appId; private String appSecret; private String baseUrl; public String login() throws IOException { // 构造应用登录请求换取 access_token MapString, String params new HashMap(); params.put(appId, appId); params.put(appSecret, appSecret); params.put(acctId, 你的账套ID); String response HttpService.postForm(baseUrl /api/login/app, params); // 解析 token注意过期时间 return JsonUtil.read(response, data.access_token); } }UserLoginService则多传用户标识返回的 token 绑定了用户上下文。参数上要特别注意acctId——苍穹是多账套的传错了账套接口可能返回成功但数据写到了另一个账套里这种坑排查起来非常费劲。我一般会在配置里把baseUrl、acctId、appId做成外部配置不硬编码。提示token 一般有有效期生产环境不要每次上传都重新登录做一个带过期时间的缓存。但缓存 key 要区分应用级和用户级混用会导致权限错乱。2.4 构造 multipart 请求FileUploadService 的关键参数FileUploadService是核心。它要做的事拿本地文件路径或 InputStream构造 multipart/form-data 请求带上 token 和必要的表单字段POST 到苍穹的文件上传接口。// FileUploadService 上传逻辑示意 public String upload(String token, File file, String bizType) throws IOException { CloseableHttpClient client HttpClientFactory.getClient(); HttpPost post new HttpPost(baseUrl /api/file/upload); post.setHeader(Authorization, Bearer token); // 关键multipart 构造文件名和字段名要和苍穹接口约定一致 MultipartEntityBuilder builder MultipartEntityBuilder.create(); builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE); builder.addBinaryBody(file, file, ContentType.APPLICATION_OCTET_STREAM, file.getName()); builder.addTextBody(bizType, bizType); // 业务类型影响存储路径 post.setEntity(builder.build()); try (CloseableHttpResponse resp client.execute(post)) { String body EntityUtils.toString(resp.getEntity(), UTF-8); // 解析返回的 fileId后续挂附件要用 return JsonUtil.read(body, data.fileId); } }几个参数必须和苍穹侧对齐file字段名不能改bizType决定文件存到哪个业务目录Authorization头的格式要看登录接口返回的是不是带Bearer前缀。文件名建议保留原始扩展名苍穹可能根据扩展名做预览处理。返回的fileId一定要存下来这是后续业务保存时挂附件的唯一凭据。2.5 把附件挂到业务数据RemoteOperationWithAttachment 的编排上传拿到fileId只是第一步。真正让附件出现在订单、合同、批次记录上还得调业务保存接口把fileId塞进附件字段。RemoteOperationWithAttachment这个类名暗示了它的职责远程操作 附件。// 业务保存时挂附件的示意 public void saveWithAttachment(String token, String billId, String fileId) { MapString, Object data new HashMap(); data.put(billId, billId); // 附件字段通常是数组结构支持多个附件 data.put(attachment, Collections.singletonList( Collections.singletonMap(fileId, fileId) )); String json JsonUtil.write(data); HttpService.postJson(baseUrl /api/biz/save, token, json); }BizCustomSaveWebApiPlugin是苍穹服务端的扩展点。如果你在苍穹侧要自定义保存逻辑——比如上传后自动解析 PDF 内容、或者根据附件类型触发不同流程——这个插件类就是入口。它和调用方代码放在一起说明这份资源是「两端都有」的示例不只是客户端。3. 避坑排查附件上传最常见的五类翻车3.1 上传成功但界面上看不到附件现象接口返回fileId日志显示 200但苍穹单据的附件列表是空的。原因多数情况是只调了文件上传接口没调业务保存接口或者业务保存时附件字段名写错了。苍穹的附件是「文件 关联」两步缺一步都不显示。解决确认RemoteOperationWithAttachment里保存逻辑有没有执行抓包看业务保存请求体里attachment字段的结构对照苍穹接口文档的字段名和层级。常见错误是传了fileId但外层少了数组包装。3.2 登录返回 401 或 token 无效现象登录接口能返回 token但调上传接口时报 401。原因token 类型用错了。应用级 token 调用户级接口或者 token 过期没刷新或者Authorization头格式不对有的接口要Bearer有的直接放 token。解决先确认你调的上传接口需要哪种 token在HttpService里加日志打印请求头检查 token 缓存有没有把应用级和用户级混在一起。我一般会在AppLoginService和UserLoginService里各打一个 tag日志里一眼能看出用的哪个。3.3 大文件上传超时或内存溢出现象小文件正常几十兆的 PDF 就超时或者 JVM 报 OOM。原因FileUploadService如果用的是byte[]或ByteArrayInputStream把整个文件读进内存大文件必炸。另外 HttpClient 默认超时可能只有几十秒。解决改用FileBody或InputStreamBody流式上传不要自己读成 byte 数组。HttpClientFactory里把socketTimeout和connectTimeout调大比如 5 分钟。如果苍穹侧支持分块上传优先用分块。3.4 文件名乱码或扩展名丢失现象上传后苍穹里文件名变成乱码或者没有后缀打不开。原因multipart 构造时没有指定文件名编码或者ContentType设成了text/plain导致苍穹不认扩展名。解决addBinaryBody的第四个参数传原始文件名ContentType用APPLICATION_OCTET_STREAM。如果还有乱码在MultipartEntityBuilder上设setCharset(StandardCharsets.UTF_8)。3.5 并发上传时连接池耗尽现象单线程没问题多线程批量上传时报ConnectionPoolTimeoutException或请求排队。原因HttpClientFactory返回的是单例 client 但连接池默认每路由只有 2 个连接并发一高就不够用。解决在工厂里设置PoolingHttpClientConnectionManager的setMaxTotal和setDefaultMaxPerRoute比如 50 和 20。同时确保响应实体被完全消费或关闭否则连接不释放。4. 进阶把上传封装成可复用组件与验证清单源码包给的是示例真正上生产得做几件事。第一把FileUploadService抽成接口实现类里注入配置方便换环境。第二加一个上传结果校验方法不只看 HTTP 200还要看业务返回码和fileId是否非空。第三做一个简单的验证清单每次改完代码走一遍验证项检查方式通过标准登录 token 有效调一个只读接口返回业务数据而非 401文件上传返回 fileId打印响应体fileId 非空且格式符合预期附件挂接成功苍穹界面查看单据附件能看到文件且能下载大文件50M传一个真实大文件不超时、不 OOM并发 10 线程用 JMeter 或脚本并发无连接池异常成功率 100%这里提一下 JMeter热搜里有人问 jmeter 上传文件其实用 JMeter 压这个接口很合适建一个线程组加 HTTP 请求勾选Use multipart/form-data文件路径填本地文件Header 里加Authorization。跑一轮就能看出并发下的问题。最后说个我自己的习惯每次对接新的苍穹环境先不写业务代码用curl或 Postman 把登录、上传、保存三个接口各调通一次把请求体和响应体存成文件。然后再照着这个包里的类结构写 Java。这样出问题时能快速判断是协议层还是代码层。从那以后我每次接苍穹附件需求都强制先跑一遍这个三步验证省了太多来回扯皮的时间。希望帮到你。本文还有配套的精品资源点击获取