文件上传（multipart/form-data + RSA 签名）技术文档

场景概述

文件上传采用 multipart/form-data 格式，包含两部分：

  • meta：JSON 格式的元数据，包含文件名、SHA256 摘要、业务参数等
  • file：实际的文件二进制内容
项目 说明
请求路径 /api/v1/dispatch/http/file/upload
签名算法 SHA256withRSA
关键特点 签名串中的 body 使用 meta JSON，文件完整性通过 SHA256 校验

第 1 步：准备文件和计算 SHA256

客户端准备上传文件，并计算文件的 SHA256 摘要：

// 计算文件 SHA256
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(fileBytes);
String sha256 = Hex.bytesToHex(hash);
// 示例结果: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

第 2 步：构造 meta JSON

meta JSON 包含文件元数据和业务参数：

{
  "filename": "test_upload.txt",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "metadata": {
    "bizType": "test",
    "orderId": "ORDER1736756000123"
  }
}

重要说明：签名串中的请求报文主体使用 meta JSON（非文件内容），这确保签名验证时不需要重复传输大文件。

第 3 步：构造签名串并签名

签名串格式（body 为 meta JSON）：

POST
/api/v1/dispatch/http/file/upload
1736756100
A1B2C3D4E5F6G7H8

{"filename":"test_upload.txt","sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","metadata":{"bizType":"test","orderId":"ORDER1736756000123"}}

注意：文件上传通常不使用数字信封加密，所以数字信封行为空（但仍需 \n）。

第 4 步：发送 multipart/form-data 请求

POST /api/v1/dispatch/http/file/upload HTTP/1.1
Host: gateway.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary1736756100000
Authorization: RSA mch_id="13030918",nonce_str="A1B2C3D4E5F6G7H8",signature="5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c...",timestamp="1736756100",serial_no="1139986924",baofu_serial_no="1139986924"

------WebKitFormBoundary1736756100000
Content-Disposition: form-data; name="meta"
Content-Type: application/json

{"filename":"test_upload.txt","sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","metadata":{"bizType":"test","orderId":"ORDER1736756000123"}}
------WebKitFormBoundary1736756100000
Content-Disposition: form-data; name="file"; filename="test_upload.txt"
Content-Type: application/octet-stream

[文件二进制内容]
------WebKitFormBoundary1736756100000--

第 5 步：网关处理流程

网关接收到文件上传请求后，执行以下验证：

  1. 解析 Authorization 头并验证签名（签名串使用 meta JSON 作为 body）
  2. 解析 multipart 请求，提取 meta JSON 和文件内容
  3. 计算上传文件的 SHA256，与 meta 中的 sha256 比对，确保文件完整性
  4. 验证通过后，将文件转发到后端服务

第 6 步：响应处理

文件上传成功后的响应示例：

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Request-ID: req-20260112-file1234
Baofu-Timestamp: 1736756200
Baofu-Nonce: X9Y8Z7W6V5U4T3S2
Baofu-Signature: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d...
Baofu-Serial: 1139986924
Baofu-Signature-Type: RSA

{
  "data": {
    "fileId": "FILE20260112001",
    "filename": "test_upload.txt",
    "size": 52,
    "uploadTime": "2026-01-12 10:35:00"
  }
}