android-frame/frame/oss/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

模块概述

frame/oss是一个对象存储服务(OSS)封装模块，为Android应用提供统一的文件上传下载接口，支持阿里云OSS和腾讯云COS两种后端服务。

项目结构

src/main/java/com/adealink/frame/oss/
├── IOssService.kt           # OSS服务接口定义
├── AbstractOssService.kt    # OSS服务抽象基类
├── IOssCompressor.kt        # 文件压缩器接口
├── alibaba/                 # 阿里云OSS实现
│   └── AliyunOssService.kt  # 阿里云OSS服务实现
├── tencent/                 # 腾讯云COS实现
│   └── QCloudOssService.kt  # 腾讯云COS服务实现
├── config/
│   └── IOssConfig.kt        # OSS配置接口
├── data/
│   ├── OssData.kt          # 数据模型(UploadFile, OssToken等)
│   ├── OssScene.kt         # 上传场景枚举
│   └── Error.kt            # 错误类型定义
├── listener/
│   └── IOssListener.kt     # 上传下载进度回调
└── constant/
    └── Tags.kt             # 日志标签常量

构建和依赖

关键依赖

• libs.aliyun.oss - 阿里云OSS Android SDK
• libs.qcloud.cos - 腾讯云COS Android SDK
• project(":frame:base") - 基础框架模块(提供Rlt状态管理)
• project(":frame:coroutine") - 协程工具模块
• project(":frame:util") - 工具类模块

核心架构

服务抽象层

• IOssService: 定义统一的OSS服务接口
• AbstractOssService: 提供通用功能实现，处理上传通知
• AliyunOssService和QCloudOssService: 分别实现阿里云和腾讯云的具体逻辑

配置管理

• IOssConfig: 抽象配置类，包含endpoint、bucket、认证token获取等配置
• 支持STS临时token认证机制
• 内置超时、重试、并发控制参数

文件类型系统

• UploadFile.FileType: 枚举定义支持的文件类型(图片、视频、音频等)
• UploadFile.LocalFile和UploadFile.ByteFile: 支持本地文件和内存数据上传
• OssScene: 场景枚举，用于文件路径分类

上传路径生成规则

{fileType.dir}/{hashUid或deviceId}/{scene.dir}/{fileName}.{suffix}

开发指南

实现IOssConfig

必须实现的抽象方法：

• getOssToken(): 返回STS临时token
• compressor: 文件压缩器实例
• 各种配置属性(context, endpoint, hashUid等)

文件上传最佳实践

1. 使用suspendUploadFile()进行异步上传
2. 设置合适的IOssListener监听进度和结果
3. 根据文件类型选择是否压缩(compress = true/false)
4. 公开文件设置public = true获取HTTP URL

错误处理

• 所有操作返回Rlt<T>类型，包含成功/失败状态
• OSSUploadError和OSSDownloadError封装具体错误信息
• 通过日志标签TAG_OSS_UPLOAD和TAG_OSS_DOWNLOAD调试