如何支持文件上传

使用当前 ApiHug protobuf 与 swagger 语法定义 multipart 上传接口。

当接口需要同时接收文件和普通字段时，使用这一模式。

适用场景

适用于上传图片、附件、导入文件等需要 multipart/form-data 的 API。

操作步骤

在请求消息里把上传字段定义为 bytes。

Protobuf

message UploadBookCoverToLocalRequest {
  option (hope.swagger.schema) = {
    json_schema: {
      description: "Upload a book cover to the local file system";
    };
  };

  int64 id = 1 [(hope.swagger.field) = {
    description: "Book id";
    empty: false;
  }];

  bytes file = 2 [(hope.swagger.field) = {
    description: "Book cover file";
    empty: false;
  }];
}

在 RPC 上声明 multipart 上传。

Protobuf

rpc UploadBookCoverToLocal (UploadBookCoverToLocalRequest) returns (google.protobuf.Empty) {
  option (hope.swagger.operation) = {
    post: "/upload-book-cover";
    description: "Upload a book cover to the local file system";
    priority: LOW;
    consumes: "multipart/form-data";
    multipart: true;
    authorization: {
      rbac: {
        predefined_role_checker: PLATFORM;
      }
    };
  };
}

重新生成 wire 与 stub。
在应用层实现实际的文件保存逻辑。

你会看到什么

生成后的 OpenAPI 文档会把请求体声明为 multipart/form-data，而不是普通 JSON 请求体。

JSON

"/admin/book/upload-book-cover": {
  "post": {
    "description": "Upload a book cover to the local file system",
    "requestBody": {
      "content": {
        "multipart/form-data": {
          "schema": {
            "$ref": "#/components/schemas/UploadBookCoverToLocalRequest"
          }
        }
      }
    }
  }
}

应用侧会得到一个可用于 multipart 处理的生成请求类型，通常底层会映射到 org.springframework.web.multipart.MultipartFile。

结果

你会得到一个从 proto 契约、OpenAPI 文档、生成 stub 到运行时实现都一致的文件上传接口。

如何支持文件上传

适用场景

操作步骤

你会看到什么

结果

On this page