Spring Boot/Java读取URL PDF返回空白附件页问题求助

问题原因 #

• 二进制文件错误使用字符流处理：PDF是二进制格式文件，必须以字节流方式读取和传输。如果将输入流转为字符（比如通过Reader、String做中间转换），字符编码会对二进制数据进行不可逆的编码/解码操作，直接破坏PDF的文件结构，导致生成的文件损坏，打开后显示空白页。
• 辅助诱因（非核心）：若响应头设置不完整（比如未指定Content-Type为application/pdf，或未设置Content-Disposition为附件形式），也可能导致客户端无法正确解析文件，但核心问题还是字符与字节的错误转换。

解决方法 #

1. 直接处理二进制流，禁用字符转换 #

跳过所有字符转换步骤，直接读取远程接口返回的字节流为字节数组，或直接流式传输到响应输出流，确保二进制数据不被篡改。

2. 正确配置Basic认证 #

调用带Basic认证的PDF接口时，需在请求头中正确添加认证信息，确保能获取到完整的PDF二进制数据。

3. 设置正确的响应头 #

返回ResponseEntity时，必须指定以下关键响应头：

• Content-Type: application/pdf，告知客户端返回内容为PDF格式
• Content-Disposition: attachment; filename="文件名.pdf"，指定以附件形式下载
• Content-Length（可选）：设置为字节数组的长度，帮助客户端准确识别文件大小

示例代码（Spring Boot） #

方式1：使用RestTemplate快速实现

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import java.util.Base64;

@Service
public class PdfDownloadService {
    public ResponseEntity<byte[]> downloadPdf(String pdfUrl, String username, String password) {
        // 构建Basic认证头
        String authCredentials = username + ":" + password;
        String encodedAuth = Base64.getEncoder().encodeToString(authCredentials.getBytes());
        String authHeader = "Basic " + encodedAuth;

        // 组装请求头
        HttpHeaders requestHeaders = new HttpHeaders();
        requestHeaders.set(HttpHeaders.AUTHORIZATION, authHeader);
        HttpEntity<Void> requestEntity = new HttpEntity<>(requestHeaders);

        // 调用远程接口，直接获取字节数组（无字符转换）
        RestTemplate restTemplate = new RestTemplate();
        ResponseEntity<byte[]> remoteResponse = restTemplate.exchange(
                pdfUrl,
                HttpMethod.GET,
                requestEntity,
                byte[].class
        );

        // 设置响应头，返回附件
        HttpHeaders responseHeaders = new HttpHeaders();
        responseHeaders.setContentType(MediaType.APPLICATION_PDF);
        responseHeaders.setContentDisposition(ContentDisposition.attachment()
                .filename("downloaded.pdf")
                .build());

        return new ResponseEntity<>(remoteResponse.getBody(), responseHeaders, HttpStatus.OK);
    }
}

方式2：使用HttpClient处理大文件（流式传输）

如果PDF文件体积较大，建议采用流式传输，避免将整个文件加载到内存导致溢出：

import org.apache.http.HttpEntity;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.util.StreamUtils;

import java.io.IOException;
import java.io.InputStream;

@Service
public class PdfStreamService {
    public ResponseEntity<byte[]> streamPdf(String pdfUrl, String username, String password) throws IOException {
        // 配置Basic认证
        CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials(username, password));

        try (CloseableHttpClient httpClient = HttpClients.custom()
                .setDefaultCredentialsProvider(credentialsProvider)
                .build()) {
            HttpGet httpGet = new HttpGet(pdfUrl);
            try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
                HttpEntity entity = response.getEntity();
                if (entity == null) {
                    return new ResponseEntity<>(HttpStatus.NOT_FOUND);
                }
                // 直接读取字节流，跳过字符转换
                try (InputStream inputStream = entity.getContent()) {
                    byte[] pdfBytes = StreamUtils.copyToByteArray(inputStream);

                    // 设置响应头
                    HttpHeaders headers = new HttpHeaders();
                    headers.setContentType(org.springframework.http.MediaType.APPLICATION_PDF);
                    headers.setContentDisposition(org.springframework.http.ContentDisposition.attachment()
                            .filename("streamed.pdf")
                            .build());

                    return new ResponseEntity<>(pdfBytes, headers, HttpStatus.OK);
                }
            }
        }
    }
}

关键注意事项 #

• 绝对禁止将二进制流转换为String或使用Reader类处理，必须始终用InputStream和字节数组操作。
• 可通过直接访问PDF URL（携带Basic认证信息）验证原文件是否能正常下载，排除远程接口本身的问题。
• 大文件场景下，优先使用流式传输（比如直接将输入流写入响应的OutputStream），进一步优化内存占用。

内容的提问来源于stack exchange，提问作者momoman