说来也挺巧最近手上的一个小项目需要把本地文件往 Box 云存储上搬还要能从 Box 拉回来。用 Java 捣鼓了几天从 OAuth 授权到上传下载全流程都跑通了。Box 这类服务本身 API 做得很完整但对第一次接触的人来说坑其实不少认证方式绕、大文件容易超时、分片边界踩错就报错。这篇东西把思路和代码整理出来针对的是刚接触 Box、想用 Java 快速实现文件上传下载的同学也适合已经能上传但经常被各种异常搞懵的老哥参考。我尽量把每一步的“为什么这么做”也讲清楚不只是贴代码。因为 Box API 的坑往往不在语法而在你对它的设计逻辑不理解。搞懂了它的授权方式、上传会话机制、分片校验规则后面写代码就是水到渠成的事。1. Box 平台接入的整体思路1.1 Box API 能做什么Box 是一个面向企业和个人的云存储平台它的核心能力是让外部系统通过 REST API 操作远端文件。我们这次用到的功能其实只占很小一部分文件上传、文件下载、文件夹列表、创建文件夹、获取文件元数据。它的 API 版本目前常用的是 2.0所有接口都在/2.0路径下数据格式为 JSON。除了基本文件操作它还支持搜索、评论、协作、权限管理、Webhook 等。但对于“浅度接触”的项目来说先跑通上传下载比什么都重要。你不需要一次性吃透整个平台只要掌握一条完整链路认证 - 拿 Token - 上传 - 下载 - 处理错误就能应付大多数业务场景。我不太建议一上来就引入官方 SDK虽然那样省事但它会帮你隐藏很多细节。一旦遇到超时、分片、重试这类真实问题你如果不知道底层发生了什么排查起来会很痛苦。所以我下面所有的实现都用纯 HTTP 调用完成配合一个小型工具类反而更好控制和理解。1.2 技术上真正要解决的问题用 Java 对接 Box表面上只是发几个 HTTP 请求但实际落地有三个核心难点。第一个是认证。Box 使用的是 OAuth 2.0 授权模式用户或者应用必须先拿到访问令牌Access Token之后每一个 API 请求都要在请求头里带上Authorization: Bearer token。Token 有时效性过期后要刷新如果你的程序是多线程并发访问还要避免刷新令牌时大家互相踩踏。第二个是传输方式。小文件可以直接用multipart/form-data上传但大文件不行必须走分片上传Upload Session。分片上传不是简单把文件拆开几个部分传上去就完了它要求你先创建一个上传会话告诉 Box 文件大小、文件名、目标文件夹然后按它给你分配的分片大小逐个上传。每个分片还得附带 SHA-1 摘要提交阶段更麻烦需要整个文件的摘要。第三个是异常处理。网络超时、服务端限流、Token 失效、同名文件冲突、文件被锁等这些在真实运行环境里都会出现。良好的异常处理机制不是捕获后打印日志而是要能识别错误码、判断是否需要重试、是否要刷新 Token、是否要提示用户调整参数。1.3 技术组件选型这次我用的技术栈很轻JDK 11、OkHttp、Jackson、SLF4J。没引入 Spring也没上全家桶目的是让代码逻辑更直观。你自己项目里有 Spring Boot 也完全没问题核心代码是可以平迁的。选 OkHttp 而不是 JDK 自带的HttpClient主要是因为它对连接超时、读取超时、重定向、连接池的控制更细而且MultipartBody对上传表单的支持比原生 API 方便很多。Jackson 就是做 JSON 序列化和反序列化Box 返回的 JSON 字段多且风格统一用 Jackson 解析省事。另外强烈建议在项目里统一封装一个BoxApiClient类把 Token 管理、HTTP 调用、错误处理都收敛在里面。你如果把这些逻辑散落在业务代码里后面每加一个接口就要复制粘贴一轮迟早会出事。2. 准备工作与授权流程详解2.1 开发者应用配置在正式调用 API 之前需要先有一个 Box 开发者账号并在开发者后台创建一个自定义应用。这个过程不同后台版本界面不一样但核心要素是一样的。应用创建完之后你必须要拿到两样东西client_id和client_secret。这就是你应用的身份标识。同时你还要配置重定向 URIRedirect URI也就是授权成功之后 Box 把用户或者临时授权码带回的那个地址。本机调试的时候可以直接填一个http://localhost:8080/callback之类的地址但要注意Box 只接受你在后台白名单里配置过的 URI你随便写一个都会报redirect_uri不匹配。在应用类型选择上如果你的业务是“用户上传自己的文件”建议用标准 OAuth 2.0 授权码模式如果是后台服务、没有用户交互界面可以考虑 JWT 服务账号模式。但 JWT 的密钥管理、断言生成会复杂不少所以“浅度接触”阶段我推荐先走授权码模式把链路跑通再说。2.2 OAuth 2.0 授权码流程授权码模式的流程可以用一句话概括先让用户去 Box 授权页面点一下Box 回调你的地址并带上一个临时code然后你用这个code去换取access_token和refresh_token。第一步是拼接授权地址让用户跳转https://account.box.com/api/oauth2/authorize?client_idYOUR_CLIENT_IDresponse_typecoderedirect_urihttp://localhost:8080/callback用户同意后Box 会重定向到你的回调地址并在 URL 上带一个?codexxx参数。拿到这个 code 之后你的后端再发起 Token 请求POST https://api.box.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_typeauthorization_code codexxx client_idYOUR_CLIENT_ID client_secretYOUR_CLIENT_SECRET redirect_urihttp://localhost:8080/callback用 Java 实现时我为了方便直接发了一个表单请求没有额外引 OAuth SDKprivate String exchangeCodeForToken(String code) throws IOException { OkHttpClient client new OkHttpClient(); FormBody body new FormBody.Builder() .add(grant_type, authorization_code) .add(code, code) .add(client_id, CLIENT_ID) .add(client_secret, CLIENT_SECRET) .add(redirect_uri, REDIRECT_URI) .build(); Request request new Request.Builder() .url(https://api.box.com/oauth2/token) .post(body) .build(); try (Response response client.newCall(request).execute()) { if (!response.isSuccessful()) { throw new IOException(Token request failed: response.code()); } String responseBody response.body().string(); // 解析 JSON取出 access_token、refresh_token、expires_in JsonNode node new ObjectMapper().readTree(responseBody); return node.get(access_token).asText(); } }需要注意redirect_uri必须和授权时传的完全一致不能多一个斜杠也不能漏掉端口。我踩过的坑就是授权时写http://localhost:8080/callback换取 Token 时写成了http://localhost:8080/callback/结果 Box 直接返回 400。2.3 Token 刷新与并发保护access_token不是永久的Box 默认过期时间通常是一个小时左右。如果令牌过期你调用文件接口会得到 HTTP 401。解决办法是用refresh_token再换一个新的POST https://api.box.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_typerefresh_token refresh_tokenREFRESH_TOKEN client_idYOUR_CLIENT_ID client_secretYOUR_CLIENT_SECRET代码逻辑很简单但多线程环境下要注意一个问题多个线程同时发现 Token 过期然后同时去刷新结果只有一个刷新请求成功其他线程拿到的还是旧 Token或者因为旧 Token 被刷新而失效。我的处理方案是给 Token 刷新加锁并且刷新成功之后立即更新内存里的 Token 引用private volatile String accessToken; private final ReentrantLock tokenLock new ReentrantLock(); public String getValidToken() throws IOException { if (accessToken ! null expiresAt System.currentTimeMillis() 30_000) { return accessToken; } tokenLock.lock(); try { if (accessToken ! null expiresAt System.currentTimeMillis() 30_000) { return accessToken; } refreshAccessToken(); return accessToken; } finally { tokenLock.unlock(); } }这种双重检查写法既避免了重复刷新也不至于每个请求都等锁。另外建议在本地保存refresh_token否则进程重启之后还得让用户重新授权。3. 文件上传的实现细节3.1 小文件直接上传文件上传是 Box API 里最常用的接口。小文件比如几十 MB 以下直接发一个multipart/form-data请求就行接口是POST https://api.box.com/2.0/files/content请求体里有两个字段一个是attributes是个 JSON 字符串必须包含文件名和目标文件夹 ID另一个是file就是文件二进制内容。我用 OkHttp 实现时代码是这样的private String uploadSimpleFile(Path file, String folderId, String token) throws IOException { OkHttpClient client new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(60, TimeUnit.SECONDS) .build(); long fileSize Files.size(file); String attributes String.format({\name\:\%s\,\parent\:{\id\:\%s\}}, file.getFileName(), folderId); RequestBody fileBody RequestBody.create(file.toFile(), MediaType.parse(application/octet-stream)); RequestBody multipart new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(attributes, attributes) .addFormDataPart(file, file.getFileName().toString(), fileBody) .build(); Request request new Request.Builder() .url(https://api.box.com/2.0/files/content) .header(Authorization, Bearer token) .post(multipart) .build(); try (Response response client.newCall(request).execute()) { String body response.body().string(); if (!response.isSuccessful()) { throw new IOException(Upload failed, code response.code() , body body); } JsonNode fileNode new ObjectMapper().readTree(body).path(entries).get(0); return fileNode.get(id).asText(); } }这里有几个细节attributes里的文件名不能包含路径分隔符必须只是文件名parent的id如果是根目录就传0。另外application/octet-stream是通用二进制类型如果不知道文件 MIME 类型用它最保险。你如果传的是图片、PDF也可以用对应的 MIME但 Box 不会因为 MIME 不同而区别处理。3.2 大文件分片上传从建会话到提交超过一定大小或者你不确定网络稳定性的文件建议使用分片上传。这个机制很有意思它不是一个纯粹的“把文件分片传上去”的过程而是先让 Box 告诉你“你该怎么分片”。第一步创建上传会话POST https://api.box.com/2.0/files/upload_sessions Authorization: Bearer token Content-Type: application/json { folder_id: 0, file_size: 5368709120, file_name: big-file.iso }Box 返回的 JSON 里会包含一个id、一个part_size还有total_parts。part_size是服务端根据你的文件大小自动算出来的它通常稳定在一个固定值附近比如 32MB、64MB 或者 128MB具体取决于文件总量。你不需要自己去硬编码分片大小而是应该以后端返回的part_size为准。接着你需要把文件按part_size切分每个分片用独立请求上传。分片上传的地址是PUT https://api.box.com/2.0/files/upload_sessions/{SESSION_ID} Authorization: Bearer token Content-Type: application/octet-stream Content-Range: bytes 0-33554431/5368709120 Digest: shabase64字符串Content-Range的格式是bytes 起始位置-结束位置/总大小总大小是完整文件的字节数不是分片字节数。Digest是当前分片的 SHA-1 哈希但是要用 Base64 编码并且拼上sha前缀。Java 计算分片摘要的代码大致是这样private static String sha1DigestBase64(byte[] data) throws Exception { MessageDigest md MessageDigest.getInstance(SHA-1); byte[] digest md.digest(data); return sha Base64.getEncoder().encodeToString(digest); }最麻烦的是提交阶段。所有分片传完之后你要发送一个提交请求这个请求的Digest必须是整个文件的 SHA-1不是某个分片的POST https://api.box.com/2.0/files/upload_sessions/{SESSION_ID}/commit Authorization: Bearer token Content-Type: application/json Digest: sha整个文件SHA1 { parts: [ {part_id: 返回的分片ID, offset: 0, size: 33554432, sha1: 分片SHA1}, ... ] }parts数组里的信息是上传每个分片时 Box 响应里返回的。你必须把那些part_id、offset、size、sha1原样保存下来提交时原样传回去。我之前图省事想着重新算一下分片 SHA1 提交就行结果 Box 返回 400提示 part 信息不匹配。老老实实把上传响应保存成 JSON最稳。3.3 上传进度与重试策略分片上传天然适合做进度显示因为你每传完一片就能知道已经传了多少。如果只是简单上传整个文件进度条想做得平滑就得靠读文件时手动统计字节数麻烦不说还容易打扰主流程。我在做进度统计时用了一个简单的包装类记录uploadedBytes和totalBytes。每传完一个分片就累加分片大小然后把当前百分比打出来。真实项目里可以把这些值推给前端轮询接口。重试策略上我的建议是分片请求失败后不要从第一片重启要记录已上传完成的分片 ID从失败的那个分片开始重传。Box 的 upload session 在没有 commit 之前是允许重复上传某个分片的你只需要保证最终所有分片都成功即可。一个小技巧是每个分片上传前先判断该分片之前是否已经成功上传。你可以把已成功上传的part_id存在本地一个列表里重试时跳过。这样即使网络抖动很严重任务也能慢慢推进而不是反复推倒重来。4. 文件下载与目录操作4.1 获取文件信息在下载文件之前通常先要确认文件是否存在、有多大、是什么类型。Box 的元数据接口很直接GET https://api.box.com/2.0/files/{file_id} Authorization: Bearer token返回的 JSON 里有name、size、created_at、modified_at、etag等字段。其中etag是个好东西如果你做增量同步可以把本地缓存的 etag 和服务端的做对比如果一致就跳过下载减少不必要的流量。拿到size之后也可以预判下载时长。如果文件特别大建议别一把梭直接下到内存而是用流式写入加断点续传。不过 Box 的下载接口本身支持 HTTP Range也就是你可以用Range: bytesxxx-xxx请求文件的部分内容。这为断点续传提供了很大方便。4.2 下载文件内容Box 下载文件的 URL 是GET https://api.box.com/2.0/files/{file_id}/content正常情况下Box 会返回 HTTP 302把请求重定向到一个临时的下载地址。你不需要手动处理这个重定向OkHttp 默认会跟随重定向直接拿到最终文件内容。但我需要提醒一点重定向后的地址是有时效性的通常是几分钟所以你不要把它存下来以后重用每次下载都应该重新走一遍。基础下载实现private void downloadFile(String fileId, Path targetPath, String token) throws IOException { OkHttpClient client new OkHttpClient.Builder() .followRedirects(true) .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(120, TimeUnit.SECONDS) .build(); Request request new Request.Builder() .url(https://api.box.com/2.0/files/ fileId /content) .header(Authorization, Bearer token) .build(); try (Response response client.newCall(request).execute()) { if (!response.isSuccessful()) { throw new IOException(Download failed, code response.code()); } try (InputStream inputStream response.body().byteStream(); OutputStream outputStream new FileOutputStream(targetPath.toFile())) { inputStream.transferTo(outputStream); } } }这段代码看着简单但实际生产环境我建议再加两个逻辑第一FileOutputStream写入前先判断文件是否已存在如果需要断点续传用RandomAccessFile或者FileChannel从指定 offset 写第二下载超时时间一定要根据文件大小调整。我遇到过 5GB 文件默认 read timeout 30 秒下载到一半直接超时崩溃。设置成 120 秒甚至更长是合理的。4.3 文件夹列表与创建文件夹上传目标文件夹不一定都是根目录所以我们需要能创建文件夹和列出文件夹内容。列出文件夹0下面的所有条目GET https://api.box.com/2.0/folders/0/items Authorization: Bearer token返回的结构里有一个entries数组每一项包含typefile 或 folder、id、name。这个接口还支持limit和offset参数做分页。实际项目中如果文件夹下条目非常多务必做分页处理不然拿不全。创建文件夹POST https://api.box.com/2.0/folders Authorization: Bearer token Content-Type: application/json { name: 项目资料, parent: {id: 0} }如果目标文件夹已经存在Box 会返回 HTTP 409提示冲突。这个行为看着像错误其实可以用来自动判断文件夹是否存在。我在做“确保目录存在”的工具方法时是先尝试创建捕获 409 并从响应 body 里解析出已有文件夹的 ID如果返回 201就直接用新创建的 ID。private String ensureFolder(String folderName, String parentId, String token) throws IOException { // POST 创建 // 若 201解析 id // 若 409解析 body 中 conflicts 里的 id }这个思路比先 list 再逐个比对名字要快得多请求次数也少推荐直接用。5. 常见问题与避坑指南5.1 Token 过期竞态与重试时机我实际跑服务的时候第一个遇到的高频问题就是 Token 过期。如果你没有做统一的 Token 管理文件上传过程中极容易在某一步报 401。因为上传耗时很长可能你用同一个 Token 连续调用了十几分钟而 Box 的 Token 有效期早就过了。解决方案有两个层面。第一每次发起请求前检查本地记录过期时间如果快过期就主动刷新不要等请求返回 401 才处理。第二在 API 客户端里做“自动重试一次”如果响应码是 401刷新 Token然后重新执行原请求。第二个方案更稳因为即使你检查了时间也存在网络延迟导致后端已经判定过期的极端情况。需要注意不要对所有 401 都无脑重试。如果刷新 Token 之后还是 401多半不是过期问题而是 client_secret 配置错了或者用户权限被撤了这时再重试只会徒增请求。5.2 分片大小与 SHA-1 Digest 报错分片上传最常见的错误有两个。一个是Digest格式不对报错信息类似Invalid digest。我一开始以为是 SHA-1 算法问题后来发现是漏了sha前缀或者把整个文件的摘要写在了分片请求里。记住规则上传分片时Digest是这个分片的 SHA-1提交会话时Digest是整个文件的 SHA-1。另一个是分片大小不匹配。Box 会在创建 upload session 时返回part_size比如 33554432 字节。你上传的每个分片除了最后一片大小必须严格等于part_size。如果你把文件平均分成任意大小上传比如每片 16MBBox 会返回 400错误信息里通常会带part_size提示。在生成分片时我建议用一个循环每次读取固定大小的字节数组。最后一次读取到的字节数可能小于part_size这是允许的。但如果最后一次刚好等于part_size那你需要小心提交的parts数组里每个分片的size值要以实际字节数为准不要想当然地填part_size。5.3 错误状态码速查表我整理了在实际对接中遇到最多的几个 HTTP 状态码做成表格方便排查状态码含义处理建议400请求参数错误检查 JSON 字段名和格式尤其Content-Range、Digest401Token 无效或过期刷新 Token 后重试一次403权限不足确认应用权限范围和文件访问权限404文件或文件夹不存在确认 ID 是否正确409资源冲突上传同名文件、创建已有文件夹时出现按业务逻辑处理429请求过于频繁等待Retry-After响应头指定时间后重试5xx服务端错误一般可以指数退避重试我在处理 429 时没有简单 sleep 固定时间而是读取响应头里的Retry-After。这个值有时候是秒数有时候是 date 字符串。如果 Box 没返回这个头我就默认等 30 秒再重试。这样既不会把请求打太狠也不会盲目等待。5.4 落地到项目的几个建议Box 上传下载做到能跑通不算难但做到能稳定跑上生产有几个细节值得注意。第一所有 API 调用统一走封装好的客户端不要在业务代码里到处拼 URL。哪怕你现在只负责上传下载后面肯定要加删除、移动、搜索统一入口会省掉很多麻烦。第二上传和下载都要考虑磁盘空间。下载大文件时不要先全部读进内存再写盘要用流式写入。上传大文件时也不要一次性把整个文件读入内存后再发请求直接用文件流作为请求体。OkHttp 的RequestBody.create(File, MediaType)支持流式读取但你在做分片时最好每片单独开一个ByteArrayInputStream避免一个超大byte[]把堆内存打爆。第三日志里绝不能打印 Access Token、Refresh Token 这类敏感信息。我们写代码时很容易在异常 catch 里顺手打印请求体一旦请求体里有 Bearer Token日志系统就会把它记录到明文文件里。真出事的时候这个 Token 可能就是别人进入账号的钥匙。第四生产环境建议为 Box API 配置独立的连接池和线程池。上传下载是 IO 密集型任务不要和业务线程混在一起否则一旦文件传输卡住整个应用线程会被拖死。我自己习惯用固定线程数的ExecutorService来控制并发分片上传数量一般 3 到 5 个并发通道就够用了太多反而不稳。这套东西跑下来我最深的体会是Box 的 API 设计得挺规整但文件传输本质上是工程问题不是算法问题。老老实实做好 Token 管理、分片重试、错误识别比研究什么高深技术都实际。你如果也是刚开始接 Box不用着急把文档啃完先把一条链路跑通再回头补充细节效率会高得多。最后分享一个小技巧本地环境联调时可以给自己的测试账号建一个专用文件夹把根目录的读写权限锁死这样就算代码里有循环创建文件夹的 bug也不会把根目录搞得一团糟。 
长河君 · 2026/10/17 23:49:57 · 阅读 1.2k Java对接Box云存储：OAuth认证与分片上传下载实战指南
说来也挺巧最近手上的一个小项目需要把本地文件往 Box 云存储上搬还要能从 Box 拉回来。用 Java 捣鼓了几天从 OAuth 授权到上传下载全流程都跑通了。Box 这类服务本身 API 做得很完整但对第一次接触的人来说坑其实不少认证方式绕、大文件容易超时、分片边界踩错就报错。这篇东西把思路和代码整理出来针对的是刚接触 Box、想用 Java 快速实现文件上传下载的同学也适合已经能上传但经常被各种异常搞懵的老哥参考。我尽量把每一步的“为什么这么做”也讲清楚不只是贴代码。因为 Box API 的坑往往不在语法而在你对它的设计逻辑不理解。搞懂了它的授权方式、上传会话机制、分片校验规则后面写代码就是水到渠成的事。1. Box 平台接入的整体思路1.1 Box API 能做什么Box 是一个面向企业和个人的云存储平台它的核心能力是让外部系统通过 REST API 操作远端文件。我们这次用到的功能其实只占很小一部分文件上传、文件下载、文件夹列表、创建文件夹、获取文件元数据。它的 API 版本目前常用的是 2.0所有接口都在/2.0路径下数据格式为 JSON。除了基本文件操作它还支持搜索、评论、协作、权限管理、Webhook 等。但对于“浅度接触”的项目来说先跑通上传下载比什么都重要。你不需要一次性吃透整个平台只要掌握一条完整链路认证 - 拿 Token - 上传 - 下载 - 处理错误就能应付大多数业务场景。我不太建议一上来就引入官方 SDK虽然那样省事但它会帮你隐藏很多细节。一旦遇到超时、分片、重试这类真实问题你如果不知道底层发生了什么排查起来会很痛苦。所以我下面所有的实现都用纯 HTTP 调用完成配合一个小型工具类反而更好控制和理解。1.2 技术上真正要解决的问题用 Java 对接 Box表面上只是发几个 HTTP 请求但实际落地有三个核心难点。第一个是认证。Box 使用的是 OAuth 2.0 授权模式用户或者应用必须先拿到访问令牌Access Token之后每一个 API 请求都要在请求头里带上Authorization: Bearer token。Token 有时效性过期后要刷新如果你的程序是多线程并发访问还要避免刷新令牌时大家互相踩踏。第二个是传输方式。小文件可以直接用multipart/form-data上传但大文件不行必须走分片上传Upload Session。分片上传不是简单把文件拆开几个部分传上去就完了它要求你先创建一个上传会话告诉 Box 文件大小、文件名、目标文件夹然后按它给你分配的分片大小逐个上传。每个分片还得附带 SHA-1 摘要提交阶段更麻烦需要整个文件的摘要。第三个是异常处理。网络超时、服务端限流、Token 失效、同名文件冲突、文件被锁等这些在真实运行环境里都会出现。良好的异常处理机制不是捕获后打印日志而是要能识别错误码、判断是否需要重试、是否要刷新 Token、是否要提示用户调整参数。1.3 技术组件选型这次我用的技术栈很轻JDK 11、OkHttp、Jackson、SLF4J。没引入 Spring也没上全家桶目的是让代码逻辑更直观。你自己项目里有 Spring Boot 也完全没问题核心代码是可以平迁的。选 OkHttp 而不是 JDK 自带的HttpClient主要是因为它对连接超时、读取超时、重定向、连接池的控制更细而且MultipartBody对上传表单的支持比原生 API 方便很多。Jackson 就是做 JSON 序列化和反序列化Box 返回的 JSON 字段多且风格统一用 Jackson 解析省事。另外强烈建议在项目里统一封装一个BoxApiClient类把 Token 管理、HTTP 调用、错误处理都收敛在里面。你如果把这些逻辑散落在业务代码里后面每加一个接口就要复制粘贴一轮迟早会出事。2. 准备工作与授权流程详解2.1 开发者应用配置在正式调用 API 之前需要先有一个 Box 开发者账号并在开发者后台创建一个自定义应用。这个过程不同后台版本界面不一样但核心要素是一样的。应用创建完之后你必须要拿到两样东西client_id和client_secret。这就是你应用的身份标识。同时你还要配置重定向 URIRedirect URI也就是授权成功之后 Box 把用户或者临时授权码带回的那个地址。本机调试的时候可以直接填一个http://localhost:8080/callback之类的地址但要注意Box 只接受你在后台白名单里配置过的 URI你随便写一个都会报redirect_uri不匹配。在应用类型选择上如果你的业务是“用户上传自己的文件”建议用标准 OAuth 2.0 授权码模式如果是后台服务、没有用户交互界面可以考虑 JWT 服务账号模式。但 JWT 的密钥管理、断言生成会复杂不少所以“浅度接触”阶段我推荐先走授权码模式把链路跑通再说。2.2 OAuth 2.0 授权码流程授权码模式的流程可以用一句话概括先让用户去 Box 授权页面点一下Box 回调你的地址并带上一个临时code然后你用这个code去换取access_token和refresh_token。第一步是拼接授权地址让用户跳转https://account.box.com/api/oauth2/authorize?client_idYOUR_CLIENT_IDresponse_typecoderedirect_urihttp://localhost:8080/callback用户同意后Box 会重定向到你的回调地址并在 URL 上带一个?codexxx参数。拿到这个 code 之后你的后端再发起 Token 请求POST https://api.box.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_typeauthorization_code codexxx client_idYOUR_CLIENT_ID client_secretYOUR_CLIENT_SECRET redirect_urihttp://localhost:8080/callback用 Java 实现时我为了方便直接发了一个表单请求没有额外引 OAuth SDKprivate String exchangeCodeForToken(String code) throws IOException { OkHttpClient client new OkHttpClient(); FormBody body new FormBody.Builder() .add(grant_type, authorization_code) .add(code, code) .add(client_id, CLIENT_ID) .add(client_secret, CLIENT_SECRET) .add(redirect_uri, REDIRECT_URI) .build(); Request request new Request.Builder() .url(https://api.box.com/oauth2/token) .post(body) .build(); try (Response response client.newCall(request).execute()) { if (!response.isSuccessful()) { throw new IOException(Token request failed: response.code()); } String responseBody response.body().string(); // 解析 JSON取出 access_token、refresh_token、expires_in JsonNode node new ObjectMapper().readTree(responseBody); return node.get(access_token).asText(); } }需要注意redirect_uri必须和授权时传的完全一致不能多一个斜杠也不能漏掉端口。我踩过的坑就是授权时写http://localhost:8080/callback换取 Token 时写成了http://localhost:8080/callback/结果 Box 直接返回 400。2.3 Token 刷新与并发保护access_token不是永久的Box 默认过期时间通常是一个小时左右。如果令牌过期你调用文件接口会得到 HTTP 401。解决办法是用refresh_token再换一个新的POST https://api.box.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_typerefresh_token refresh_tokenREFRESH_TOKEN client_idYOUR_CLIENT_ID client_secretYOUR_CLIENT_SECRET代码逻辑很简单但多线程环境下要注意一个问题多个线程同时发现 Token 过期然后同时去刷新结果只有一个刷新请求成功其他线程拿到的还是旧 Token或者因为旧 Token 被刷新而失效。我的处理方案是给 Token 刷新加锁并且刷新成功之后立即更新内存里的 Token 引用private volatile String accessToken; private final ReentrantLock tokenLock new ReentrantLock(); public String getValidToken() throws IOException { if (accessToken ! null expiresAt System.currentTimeMillis() 30_000) { return accessToken; } tokenLock.lock(); try { if (accessToken ! null expiresAt System.currentTimeMillis() 30_000) { return accessToken; } refreshAccessToken(); return accessToken; } finally { tokenLock.unlock(); } }这种双重检查写法既避免了重复刷新也不至于每个请求都等锁。另外建议在本地保存refresh_token否则进程重启之后还得让用户重新授权。3. 文件上传的实现细节3.1 小文件直接上传文件上传是 Box API 里最常用的接口。小文件比如几十 MB 以下直接发一个multipart/form-data请求就行接口是POST https://api.box.com/2.0/files/content请求体里有两个字段一个是attributes是个 JSON 字符串必须包含文件名和目标文件夹 ID另一个是file就是文件二进制内容。我用 OkHttp 实现时代码是这样的private String uploadSimpleFile(Path file, String folderId, String token) throws IOException { OkHttpClient client new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(60, TimeUnit.SECONDS) .build(); long fileSize Files.size(file); String attributes String.format({\name\:\%s\,\parent\:{\id\:\%s\}}, file.getFileName(), folderId); RequestBody fileBody RequestBody.create(file.toFile(), MediaType.parse(application/octet-stream)); RequestBody multipart new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart(attributes, attributes) .addFormDataPart(file, file.getFileName().toString(), fileBody) .build(); Request request new Request.Builder() .url(https://api.box.com/2.0/files/content) .header(Authorization, Bearer token) .post(multipart) .build(); try (Response response client.newCall(request).execute()) { String body response.body().string(); if (!response.isSuccessful()) { throw new IOException(Upload failed, code response.code() , body body); } JsonNode fileNode new ObjectMapper().readTree(body).path(entries).get(0); return fileNode.get(id).asText(); } }这里有几个细节attributes里的文件名不能包含路径分隔符必须只是文件名parent的id如果是根目录就传0。另外application/octet-stream是通用二进制类型如果不知道文件 MIME 类型用它最保险。你如果传的是图片、PDF也可以用对应的 MIME但 Box 不会因为 MIME 不同而区别处理。3.2 大文件分片上传从建会话到提交超过一定大小或者你不确定网络稳定性的文件建议使用分片上传。这个机制很有意思它不是一个纯粹的“把文件分片传上去”的过程而是先让 Box 告诉你“你该怎么分片”。第一步创建上传会话POST https://api.box.com/2.0/files/upload_sessions Authorization: Bearer token Content-Type: application/json { folder_id: 0, file_size: 5368709120, file_name: big-file.iso }Box 返回的 JSON 里会包含一个id、一个part_size还有total_parts。part_size是服务端根据你的文件大小自动算出来的它通常稳定在一个固定值附近比如 32MB、64MB 或者 128MB具体取决于文件总量。你不需要自己去硬编码分片大小而是应该以后端返回的part_size为准。接着你需要把文件按part_size切分每个分片用独立请求上传。分片上传的地址是PUT https://api.box.com/2.0/files/upload_sessions/{SESSION_ID} Authorization: Bearer token Content-Type: application/octet-stream Content-Range: bytes 0-33554431/5368709120 Digest: shabase64字符串Content-Range的格式是bytes 起始位置-结束位置/总大小总大小是完整文件的字节数不是分片字节数。Digest是当前分片的 SHA-1 哈希但是要用 Base64 编码并且拼上sha前缀。Java 计算分片摘要的代码大致是这样private static String sha1DigestBase64(byte[] data) throws Exception { MessageDigest md MessageDigest.getInstance(SHA-1); byte[] digest md.digest(data); return sha Base64.getEncoder().encodeToString(digest); }最麻烦的是提交阶段。所有分片传完之后你要发送一个提交请求这个请求的Digest必须是整个文件的 SHA-1不是某个分片的POST https://api.box.com/2.0/files/upload_sessions/{SESSION_ID}/commit Authorization: Bearer token Content-Type: application/json Digest: sha整个文件SHA1 { parts: [ {part_id: 返回的分片ID, offset: 0, size: 33554432, sha1: 分片SHA1}, ... ] }parts数组里的信息是上传每个分片时 Box 响应里返回的。你必须把那些part_id、offset、size、sha1原样保存下来提交时原样传回去。我之前图省事想着重新算一下分片 SHA1 提交就行结果 Box 返回 400提示 part 信息不匹配。老老实实把上传响应保存成 JSON最稳。3.3 上传进度与重试策略分片上传天然适合做进度显示因为你每传完一片就能知道已经传了多少。如果只是简单上传整个文件进度条想做得平滑就得靠读文件时手动统计字节数麻烦不说还容易打扰主流程。我在做进度统计时用了一个简单的包装类记录uploadedBytes和totalBytes。每传完一个分片就累加分片大小然后把当前百分比打出来。真实项目里可以把这些值推给前端轮询接口。重试策略上我的建议是分片请求失败后不要从第一片重启要记录已上传完成的分片 ID从失败的那个分片开始重传。Box 的 upload session 在没有 commit 之前是允许重复上传某个分片的你只需要保证最终所有分片都成功即可。一个小技巧是每个分片上传前先判断该分片之前是否已经成功上传。你可以把已成功上传的part_id存在本地一个列表里重试时跳过。这样即使网络抖动很严重任务也能慢慢推进而不是反复推倒重来。4. 文件下载与目录操作4.1 获取文件信息在下载文件之前通常先要确认文件是否存在、有多大、是什么类型。Box 的元数据接口很直接GET https://api.box.com/2.0/files/{file_id} Authorization: Bearer token返回的 JSON 里有name、size、created_at、modified_at、etag等字段。其中etag是个好东西如果你做增量同步可以把本地缓存的 etag 和服务端的做对比如果一致就跳过下载减少不必要的流量。拿到size之后也可以预判下载时长。如果文件特别大建议别一把梭直接下到内存而是用流式写入加断点续传。不过 Box 的下载接口本身支持 HTTP Range也就是你可以用Range: bytesxxx-xxx请求文件的部分内容。这为断点续传提供了很大方便。4.2 下载文件内容Box 下载文件的 URL 是GET https://api.box.com/2.0/files/{file_id}/content正常情况下Box 会返回 HTTP 302把请求重定向到一个临时的下载地址。你不需要手动处理这个重定向OkHttp 默认会跟随重定向直接拿到最终文件内容。但我需要提醒一点重定向后的地址是有时效性的通常是几分钟所以你不要把它存下来以后重用每次下载都应该重新走一遍。基础下载实现private void downloadFile(String fileId, Path targetPath, String token) throws IOException { OkHttpClient client new OkHttpClient.Builder() .followRedirects(true) .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(120, TimeUnit.SECONDS) .build(); Request request new Request.Builder() .url(https://api.box.com/2.0/files/ fileId /content) .header(Authorization, Bearer token) .build(); try (Response response client.newCall(request).execute()) { if (!response.isSuccessful()) { throw new IOException(Download failed, code response.code()); } try (InputStream inputStream response.body().byteStream(); OutputStream outputStream new FileOutputStream(targetPath.toFile())) { inputStream.transferTo(outputStream); } } }这段代码看着简单但实际生产环境我建议再加两个逻辑第一FileOutputStream写入前先判断文件是否已存在如果需要断点续传用RandomAccessFile或者FileChannel从指定 offset 写第二下载超时时间一定要根据文件大小调整。我遇到过 5GB 文件默认 read timeout 30 秒下载到一半直接超时崩溃。设置成 120 秒甚至更长是合理的。4.3 文件夹列表与创建文件夹上传目标文件夹不一定都是根目录所以我们需要能创建文件夹和列出文件夹内容。列出文件夹0下面的所有条目GET https://api.box.com/2.0/folders/0/items Authorization: Bearer token返回的结构里有一个entries数组每一项包含typefile 或 folder、id、name。这个接口还支持limit和offset参数做分页。实际项目中如果文件夹下条目非常多务必做分页处理不然拿不全。创建文件夹POST https://api.box.com/2.0/folders Authorization: Bearer token Content-Type: application/json { name: 项目资料, parent: {id: 0} }如果目标文件夹已经存在Box 会返回 HTTP 409提示冲突。这个行为看着像错误其实可以用来自动判断文件夹是否存在。我在做“确保目录存在”的工具方法时是先尝试创建捕获 409 并从响应 body 里解析出已有文件夹的 ID如果返回 201就直接用新创建的 ID。private String ensureFolder(String folderName, String parentId, String token) throws IOException { // POST 创建 // 若 201解析 id // 若 409解析 body 中 conflicts 里的 id }这个思路比先 list 再逐个比对名字要快得多请求次数也少推荐直接用。5. 常见问题与避坑指南5.1 Token 过期竞态与重试时机我实际跑服务的时候第一个遇到的高频问题就是 Token 过期。如果你没有做统一的 Token 管理文件上传过程中极容易在某一步报 401。因为上传耗时很长可能你用同一个 Token 连续调用了十几分钟而 Box 的 Token 有效期早就过了。解决方案有两个层面。第一每次发起请求前检查本地记录过期时间如果快过期就主动刷新不要等请求返回 401 才处理。第二在 API 客户端里做“自动重试一次”如果响应码是 401刷新 Token然后重新执行原请求。第二个方案更稳因为即使你检查了时间也存在网络延迟导致后端已经判定过期的极端情况。需要注意不要对所有 401 都无脑重试。如果刷新 Token 之后还是 401多半不是过期问题而是 client_secret 配置错了或者用户权限被撤了这时再重试只会徒增请求。5.2 分片大小与 SHA-1 Digest 报错分片上传最常见的错误有两个。一个是Digest格式不对报错信息类似Invalid digest。我一开始以为是 SHA-1 算法问题后来发现是漏了sha前缀或者把整个文件的摘要写在了分片请求里。记住规则上传分片时Digest是这个分片的 SHA-1提交会话时Digest是整个文件的 SHA-1。另一个是分片大小不匹配。Box 会在创建 upload session 时返回part_size比如 33554432 字节。你上传的每个分片除了最后一片大小必须严格等于part_size。如果你把文件平均分成任意大小上传比如每片 16MBBox 会返回 400错误信息里通常会带part_size提示。在生成分片时我建议用一个循环每次读取固定大小的字节数组。最后一次读取到的字节数可能小于part_size这是允许的。但如果最后一次刚好等于part_size那你需要小心提交的parts数组里每个分片的size值要以实际字节数为准不要想当然地填part_size。5.3 错误状态码速查表我整理了在实际对接中遇到最多的几个 HTTP 状态码做成表格方便排查状态码含义处理建议400请求参数错误检查 JSON 字段名和格式尤其Content-Range、Digest401Token 无效或过期刷新 Token 后重试一次403权限不足确认应用权限范围和文件访问权限404文件或文件夹不存在确认 ID 是否正确409资源冲突上传同名文件、创建已有文件夹时出现按业务逻辑处理429请求过于频繁等待Retry-After响应头指定时间后重试5xx服务端错误一般可以指数退避重试我在处理 429 时没有简单 sleep 固定时间而是读取响应头里的Retry-After。这个值有时候是秒数有时候是 date 字符串。如果 Box 没返回这个头我就默认等 30 秒再重试。这样既不会把请求打太狠也不会盲目等待。5.4 落地到项目的几个建议Box 上传下载做到能跑通不算难但做到能稳定跑上生产有几个细节值得注意。第一所有 API 调用统一走封装好的客户端不要在业务代码里到处拼 URL。哪怕你现在只负责上传下载后面肯定要加删除、移动、搜索统一入口会省掉很多麻烦。第二上传和下载都要考虑磁盘空间。下载大文件时不要先全部读进内存再写盘要用流式写入。上传大文件时也不要一次性把整个文件读入内存后再发请求直接用文件流作为请求体。OkHttp 的RequestBody.create(File, MediaType)支持流式读取但你在做分片时最好每片单独开一个ByteArrayInputStream避免一个超大byte[]把堆内存打爆。第三日志里绝不能打印 Access Token、Refresh Token 这类敏感信息。我们写代码时很容易在异常 catch 里顺手打印请求体一旦请求体里有 Bearer Token日志系统就会把它记录到明文文件里。真出事的时候这个 Token 可能就是别人进入账号的钥匙。第四生产环境建议为 Box API 配置独立的连接池和线程池。上传下载是 IO 密集型任务不要和业务线程混在一起否则一旦文件传输卡住整个应用线程会被拖死。我自己习惯用固定线程数的ExecutorService来控制并发分片上传数量一般 3 到 5 个并发通道就够用了太多反而不稳。这套东西跑下来我最深的体会是Box 的 API 设计得挺规整但文件传输本质上是工程问题不是算法问题。老老实实做好 Token 管理、分片重试、错误识别比研究什么高深技术都实际。你如果也是刚开始接 Box不用着急把文档啃完先把一条链路跑通再回头补充细节效率会高得多。最后分享一个小技巧本地环境联调时可以给自己的测试账号建一个专用文件夹把根目录的读写权限锁死这样就算代码里有循环创建文件夹的 bug也不会把根目录搞得一团糟。