tamar-file-hub-client 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

file_hub_client/services/file/sync_blob_service.py

@@ -1,478 +1,554 @@
-"""
-同步二进制大对象服务
-"""
-from pathlib import Path
-from typing import Optional, Union, BinaryIO, Iterator
-
-from .base_file_service import BaseFileService
-from ...enums import UploadMode
-from ...errors import ValidationError
-from ...rpc import SyncGrpcClient
-from ...schemas import FileUploadResponse, UploadUrlResponse
-from ...utils import HttpUploader, HttpDownloader, retry_with_backoff, get_file_mime_type
-
-
-class SyncBlobService(BaseFileService):
-    """同步文件（二进制大对象）服务"""
-
-    def __init__(self, client: SyncGrpcClient):
-        """
-        初始化文件（二进制大对象）服务
-
-        Args:
-            client: 同步gRPC客户端
-        """
-        self.client = client
-        self.http_uploader = HttpUploader()
-        self.http_downloader = HttpDownloader()
-
-    def _generate_resumable_upload_url(
-            self,
-            file_name: str,
-            file_size: int,
-            folder_id: Optional[str] = None,
-            file_type: str = "file",
-            mime_type: str = None,
-            file_hash: str = None,
-            is_temporary: Optional[bool] = False,
-            expire_seconds: Optional[int] = None,
-            **metadata
-    ) -> UploadUrlResponse:
-        """
-        生成断点续传URL
-
-        Args:
-            file_name: 文件名
-            file_size: 文件大小
-            folder_id: 文件夹ID
-            file_type: 文件类型
-            mime_type: MIME类型
-            file_hash: 文件哈希
-            is_temporary: 是否为临时文件
-            expire_seconds: 过期秒数
-            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
-
-        Returns:
-            上传URL响应
-        """
-        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
-
-        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
-
-        request = file_service_pb2.UploadUrlRequest(
-            file_name=file_name,
-            file_size=file_size,
-            file_type=file_type,
-            mime_type=mime_type or "application/octet-stream",
-            file_hash=file_hash,
-            is_temporary=is_temporary,
-            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
-        )
-
-        if folder_id:
-            request.folder_id = folder_id
-
-        # 构建元数据
-        grpc_metadata = self.client.build_metadata(**metadata)
-
-        response = stub.GenerateResumableUploadUrl(request, metadata=grpc_metadata)
-
-        return UploadUrlResponse(
-            file=self._convert_file_info(response.file),
-            upload_file=self._convert_upload_file_info(response.upload_file),
-            upload_url=response.url
-        )
-
-    def _confirm_upload_completed(self, file_id: str, **metadata) -> None:
-        """
-        确认上传完成
-
-        Args:
-            file_id: 文件ID
-            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
-        """
-        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
-
-        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
-
-        request = file_service_pb2.UploadCompletedRequest(file_id=file_id)
-
-        # 构建元数据
-        grpc_metadata = self.client.build_metadata(**metadata)
-
-        stub.ConfirmUploadCompleted(request, metadata=grpc_metadata)
-
-    @retry_with_backoff(max_retries=3)
-    def _upload_file(
-            self,
-            file_name: str,
-            content: Union[bytes, BinaryIO, Path],
-            folder_id: Optional[str] = None,
-            file_type: str = "file",
-            mime_type: Optional[str] = None,
-            is_temporary: Optional[bool] = False,
-            expire_seconds: Optional[int] = None,
-            **metadata
-    ) -> FileUploadResponse:
-        """
-        直接上传文件
-
-        Args:
-            file_name: 文件名
-            content: 文件内容（字节、文件对象或路径）
-            folder_id: 文件夹ID
-            file_type: 文件类型
-            mime_type: MIME类型
-            is_temporary: 是否为临时文件
-            expire_seconds: 过期秒数
-            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
-
-        Returns:
-            文件信息
-        """
-        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
-
-        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
-
-        # 处理不同类型的内容
-        if isinstance(content, Path):
-            if not content.exists():
-                raise ValidationError(f"文件不存在: {content}")
-            with open(content, "rb") as f:
-                file_bytes = f.read()
-            if not mime_type:
-                mime_type = get_file_mime_type(content)
-        elif isinstance(content, bytes):
-            file_bytes = content
-        elif hasattr(content, 'read'):
-            file_bytes = content.read()
-        else:
-            raise ValidationError("不支持的内容类型")
-
-        # 构建请求
-        request = file_service_pb2.UploadFileRequest(
-            file_name=file_name,
-            content=file_bytes,
-            file_type=file_type,
-            mime_type=mime_type or "application/octet-stream",
-            is_temporary=is_temporary,
-            expire_seconds=expire_seconds,
-        )
-
-        if folder_id:
-            request.folder_id = folder_id
-
-        # 构建元数据
-        grpc_metadata = self.client.build_metadata(**metadata)
-
-        # 发送请求
-        response = stub.UploadFile(request, metadata=grpc_metadata)
-
-        # 转换响应
-        return FileUploadResponse(
-            file=self._convert_file_info(response.file),
-            upload_file=self._convert_upload_file_info(response.upload_file),
-        )
-
-    def _upload_stream(
-            self,
-            file_name: str,
-            content: Union[bytes, BinaryIO, Path],
-            file_size: int,
-            folder_id: Optional[str],
-            file_type: str,
-            mime_type: str,
-            file_hash: str,
-            is_temporary: Optional[bool] = False,
-            expire_seconds: Optional[int] = None,
-            **metadata
-    ) -> FileUploadResponse:
-        """客户端直传实现"""
-        # 获取上传URL，以及对应的文件和上传文件信息
-        upload_url_resp = self.generate_upload_url(
-            file_name=file_name,
-            file_size=file_size,
-            folder_id=folder_id,
-            file_type=file_type,
-            mime_type=mime_type,
-            file_hash=file_hash,
-            is_temporary=is_temporary,
-            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
-            **metadata
-        )
-
-        # 上传文件到对象存储
-        self.http_uploader.upload(
-            url=upload_url_resp.upload_url,
-            content=content,
-            headers={"Content-Type": mime_type},
-            total_size=file_size,
-        )
-
-        # 确认上传完成
-        self._confirm_upload_completed(
-            file_id=upload_url_resp.file.id,
-            **metadata
-        )
-
-        # 返回文件信息
-        return FileUploadResponse(
-            file=upload_url_resp.file,
-            upload_file=upload_url_resp.upload_file
-        )
-
-    def _upload_resumable(
-            self,
-            file_name: str,
-            content: Union[bytes, BinaryIO, Path],
-            file_size: int,
-            folder_id: Optional[str],
-            file_type: str,
-            mime_type: str,
-            file_hash: str,
-            is_temporary: Optional[bool] = False,
-            expire_seconds: Optional[int] = None,
-            **metadata
-    ) -> FileUploadResponse:
-        """断点续传实现"""
-        # 获取断点续传URL，以及对应的文件和上传文件信息
-        upload_url_resp = self._generate_resumable_upload_url(
-            file_name=file_name,
-            file_size=file_size,
-            folder_id=folder_id,
-            file_type=file_type,
-            mime_type=mime_type,
-            file_hash=file_hash,
-            is_temporary=is_temporary,
-            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
-            **metadata
-        )
-
-        # 开启断点续传
-        upload_url = self.http_uploader.start_resumable_session(
-            url=upload_url_resp.upload_url,
-            total_file_size=file_size,
-            mine_type=mime_type,
-        )
-
-        # 上传文件到对象存储
-        self.http_uploader.upload(
-            url=upload_url,
-            content=content,
-            headers={"Content-Type": mime_type},
-            total_size=file_size,
-            is_resume=True
-        )
-
-        # 确认上传完成
-        self._confirm_upload_completed(
-            file_id=upload_url_resp.file.id,
-            **metadata
-        )
-
-        # 返回文件信息
-        return FileUploadResponse(
-            file=upload_url_resp.file,
-            upload_file=upload_url_resp.upload_file
-        )
-
-    def generate_upload_url(
-            self,
-            file_name: str,
-            file_size: int,
-            folder_id: Optional[str] = None,
-            file_type: str = "file",
-            mime_type: str = None,
-            file_hash: str = None,
-            is_temporary: Optional[bool] = False,
-            expire_seconds: Optional[int] = None,
-            **metadata
-    ) -> UploadUrlResponse:
-        """
-        生成上传URL（用于客户端直传）
-
-        Args:
-            file_name: 文件名
-            file_size: 文件大小
-            folder_id: 文件夹ID
-            file_type: 文件类型
-            mime_type: MIME类型
-            file_hash: 文件哈希
-            is_temporary: 是否为临时文件
-            expire_seconds: 过期秒数
-            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
-
-        Returns:
-            上传URL响应
-        """
-        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
-
-        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
-
-        request = file_service_pb2.UploadUrlRequest(
-            file_name=file_name,
-            file_size=file_size,
-            file_type=file_type,
-            mime_type=mime_type or "application/octet-stream",
-            file_hash=file_hash,
-            is_temporary=is_temporary,
-            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
-        )
-
-        if folder_id:
-            request.folder_id = folder_id
-
-        # 构建元数据
-        grpc_metadata = self.client.build_metadata(**metadata)
-
-        response = stub.GenerateUploadUrl(request, metadata=grpc_metadata)
-
-        return UploadUrlResponse(
-            file=self._convert_file_info(response.file),
-            upload_file=self._convert_upload_file_info(response.upload_file),
-            upload_url=response.url
-        )
-
-    def upload(
-            self,
-            file: Union[str, Path, BinaryIO, bytes],
-            *,
-            folder_id: Optional[str] = None,
-            mode: Optional[UploadMode] = UploadMode.NORMAL,
-            is_temporary: Optional[bool] = False,
-            expire_seconds: Optional[int] = None,
-            **metadata
-    ) -> FileUploadResponse:
-        """
-        统一的文件上传接口
-
-        Args:
-            file: 文件路径、Path对象、文件对象或字节数据
-            folder_id: 目标文件夹ID（可选）
-            mode: 上传模式（NORMAL/DIRECT/RESUMABLE/STREAM）
-            is_temporary: 是否为临时文件
-            expire_seconds: 过期秒数
-            **metadata: 额外的元数据
-
-        Returns:
-            文件信息
-        """
-        # 解析文件参数，提取文件信息
-        file_name, content, file_size, mime_type, file_type, file_hash = self._extract_file_info(file)
-
-        # 根据文件大小自动选择上传模式
-        if mode == UploadMode.NORMAL:
-            ten_mb = 1024 * 1024 * 10
-            hundred_mb = 1024 * 1024 * 100
-            if file_size >= ten_mb and file_size < hundred_mb:  # 10MB
-                mode = UploadMode.STREAM  # 大文件自动使用流式上传模式
-            elif file_size > hundred_mb:
-                mode = UploadMode.RESUMABLE  # 特大文件自动使用断点续传模式
-
-        # 根据上传模式执行不同的上传逻辑
-        if mode == UploadMode.NORMAL:
-            # 普通上传（通过gRPC）
-            return self._upload_file(
-                file_name=file_name,
-                content=content,
-                folder_id=folder_id,
-                file_type=file_type,
-                mime_type=mime_type,
-                is_temporary=is_temporary,
-                expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
-                **metadata
-            )
-
-        elif mode == UploadMode.STREAM:
-            # 流式上传
-            return self._upload_stream(
-                file_name=file_name,
-                content=content,
-                file_size=file_size,
-                folder_id=folder_id,
-                file_type=file_type,
-                mime_type=mime_type,
-                file_hash=file_hash,
-                is_temporary=is_temporary,
-                expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
-                **metadata
-            )
-
-        elif mode == UploadMode.RESUMABLE:
-            # 断点续传
-            return self._upload_resumable(
-                file_name=file_name,
-                content=content,
-                file_size=file_size,
-                folder_id=folder_id,
-                file_type=file_type,
-                mime_type=mime_type,
-                file_hash=file_hash,
-                is_temporary=is_temporary,
-                expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
-                **metadata
-            )
-
-        else:
-            raise ValidationError(f"不支持的上传模式: {mode}")
-
-    def generate_download_url(
-            self,
-            file_id: str,
-            *,
-            expire_seconds: Optional[int] = None,
-            **metadata
-    ) -> str:
-        """
-        生成下载URL
-
-        Args:
-            file_id: 文件ID
-            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
-
-        Returns:
-            下载URL
-        """
-        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
-
-        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
-
-        request = file_service_pb2.DownloadUrlRequest(file_id=file_id,
-                                                      expire_seconds=expire_seconds if expire_seconds else None)
-
-        # 构建元数据
-        grpc_metadata = self.client.build_metadata(**metadata)
-
-        download_url_resp = stub.GenerateDownloadUrl(request, metadata=grpc_metadata)
-
-        return download_url_resp.url
-
-    def download(
-            self,
-            file_id: str,
-            save_path: Optional[Union[str, Path]] = None,
-            chunk_size: Optional[int] = None,
-            **metadata
-    ) -> Union[bytes, Path, Iterator[bytes]]:
-        """
-        统一的文件下载接口
-
-        Args:
-            file_id: 文件ID
-            save_path: 保存路径（如果为None，返回字节数据）
-            chunk_size: 分片大小
-            **metadata: 额外的元数据
-
-        Returns:
-            - NORMAL模式：下载的内容（字节）或保存的文件路径
-            - STREAM模式：返回迭代器，逐块返回数据
-        """
-
-        # 获取下载URL
-        download_url = self.generate_download_url(file_id, **metadata)
-
-        return self.http_downloader.download(
-            url=download_url,
-            save_path=save_path,
-            chunk_size=chunk_size,
-        )
+"""
+同步二进制大对象服务
+"""
+import hashlib
+from pathlib import Path
+from typing import Optional, Union, BinaryIO, Iterator
+
+from .base_file_service import BaseFileService
+from ...enums import UploadMode
+from ...errors import ValidationError
+from ...rpc import SyncGrpcClient
+from ...schemas import FileUploadResponse, UploadUrlResponse
+from ...utils import HttpUploader, HttpDownloader, retry_with_backoff, get_file_mime_type
+
+
+class SyncBlobService(BaseFileService):
+    """同步文件（二进制大对象）服务"""
+
+    def __init__(self, client: SyncGrpcClient):
+        """
+        初始化文件（二进制大对象）服务
+
+        Args:
+            client: 同步gRPC客户端
+        """
+        self.client = client
+        self.http_uploader = HttpUploader()
+        self.http_downloader = HttpDownloader()
+
+    def _generate_resumable_upload_url(
+            self,
+            file_name: str,
+            file_size: int,
+            folder_id: Optional[str] = None,
+            file_type: str = "dat",
+            mime_type: str = None,
+            file_hash: str = None,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> UploadUrlResponse:
+        """
+        生成断点续传URL
+
+        Args:
+            file_name: 文件名
+            file_size: 文件大小
+            folder_id: 文件夹ID
+            file_type: 文件类型
+            mime_type: MIME类型
+            file_hash: 文件哈希
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            上传URL响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.UploadUrlRequest(
+            file_name=file_name,
+            file_size=file_size,
+            file_type=file_type,
+            mime_type=mime_type or "application/octet-stream",
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+        )
+
+        if folder_id:
+            request.folder_id = folder_id
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+
+        response = stub.GenerateResumableUploadUrl(request, metadata=grpc_metadata)
+
+        return UploadUrlResponse(
+            file=self._convert_file_info(response.file),
+            upload_file=self._convert_upload_file_info(response.upload_file),
+            upload_url=response.url
+        )
+
+    def _confirm_upload_completed(self, file_id: str, request_id: Optional[str] = None,
+                                  **metadata) -> None:
+        """
+        确认上传完成
+
+        Args:
+            file_id: 文件ID
+            request_id: 请求ID（可选，如果不提供则自动生成）
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.UploadCompletedRequest(file_id=file_id)
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+
+        stub.ConfirmUploadCompleted(request, metadata=grpc_metadata)
+
+    @retry_with_backoff(max_retries=3)
+    def _upload_file(
+            self,
+            file_name: str,
+            content: Union[bytes, BinaryIO, Path],
+            folder_id: Optional[str] = None,
+            file_type: str = "dat",
+            mime_type: Optional[str] = None,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """
+        直接上传文件
+
+        Args:
+            file_name: 文件名
+            content: 文件内容（字节、文件对象或路径）
+            folder_id: 文件夹ID
+            file_type: 文件类型
+            mime_type: MIME类型
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            request_id: 请求ID（可选，如果不提供则自动生成）
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            文件信息
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        # 处理不同类型的内容
+        if isinstance(content, Path):
+            if not content.exists():
+                raise ValidationError(f"文件不存在: {content}")
+            with open(content, "rb") as f:
+                file_bytes = f.read()
+            if not mime_type:
+                mime_type = get_file_mime_type(content)
+        elif isinstance(content, bytes):
+            file_bytes = content
+        elif hasattr(content, 'read'):
+            file_bytes = content.read()
+        else:
+            raise ValidationError("不支持的内容类型")
+
+        # 构建请求
+        request = file_service_pb2.UploadFileRequest(
+            file_name=file_name,
+            content=file_bytes,
+            file_type=file_type,
+            mime_type=mime_type or "application/octet-stream",
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds,
+        )
+
+        if folder_id:
+            request.folder_id = folder_id
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+
+        # 发送请求
+        response = stub.UploadFile(request, metadata=grpc_metadata)
+
+        # 转换响应
+        return FileUploadResponse(
+            file=self._convert_file_info(response.file),
+            upload_file=self._convert_upload_file_info(response.upload_file),
+        )
+
+    def _upload_stream(
+            self,
+            file_name: str,
+            content: Union[bytes, BinaryIO, Path],
+            file_size: int,
+            folder_id: Optional[str],
+            file_type: str,
+            mime_type: str,
+            file_hash: str,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """客户端直传实现"""
+        # 获取上传URL，以及对应的文件和上传文件信息
+        upload_url_resp = self.generate_upload_url(
+            file_name=file_name,
+            file_size=file_size,
+            folder_id=folder_id,
+            file_type=file_type,
+            mime_type=mime_type,
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+            request_id=request_id,
+            **metadata
+        )
+
+        # 如果URL为空，说明文件已存在（哈希重复），直接返回
+        if not upload_url_resp.upload_url:
+            return FileUploadResponse(
+                file=upload_url_resp.file,
+                upload_file=upload_url_resp.upload_file
+            )
+
+        # 上传文件到对象存储
+        self.http_uploader.upload(
+            url=upload_url_resp.upload_url,
+            content=content,
+            headers={"Content-Type": mime_type},
+            total_size=file_size,
+        )
+
+        # 确认上传完成
+        self._confirm_upload_completed(
+            file_id=upload_url_resp.file.id,
+            request_id=request_id,
+            **metadata
+        )
+
+        # 返回文件信息
+        return FileUploadResponse(
+            file=upload_url_resp.file,
+            upload_file=upload_url_resp.upload_file
+        )
+
+    def _upload_resumable(
+            self,
+            file_name: str,
+            content: Union[bytes, BinaryIO, Path],
+            file_size: int,
+            folder_id: Optional[str],
+            file_type: str,
+            mime_type: str,
+            file_hash: str,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """断点续传实现"""
+        # 获取断点续传URL，以及对应的文件和上传文件信息
+        upload_url_resp = self._generate_resumable_upload_url(
+            file_name=file_name,
+            file_size=file_size,
+            folder_id=folder_id,
+            file_type=file_type,
+            mime_type=mime_type,
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+            request_id=request_id,
+            **metadata
+        )
+
+        # 如果URL为空，说明文件已存在（哈希重复），直接返回
+        if not upload_url_resp.upload_url:
+            return FileUploadResponse(
+                file=upload_url_resp.file,
+                upload_file=upload_url_resp.upload_file
+            )
+
+        # 开启断点续传
+        upload_url = self.http_uploader.start_resumable_session(
+            url=upload_url_resp.upload_url,
+            total_file_size=file_size,
+            mine_type=mime_type,
+        )
+
+        # 上传文件到对象存储
+        self.http_uploader.upload(
+            url=upload_url,
+            content=content,
+            headers={"Content-Type": mime_type},
+            total_size=file_size,
+            is_resume=True
+        )
+
+        # 确认上传完成
+        self._confirm_upload_completed(
+            file_id=upload_url_resp.file.id,
+            request_id=request_id,
+            **metadata
+        )
+
+        # 返回文件信息
+        return FileUploadResponse(
+            file=upload_url_resp.file,
+            upload_file=upload_url_resp.upload_file
+        )
+
+    def generate_upload_url(
+            self,
+            file_name: str,
+            file_size: int,
+            folder_id: Optional[str] = None,
+            file_type: str = "dat",
+            mime_type: str = None,
+            file_hash: str = None,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> UploadUrlResponse:
+        """
+        生成上传URL（用于客户端直传）
+
+        Args:
+            file_name: 文件名
+            file_size: 文件大小
+            folder_id: 文件夹ID
+            file_type: 文件类型
+            mime_type: MIME类型
+            file_hash: 文件哈希
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            request_id: 请求ID（可选，如果不提供则自动生成）
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            上传URL响应
+            注意：如果文件哈希已存在（重复上传），upload_url 会为空，
+            此时应直接使用返回的 file 和 upload_file 信息，无需再次上传
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.UploadUrlRequest(
+            file_name=file_name,
+            file_size=file_size,
+            file_type=file_type,
+            mime_type=mime_type or "application/octet-stream",
+            file_hash=file_hash,
+            is_temporary=is_temporary,
+            expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+        )
+
+        if folder_id:
+            request.folder_id = folder_id
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+
+        response = stub.GenerateUploadUrl(request, metadata=grpc_metadata)
+
+        return UploadUrlResponse(
+            file=self._convert_file_info(response.file),
+            upload_file=self._convert_upload_file_info(response.upload_file),
+            upload_url=response.url
+        )
+
+    def upload(
+            self,
+            file: Optional[Union[str, Path, BinaryIO, bytes]] = None,
+            *,
+            folder_id: Optional[str] = None,
+            mode: Optional[UploadMode] = UploadMode.NORMAL,
+            is_temporary: Optional[bool] = False,
+            expire_seconds: Optional[int] = None,
+            url: Optional[str] = None,
+            file_name: Optional[str] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> FileUploadResponse:
+        """
+        统一的文件上传接口
+
+        Args:
+            file: 文件路径、Path对象、文件对象或字节数据（当使用url参数时可省略）
+            folder_id: 目标文件夹ID（可选）
+            mode: 上传模式（NORMAL/DIRECT/RESUMABLE/STREAM）
+            is_temporary: 是否为临时文件
+            expire_seconds: 过期秒数
+            url: 要下载并上传的URL（可选）
+            file_name: 当使用url参数时指定的文件名（可选）
+            request_id: 请求ID（可选，如果不提供则自动生成）
+            **metadata: 额外的元数据
+
+        Returns:
+            文件信息
+            
+        Note:
+            必须提供 file 或 url 参数之一
+        """
+        # 参数验证：必须提供 file 或 url 之一
+        if file is None and not url:
+            raise ValidationError("必须提供 file 或 url 参数之一")
+        
+        # 如果提供了URL，先下载文件
+        if url:
+            # 下载文件到内存
+            downloaded_content = self.http_downloader.download(url)
+            
+            # 如果没有指定文件名，从URL中提取
+            if not file_name:
+                from urllib.parse import urlparse
+                from pathlib import Path as PathLib
+                parsed_url = urlparse(url)
+                url_path = PathLib(parsed_url.path)
+                file_name = url_path.name if url_path.name else f"download_{hashlib.md5(url.encode()).hexdigest()[:8]}"
+            
+            # 使用下载的内容作为file参数
+            file = downloaded_content
+            
+            # 提取文件信息（bytes会返回默认的MIME类型，我们稍后会基于文件名重新计算）
+            extracted_file_name, content, file_size, _, _, file_hash = self._extract_file_info(file)
+            
+            # file_name已经在上面设置了（要么是用户指定的，要么是从URL提取的）
+            extracted_file_name = file_name
+            
+            # 基于文件名计算文件类型和MIME类型
+            file_type = Path(extracted_file_name).suffix.lstrip('.').lower() if Path(extracted_file_name).suffix else 'dat'
+            mime_type = get_file_mime_type(Path(extracted_file_name))
+        else:
+            # 解析文件参数，提取文件信息
+            extracted_file_name, content, file_size, mime_type, file_type, file_hash = self._extract_file_info(file)
+
+        # 根据文件大小自动选择上传模式
+        if mode == UploadMode.NORMAL:
+            ten_mb = 1024 * 1024 * 10
+            hundred_mb = 1024 * 1024 * 100
+            if file_size >= ten_mb and file_size < hundred_mb:  # 10MB
+                mode = UploadMode.STREAM  # 大文件自动使用流式上传模式
+            elif file_size > hundred_mb:
+                mode = UploadMode.RESUMABLE  # 特大文件自动使用断点续传模式
+
+        # 根据上传模式执行不同的上传逻辑
+        if mode == UploadMode.NORMAL:
+            # 普通上传（通过gRPC）
+            return self._upload_file(
+                file_name=extracted_file_name,
+                content=content,
+                folder_id=folder_id,
+                file_type=file_type,
+                mime_type=mime_type,
+                is_temporary=is_temporary,
+                expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+                request_id=request_id,
+                **metadata
+            )
+
+        elif mode == UploadMode.STREAM:
+            # 流式上传
+            return self._upload_stream(
+                file_name=extracted_file_name,
+                content=content,
+                file_size=file_size,
+                folder_id=folder_id,
+                file_type=file_type,
+                mime_type=mime_type,
+                file_hash=file_hash,
+                is_temporary=is_temporary,
+                expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+                request_id=request_id,
+                **metadata
+            )
+
+        elif mode == UploadMode.RESUMABLE:
+            # 断点续传
+            return self._upload_resumable(
+                file_name=extracted_file_name,
+                content=content,
+                file_size=file_size,
+                folder_id=folder_id,
+                file_type=file_type,
+                mime_type=mime_type,
+                file_hash=file_hash,
+                is_temporary=is_temporary,
+                expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
+                request_id=request_id,
+                **metadata
+            )
+
+        else:
+            raise ValidationError(f"不支持的上传模式: {mode}")
+
+    def generate_download_url(
+            self,
+            file_id: str,
+            *,
+            expire_seconds: Optional[int] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> str:
+        """
+        生成下载URL
+
+        Args:
+            file_id: 文件ID
+            request_id: 请求ID（可选，如果不提供则自动生成）
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+
+        Returns:
+            下载URL
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.DownloadUrlRequest(file_id=file_id,
+                                                      expire_seconds=expire_seconds if expire_seconds else None)
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+
+        download_url_resp = stub.GenerateDownloadUrl(request, metadata=grpc_metadata)
+
+        return download_url_resp.url
+
+    def download(
+            self,
+            file_id: str,
+            save_path: Optional[Union[str, Path]] = None,
+            chunk_size: Optional[int] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> Union[bytes, Path, Iterator[bytes]]:
+        """
+        统一的文件下载接口
+
+        Args:
+            file_id: 文件ID
+            save_path: 保存路径（如果为None，返回字节数据）
+            chunk_size: 分片大小
+            request_id: 请求ID（可选，如果不提供则自动生成）
+            **metadata: 额外的元数据
+
+        Returns:
+            - NORMAL模式：下载的内容（字节）或保存的文件路径
+            - STREAM模式：返回迭代器，逐块返回数据
+        """
+
+        # 获取下载URL
+        download_url = self.generate_download_url(file_id, request_id=request_id, **metadata)
+
+        return self.http_downloader.download(
+            url=download_url,
+            save_path=save_path,
+            chunk_size=chunk_size,
+        )