MultipartEntityBuilder詳解

一、MultipartEntityBuilder的概述

MultipartEntityBuilder是Apache HttpClient庫中的一個類，提供了便捷的構建multipart請求的能力。一般地，我們使用multipart請求是需要上傳文件或者提交多個參數。如果使用普通請求，一般是無法處理這些情況的。

相對於上一個版本的HttpMultipart，MultipartEntityBuilder改進了參數的添加方法，並提供了更加豐富的定製化能力。

二、MultipartEntityBuilder的使用

MultipartEntityBuilder提供了多種添加參數的方法，本節中我們將會一一闡述：

1.添加文本參數

    HttpPost httpPost = new HttpPost(url);
    MultipartEntityBuilder builder = MultipartEntityBuilder.create();

    builder.addTextBody("username", "admin");
    builder.addTextBody("password", "123456");

    httpPost.setEntity(builder.build());
    CloseableHttpResponse httpResponse = httpClient.execute(httpPost);

addTextBody()方法的前兩個參數分別為參數名和參數值。當然，也可以使用addParameter方法添加，效果是一樣的。

2.添加二進位文件

    HttpPost httpPost = new HttpPost(url);
    MultipartEntityBuilder builder = MultipartEntityBuilder.create();

    File file = new File("/path/to/file");
    builder.addBinaryBody("file", file, ContentType.MULTIPART_FORM_DATA, "filename");

    httpPost.setEntity(builder.build());
    CloseableHttpResponse httpResponse = httpClient.execute(httpPost);

addBinaryBody()方法的前三個參數分別為參數名、文件和Content-Type。

3.添加純文本文件

    HttpPost httpPost = new HttpPost(url);
    MultipartEntityBuilder builder = MultipartEntityBuilder.create();

    String text = "this is a plain text";
    builder.addTextBody("text", text, ContentType.DEFAULT_TEXT);

    httpPost.setEntity(builder.build());
    CloseableHttpResponse httpResponse = httpClient.execute(httpPost);

4.定製化MultipartEntity

    HttpPost httpPost = new HttpPost(url);
    MultipartEntityBuilder builder = MultipartEntityBuilder.create();

    builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE);
    builder.setCharset(StandardCharsets.UTF_8);
    builder.addPart("file", new ByteArrayBody(fileContent, "filename"));
    builder.addPart("text", new StringBody("this is a plain text", ContentType.DEFAULT_TEXT));
    builder.addPart("parameter", new StringBody("parameter-value", ContentType.DEFAULT_BINARY));

    HttpEntity entity = builder.build();
    httpPost.setEntity(entity);
    CloseableHttpResponse httpResponse = httpClient.execute(httpPost);

setMode方法設置Multipart模式，對應不同的RFC規範；setCharset方法設置編碼；addPart方法提供了更加靈活的添加參數方法。

三、MultipartEntityBuilder的附加功能

1.追加參數

在上一個例子中，如果你想要在上傳文件的同時上傳其他參數，可以使用addPart方法，但是如果你希望追加參數，可以使用addTextBody/addBinaryBody方法，如下：

    builder.addBinaryBody("file", file, ContentType.MULTIPART_FORM_DATA, "filename");
    builder.addTextBody("username", "admin");
    builder.addTextBody("password", "123456");

2.文件流轉換

在某些情況下，我們需要將文件轉換成其他格式，比如Base64。此時，MultipartEntityBuilder提供了stream方式的addBinaryBody方法，如下：

    builder.addBinaryBody("file", new ByteArrayInputStream(Base64.encode(fileContent.getBytes())), ContentType.DEFAULT_BINARY, "filename");

3.支持參數排序

在某些場景下，需要按照參數名稱做排序，MultipartEntityBuilder提供了Comparator介面，你可以自定義該介面來實現參數排序，如下：

    builder.setSortOrder(new Comparator() {
        @Override
        public int compare(String o1, String o2) {
            return o1.compareToIgnoreCase(o2);
        }
    });

四、總結

本文通過具體的例子介紹了MultipartEntityBuilder的使用，包括文本參數、二進位文件、純文本文件、定製化MultipartEntity、追加參數、文件流轉換以及參數排序等相關功能。這些都為我們優美地處理多樣化的請求提供了強有力的工具。