CSB 按照 HTTP 协议的规范实现了 HTTP2HTTP 的附件传输功能。在您将后端 HTTP 服务通过 CSB 对外开放为 HTTP 服务后,可以上传或下载附件。

前提条件

使用约束

  • 仅适用于 HTTP2HTTP 场景。对于 HTTP2HSF、HTTP2Dubbo、HTTP2WS 场景,CSB Broker 只能获取附件,不支持转发给后端的 HSF/Dubbo/WS 服务。
  • 目前仅实现部分 HTTP 附件交互场景。支持场景如下:
    • 上传附件:
      • HTTP Body 二进制流:使用 POST,设置 Content-Type: application/octet-stream ,适合于仅上传单个二进制流。
      • 多附件二进制流:使用 POST,设置 Content-Type: multipart/form-data ,适合于有普通 form 的业务数据,同时还有多个附件上传场景。
    • 下载附件:HTTP Body 返回二进制流,设置 Content-Type: application/octet-stream
  • 仅支持新版本服务:即在发布设置页面选择新版。如果您未进行发布设置,则在发布服务时选择新版发布示例详情-发布者-发布设置
  • 单个文件最大 15 M,可以通过 jvm -Dcsb_httpAttachmentTotalMBSize=M字节数来修改,Broker 端通过 csb_httpAttachmentTotalMBSize 配置。
  • 最多同时发送 5 个附件,可以通过 jvm -Dcsb_httpAttachmentMaxAmount=文件数来修改。Broker 端通过 csb_httpAttachmentMaxAmount 配置。
  • Broker 向后端业务服务发送多附件请求的响应超时时间为 120 秒(csb_httpAttachmentClientTimeoutSeconds)。
  • 不支持自定义消息转换的响应逻辑。
  • 每 Broker 建立最多 60 个多附件传输的 HTTP 连接(csb_httpAttachmentClientMaxConn)。

上传附件

  • HTTP Body 二进制流
    • 修改 CSB 客户端代码

      CSB 客户端示例代码:

      HttpParameters.Builder builder = new HttpParameters.Builder();
      builder.requestURL("http://localhost:8086/CSB") // 设置CSB服务地址
        .api("http2http1") // 设置服务名
        .version("1.0.0") // 设置版本号
        .method("post") // 设置调用方式, get/post
        .accessKey("ak").secretKey("sk"); // 设置accessKey和secretKey
      
      try {
        // 设置请求参数
        builder.putParamsMap("name", "name中文1").putParamsMap("times", "3");
        builder.contentBody(new ContentBody(new File("文件名.xxx")));
        HttpReturn ret = HttpCaller.invokeReturn(builder.build());
      } catch (HttpCallerException e) {
        // error process
      }

      HTTP 请求示例如下(上传 xml 文本文件):

      客户端示例代码-HTTP
    • 业务服务端处理方式

      根据 Content-Type: application/octet-stream 判断请求消息内容格式,并正确处理。

  • 多附件二进制流
    • 修改 CSB 客户端代码

      CSB 客户端示例代码:

      HttpParameters.Builder builder = new HttpParameters.Builder();
      builder.requestURL("http://localhost:8086/CSB") // 设置请求的URL
        .api("http2http1") // 设置服务名
        .version("1.0.0") // 设置版本号
        .method("post") // 设置调用方式, get/post
        .accessKey("ak").secretKey("sk"); // 设置accessKey和secretKey
      
      try {
        // 设置form请求参数
        builder.putParamsMap("times", "2").putParamsMap("name", "we中文wesdsfsfdsasdefds");
      
        //设置上传附件
        builder.addAttachFile("file1", new File("文件名1.xxx"));
        builder.addAttachFile("file2", "fileName2", new FileInputStream(new File("文件名2.yyy")), true); //对文件进行压缩传输
      
        HttpReturn ret = HttpCaller.invokeReturn(builder.build());
      } catch (Exception e) {
        // error process
      }

      HTTP 请求示例如下(上传 xml 文本文件):

      多附件二进制流-CSB 客户端代码-HTTP
      说明
      • 通过 builder.putParamsMap() 方式设置的参数都是以 application/x-www-form-urlencoded; charset=UTF-8 方式提交请求。服务端需正确解码,以便得到正确的参数值。
      • 所有附件均以 Content-Type: application/octet-stream 上传。
    • 业务服务端处理方式
      • 根据 Content-Type: multipart/form-data 判断是否是多附件上传请求,并正确解析请求内容。
      • 根据每个 form 表单的 Content-Type: application/x-www-form-urlencodedContent-Type: application/octet-stream 正确解析对应 form 数据。

下载附件

CSB HTTP SDK 会自动解析 HTTP 响应,并根据 HTTP Header 的 Content-Type: application/octet-stream 设置 HttpReturn 对象的 responseresponseBytes

示例代码如下:

HttpReturn ret = HttpCaller.invokeReturn(builder.build());
ret.responseBytes; //响应结果的二进制数据
ret.response; //响应结果的字符串数据

FAQ

  1. 什么场景使用“Body 二进制流”,什么场景使用“多附件二进制流”?
    上传方式 HTTP Query 参数 HTTP Form 参数 上传附件数量
    Body 二进制流 支持 不支持 1
    多附件二进制流 支持 支持 1 个或多个
  2. 最大支持附件大小是多少?

    Broker 目前最多支持 15 M 附件大小,不管几个附件,一次请求合计不能超过 15 M。