# 阿里云OSS对象存储工具

## 📋 工具概述

这是一个基于阿里云OSS（Object Storage Service）对象存储服务的Java工具包，提供了完整的文件上传、下载、删除和URL生成功能。该工具使用Spring Boot框架，支持配置化管理，适合在企业级应用中使用。

## ✨ 主要功能

- 🔄 **文件上传**: 支持MultipartFile文件上传到阿里云OSS
- 📥 **文件下载**: 从OSS下载文件并返回输入流
- 🔗 **预签名URL**: 生成带有时效性的文件访问链接
- 🗑️ **文件删除**: 安全删除OSS中的文件
- ⚙️ **配置管理**: 通过YAML配置文件管理OSS连接参数

## 📂 文件结构

```
阿里oss云存储/
├── README.md           # 本说明文档
├── OSSService.java     # OSS服务核心实现类
├── OSSConfig.java      # OSS配置类，用于读取配置文件
└── yml配置.txt         # 配置文件模板
```

## 🔧 配置说明

### 1. 依赖配置

在你的 `pom.xml` 中添加以下依赖：

```xml
<!-- 阿里云OSS SDK -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.15.1</version>
</dependency>

<!-- Spring Boot配置处理器 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

<!-- Lombok（用于简化代码） -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>
```

### 2. YAML配置

在你的 `application.yml` 文件中添加以下配置：

```yaml
# 阿里云OSS配置
aliyun:
  oss:
    # OSS访问端点（根据你的地域选择）
    endpoint: oss-cn-guangzhou.aliyuncs.com  # 广州节点
    # 访问密钥ID（从阿里云控制台获取）
    access-key-id: YOUR_ACCESS_KEY_ID
    # 访问密钥Secret（从阿里云控制台获取）
    access-key-secret: YOUR_ACCESS_KEY_SECRET
    # 存储桶名称
    bucket-name: YOUR_BUCKET_NAME
    # 默认URL有效期（秒）
    default-expiration: 604800  # 7天
```

**⚠️ 安全提醒**: 
- 不要将真实的密钥直接写在配置文件中
- 建议使用环境变量或加密配置管理敏感信息

## 📋 核心类说明

### OSSConfig.java - 配置类
```java
@Component
@ConfigurationProperties(prefix = "aliyun.oss")
@Data
public class OSSConfig {
    private String endpoint;          // OSS访问端点
    private String accessKeyId;       // 访问密钥ID
    private String accessKeySecret;   // 访问密钥Secret
    private String bucketName;        // 存储桶名称
    private int defaultExpiration = 3600; // 默认过期时间
}
```

### OSSService.java - 服务类
这是核心服务类，提供以下主要方法：

#### 1. 文件上传
```java
/**
 * 上传文件到OSS
 * @param objectName OSS中的文件路径/文件名
 * @param file 要上传的MultipartFile文件
 * @return 文件的预签名访问URL，失败时返回null
 */
public String uploadFile(String objectName, MultipartFile file)
```

#### 2. 文件下载
```java
/**
 * 从OSS下载文件
 * @param objectName OSS中的文件路径
 * @return 文件的输入流
 * @throws IOException 下载失败时抛出异常
 */
public InputStream downloadFile(String objectName) throws IOException
```

#### 3. 生成预签名URL
```java
/**
 * 生成预签名URL（使用默认有效期）
 * @param objectName OSS中的文件路径
 * @return 带有时效性的文件访问URL
 */
public String generatePresignedUrl(String objectName)

/**
 * 生成预签名URL（自定义有效期）
 * @param objectName OSS中的文件路径
 * @param expirationSeconds 有效期（秒）
 * @return 带有时效性的文件访问URL
 */
public String generatePresignedUrl(String objectName, int expirationSeconds)
```

#### 4. 文件删除
```java
/**
 * 删除OSS中的文件
 * @param objectName OSS中的文件路径
 * @return true表示删除成功，false表示删除失败
 */
public boolean deleteFile(String objectName)
```

## 🚀 使用示例

### 在Controller中使用

```java
@RestController
@RequestMapping("/api/file")
public class FileController {
    
    @Autowired
    private OSSService ossService;
    
    /**
     * 上传文件
     */
    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return ResponseEntity.badRequest().body("文件不能为空");
        }
        
        // 生成唯一的文件名（可以加上时间戳避免重名）
        String objectName = "uploads/" + System.currentTimeMillis() + "_" + file.getOriginalFilename();
        
        // 上传文件并获取访问URL
        String fileUrl = ossService.uploadFile(objectName, file);
        
        if (fileUrl != null) {
            return ResponseEntity.ok("文件上传成功，访问链接: " + fileUrl);
        } else {
            return ResponseEntity.status(500).body("文件上传失败");
        }
    }
    
    /**
     * 下载文件
     */
    @GetMapping("/download")
    public ResponseEntity<Resource> downloadFile(@RequestParam("filename") String filename) {
        try {
            InputStream inputStream = ossService.downloadFile(filename);
            InputStreamResource resource = new InputStreamResource(inputStream);
            
            return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + filename + "\"")
                    .body(resource);
        } catch (IOException e) {
            return ResponseEntity.status(404).body(null);
        }
    }
    
    /**
     * 获取文件访问链接
     */
    @GetMapping("/url")
    public ResponseEntity<String> getFileUrl(@RequestParam("filename") String filename) {
        String url = ossService.generatePresignedUrl(filename);
        return ResponseEntity.ok("文件访问链接: " + url);
    }
    
    /**
     * 删除文件
     */
    @DeleteMapping("/delete")
    public ResponseEntity<String> deleteFile(@RequestParam("filename") String filename) {
        boolean success = ossService.deleteFile(filename);
        if (success) {
            return ResponseEntity.ok("文件删除成功");
        } else {
            return ResponseEntity.status(500).body("文件删除失败");
        }
    }
}
```

## 🔍 功能特点

### 1. 自动资源管理
- 使用 `@PreDestroy` 注解确保应用关闭时正确释放OSS客户端资源
- 在文件操作中使用 try-with-resources 确保输入流正确关闭

### 2. 异常处理
- 完善的异常捕获和处理机制
- 详细的错误日志输出，便于问题排查

### 3. 配置化管理
- 支持通过YAML配置文件管理所有OSS连接参数
- 支持自定义默认过期时间

### 4. 灵活的URL生成
- 支持使用默认过期时间生成预签名URL
- 支持自定义过期时间，满足不同业务需求

## ⚠️ 注意事项

1. **权限配置**: 确保你的阿里云账户有足够的OSS操作权限
2. **存储桶策略**: 根据需要配置存储桶的读写权限
3. **文件命名**: 建议使用有意义的文件路径和名称，便于管理
4. **大文件上传**: 对于大文件，建议使用分片上传功能（可后续扩展）
5. **成本控制**: 注意OSS的存储和流量费用

## 🔧 扩展建议

1. **分片上传**: 对于大文件，可以添加分片上传功能
2. **图片处理**: 可以集成阿里云的图片处理服务
3. **CDN加速**: 结合阿里云CDN提高文件访问速度
4. **监控告警**: 添加文件操作的监控和告警功能

## 📞 技术支持

如果在使用过程中遇到问题，可以：
1. 查看阿里云OSS官方文档
2. 检查配置文件是否正确
3. 查看应用日志中的详细错误信息

---

**最后更新**: 2024年
**兼容版本**: Spring Boot 2.x+, Java 8+