@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-oss/README.md

@@ -0,0 +1,594 @@
+---
+name: avatar-boot-starter-oss
+description: 当涉及 OSS、对象存储、文件上传、文件下载、阿里云存储 相关功能时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于阿里云 OSS SDK 3.18.1 的对象存储能力，包含文件上传下载、分片上传、签名 URL、STS 直传。
+---
+
+Avatar Boot 的阿里云 OSS 对象存储集成模块，基于 aliyun-sdk-oss 3.18.1 提供开箱即用的文件上传、下载和管理能力。
+
+## 功能特性
+
+- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，自动装配 OSSClient
+- ✅ **简单上传** - 支持 putObject 方式上传文件和流
+- ✅ **分片上传** - 支持大文件分片上传，自动管理分片生命周期
+- ✅ **签名 URL** - 生成预签名 URL，支持临时授权访问
+- ✅ **STS 直传** - 支持客户端直传模式，减轻服务端带宽压力
+- ✅ **生命周期管理** - 支持配置文件自动过期和存储类型转换
+
+## 快速开始
+
+### 1. 添加依赖
+
+在项目的 `pom.xml` 中添加依赖：
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-oss</artifactId>
+</dependency>
+```
+
+> 版本由 Avatar Boot BOM 统一管理，无需指定 version。内置 aliyun-sdk-oss 3.18.1。
+
+### 2. 配置文件
+
+在 `application.yml` 中添加 OSS 配置：
+
+```yaml
+aliyun:
+  oss:
+    endpoint: https://oss-cn-shanghai.aliyuncs.com   # OSS 端点
+    access-key-id: ${OSS_ACCESS_KEY_ID}              # AccessKey ID（从环境变量读取）
+    access-key-secret: ${OSS_ACCESS_KEY_SECRET}       # AccessKey Secret（从环境变量读取）
+    bucket-name: your-bucket-name                     # 默认 Bucket
+```
+
+**安全提醒**：AccessKey 信息禁止硬编码在配置文件中，必须通过环境变量或密钥管理服务注入。
+
+### 3. OSSClient 配置类
+
+```java
+package com.example.config;
+
+import com.aliyun.oss.OSS;
+import com.aliyun.oss.OSSClientBuilder;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class OssConfig {
+
+    @Value("${aliyun.oss.endpoint}")
+    private String endpoint;
+
+    @Value("${aliyun.oss.access-key-id}")
+    private String accessKeyId;
+
+    @Value("${aliyun.oss.access-key-secret}")
+    private String accessKeySecret;
+
+    @Bean(destroyMethod = "shutdown")
+    public OSS ossClient() {
+        return new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
+    }
+}
+```
+
+## 文件上传
+
+### 简单上传（putObject）
+
+```java
+package com.example.service;
+
+import com.aliyun.oss.OSS;
+import com.aliyun.oss.model.ObjectMetadata;
+import com.aliyun.oss.model.PutObjectResult;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.InputStream;
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.util.UUID;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class OssUploadService {
+
+    private final OSS ossClient;
+
+    @Value("${aliyun.oss.bucket-name}")
+    private String bucketName;
+
+    /**
+     * 上传文件
+     * @return 文件访问路径
+     */
+    public String uploadFile(MultipartFile file) {
+        // 生成文件路径：日期 + UUID
+        String objectKey = generateObjectKey(file.getOriginalFilename());
+
+        try (InputStream inputStream = file.getInputStream()) {
+            ObjectMetadata metadata = new ObjectMetadata();
+            metadata.setContentType(file.getContentType());
+            metadata.setContentLength(file.getSize());
+            // 设置自定义元数据
+            metadata.addUserMetadata("original-filename", file.getOriginalFilename());
+
+            PutObjectResult result = ossClient.putObject(bucketName, objectKey, inputStream, metadata);
+            log.info("文件上传成功: objectKey={}, etag={}", objectKey, result.getETag());
+
+            return objectKey;
+        } catch (Exception e) {
+            log.error("文件上传失败: filename={}", file.getOriginalFilename(), e);
+            throw new RuntimeException("文件上传失败", e);
+        }
+    }
+
+    /**
+     * 上传字符串内容
+     */
+    public String uploadContent(String content, String fileName) {
+        String objectKey = generateObjectKey(fileName);
+        ossClient.putObject(bucketName, objectKey, new java.io.ByteArrayInputStream(content.getBytes()));
+        return objectKey;
+    }
+
+    /**
+     * 生成文件路径：按日期分目录 + UUID 文件名
+     * 格式：upload/2026/03/09/uuid.ext
+     */
+    private String generateObjectKey(String originalFilename) {
+        String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
+        String ext = "";
+        if (originalFilename != null && originalFilename.contains(".")) {
+            ext = originalFilename.substring(originalFilename.lastIndexOf("."));
+        }
+        return String.format("upload/%s/%s%s", datePath, UUID.randomUUID().toString().replace("-", ""), ext);
+    }
+}
+```
+
+### 分片上传（Multipart Upload）
+
+```java
+@Service
+@RequiredArgsConstructor
+public class MultipartUploadService {
+
+    private final OSS ossClient;
+
+    @Value("${aliyun.oss.bucket-name}")
+    private String bucketName;
+
+    /**
+     * 分片上传大文件
+     * @param file 文件
+     * @param partSize 分片大小（字节），建议 5MB-100MB
+     */
+    public String multipartUpload(MultipartFile file, long partSize) {
+        String objectKey = "upload/" + LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"))
+                + "/" + UUID.randomUUID().toString().replace("-", "")
+                + getExtension(file.getOriginalFilename());
+
+        // 1. 初始化分片上传
+        InitiateMultipartUploadRequest initRequest =
+                new InitiateMultipartUploadRequest(bucketName, objectKey);
+        InitiateMultipartUploadResult initResult = ossClient.initiateMultipartUpload(initRequest);
+        String uploadId = initResult.getUploadId();
+        log.info("分片上传初始化: uploadId={}, objectKey={}", uploadId, objectKey);
+
+        try {
+            long fileSize = file.getSize();
+            int partCount = (int) Math.ceil((double) fileSize / partSize);
+            List<PartETag> partETags = new ArrayList<>();
+
+            InputStream inputStream = file.getInputStream();
+            for (int i = 0; i < partCount; i++) {
+                long startPos = i * partSize;
+                long curPartSize = Math.min(partSize, fileSize - startPos);
+
+                // 2. 上传分片
+                UploadPartRequest uploadPartRequest = new UploadPartRequest();
+                uploadPartRequest.setBucketName(bucketName);
+                uploadPartRequest.setKey(objectKey);
+                uploadPartRequest.setUploadId(uploadId);
+                uploadPartRequest.setInputStream(inputStream);
+                uploadPartRequest.setPartSize(curPartSize);
+                uploadPartRequest.setPartNumber(i + 1);
+
+                UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
+                partETags.add(uploadPartResult.getPartETag());
+                log.info("分片 {}/{} 上传成功", i + 1, partCount);
+            }
+
+            // 3. 完成分片上传
+            CompleteMultipartUploadRequest completeRequest =
+                    new CompleteMultipartUploadRequest(bucketName, objectKey, uploadId, partETags);
+            ossClient.completeMultipartUpload(completeRequest);
+            log.info("分片上传完成: objectKey={}", objectKey);
+
+            return objectKey;
+        } catch (Exception e) {
+            // 取消分片上传，清理已上传的分片
+            ossClient.abortMultipartUpload(
+                    new AbortMultipartUploadRequest(bucketName, objectKey, uploadId));
+            log.error("分片上传失败，已取消: uploadId={}", uploadId, e);
+            throw new RuntimeException("分片上传失败", e);
+        }
+    }
+
+    private String getExtension(String filename) {
+        if (filename != null && filename.contains(".")) {
+            return filename.substring(filename.lastIndexOf("."));
+        }
+        return "";
+    }
+}
+```
+
+## 文件下载
+
+### 服务端下载
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OssDownloadService {
+
+    private final OSS ossClient;
+
+    @Value("${aliyun.oss.bucket-name}")
+    private String bucketName;
+
+    /**
+     * 下载文件到字节数组
+     */
+    public byte[] downloadFile(String objectKey) {
+        try {
+            OSSObject ossObject = ossClient.getObject(bucketName, objectKey);
+            try (InputStream inputStream = ossObject.getObjectContent()) {
+                return inputStream.readAllBytes();
+            }
+        } catch (Exception e) {
+            log.error("文件下载失败: objectKey={}", objectKey, e);
+            throw new RuntimeException("文件下载失败", e);
+        }
+    }
+
+    /**
+     * 下载文件到 HttpServletResponse（浏览器下载）
+     */
+    public void downloadToResponse(String objectKey, String fileName,
+                                    HttpServletResponse response) {
+        try {
+            OSSObject ossObject = ossClient.getObject(bucketName, objectKey);
+            ObjectMetadata metadata = ossObject.getObjectMetadata();
+
+            response.setContentType(metadata.getContentType());
+            response.setContentLengthLong(metadata.getContentLength());
+            response.setHeader("Content-Disposition",
+                    "attachment; filename=" + URLEncoder.encode(fileName, StandardCharsets.UTF_8));
+
+            try (InputStream in = ossObject.getObjectContent();
+                 OutputStream out = response.getOutputStream()) {
+                in.transferTo(out);
+                out.flush();
+            }
+        } catch (Exception e) {
+            log.error("文件下载失败: objectKey={}", objectKey, e);
+            throw new RuntimeException("文件下载失败", e);
+        }
+    }
+}
+```
+
+### 生成预签名 URL
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OssPresignedUrlService {
+
+    private final OSS ossClient;
+
+    @Value("${aliyun.oss.bucket-name}")
+    private String bucketName;
+
+    /**
+     * 生成下载预签名 URL（有效期 1 小时）
+     */
+    public String generateDownloadUrl(String objectKey) {
+        return generatePresignedUrl(objectKey, 3600, HttpMethod.GET);
+    }
+
+    /**
+     * 生成上传预签名 URL（有效期 10 分钟）
+     */
+    public String generateUploadUrl(String objectKey) {
+        return generatePresignedUrl(objectKey, 600, HttpMethod.PUT);
+    }
+
+    /**
+     * 生成预签名 URL
+     * @param expireSeconds 过期时间（秒）
+     */
+    public String generatePresignedUrl(String objectKey, int expireSeconds, HttpMethod method) {
+        Date expiration = new Date(System.currentTimeMillis() + expireSeconds * 1000L);
+
+        GeneratePresignedUrlRequest request =
+                new GeneratePresignedUrlRequest(bucketName, objectKey, method);
+        request.setExpiration(expiration);
+
+        URL url = ossClient.generatePresignedUrl(request);
+        log.info("生成预签名 URL: objectKey={}, expireSeconds={}", objectKey, expireSeconds);
+        return url.toString();
+    }
+}
+```
+
+## 文件命名策略
+
+**推荐的文件命名规则：**
+
+```
+{业务类型}/{年}/{月}/{日}/{UUID}.{扩展名}
+```
+
+| 场景 | 路径格式 | 示例 |
+|------|---------|------|
+| 用户头像 | `avatar/{yyyy}/{MM}/{dd}/{uuid}.jpg` | `avatar/2026/03/09/a1b2c3d4.jpg` |
+| 文档上传 | `document/{yyyy}/{MM}/{dd}/{uuid}.pdf` | `document/2026/03/09/e5f6g7h8.pdf` |
+| 临时文件 | `temp/{yyyy}/{MM}/{dd}/{uuid}.tmp` | `temp/2026/03/09/i9j0k1l2.tmp` |
+| 导出文件 | `export/{yyyy}/{MM}/{dd}/{uuid}.xlsx` | `export/2026/03/09/m3n4o5p6.xlsx` |
+
+**命名规范：**
+
+1. **使用 UUID 作为文件名**：避免文件名冲突和中文编码问题
+2. **按日期分目录**：便于管理和生命周期策略配置
+3. **保留原始扩展名**：便于浏览器识别文件类型
+4. **不使用原始文件名**：防止路径遍历攻击和特殊字符问题
+
+## 客户端直传（STS Token）
+
+### 获取 STS 临时凭证
+
+```java
+package com.example.service;
+
+import com.aliyuncs.DefaultAcsClient;
+import com.aliyuncs.auth.sts.AssumeRoleRequest;
+import com.aliyuncs.auth.sts.AssumeRoleResponse;
+import com.aliyuncs.profile.DefaultProfile;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+@Slf4j
+@Service
+public class StsTokenService {
+
+    @Value("${aliyun.oss.access-key-id}")
+    private String accessKeyId;
+
+    @Value("${aliyun.oss.access-key-secret}")
+    private String accessKeySecret;
+
+    @Value("${aliyun.oss.sts.role-arn}")
+    private String roleArn;
+
+    @Value("${aliyun.oss.sts.region-id:cn-shanghai}")
+    private String regionId;
+
+    /**
+     * 获取 STS 临时凭证
+     * @param sessionName 会话名称
+     * @param durationSeconds 有效期（秒），最短 900，最长 3600
+     */
+    public StsCredentials getStsToken(String sessionName, long durationSeconds) {
+        try {
+            DefaultProfile profile = DefaultProfile.getProfile(regionId, accessKeyId, accessKeySecret);
+            DefaultAcsClient client = new DefaultAcsClient(profile);
+
+            AssumeRoleRequest request = new AssumeRoleRequest();
+            request.setRoleArn(roleArn);
+            request.setRoleSessionName(sessionName);
+            request.setDurationSeconds(durationSeconds);
+
+            // 限制上传路径的策略
+            String policy = """
+                    {
+                      "Version": "1",
+                      "Statement": [
+                        {
+                          "Effect": "Allow",
+                          "Action": ["oss:PutObject"],
+                          "Resource": ["acs:oss:*:*:your-bucket-name/upload/*"]
+                        }
+                      ]
+                    }
+                    """;
+            request.setPolicy(policy);
+
+            AssumeRoleResponse response = client.getAcsResponse(request);
+            AssumeRoleResponse.Credentials credentials = response.getCredentials();
+
+            return new StsCredentials(
+                    credentials.getAccessKeyId(),
+                    credentials.getAccessKeySecret(),
+                    credentials.getSecurityToken(),
+                    credentials.getExpiration()
+            );
+        } catch (Exception e) {
+            log.error("获取 STS Token 失败", e);
+            throw new RuntimeException("获取 STS Token 失败", e);
+        }
+    }
+}
+```
+
+### 前端直传接口
+
+```java
+@RestController
+@RequestMapping("/api/oss")
+@RequiredArgsConstructor
+public class OssController {
+
+    private final StsTokenService stsTokenService;
+
+    @Value("${aliyun.oss.endpoint}")
+    private String endpoint;
+
+    @Value("${aliyun.oss.bucket-name}")
+    private String bucketName;
+
+    /**
+     * 获取前端直传凭证
+     */
+    @GetMapping("/sts-token")
+    public Result<Map<String, Object>> getStsToken() {
+        StsCredentials credentials = stsTokenService.getStsToken("web-upload", 900);
+
+        Map<String, Object> data = new HashMap<>();
+        data.put("accessKeyId", credentials.getAccessKeyId());
+        data.put("accessKeySecret", credentials.getAccessKeySecret());
+        data.put("securityToken", credentials.getSecurityToken());
+        data.put("expiration", credentials.getExpiration());
+        data.put("endpoint", endpoint);
+        data.put("bucket", bucketName);
+        data.put("dir", "upload/" + LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd")) + "/");
+
+        return Result.success(data);
+    }
+}
+```
+
+## 生命周期管理
+
+### 配置文件自动过期
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OssLifecycleService {
+
+    private final OSS ossClient;
+
+    @Value("${aliyun.oss.bucket-name}")
+    private String bucketName;
+
+    /**
+     * 配置临时文件 7 天后自动删除
+     */
+    public void setupTempFileLifecycle() {
+        SetBucketLifecycleRequest request = new SetBucketLifecycleRequest(bucketName);
+
+        LifecycleRule rule = new LifecycleRule();
+        rule.setId("auto-delete-temp");
+        rule.setPrefix("temp/");
+        rule.setStatus(LifecycleRule.RuleStatus.Enabled);
+        rule.setExpirationDays(7);  // 7 天后删除
+
+        request.setLifecycleRules(List.of(rule));
+        ossClient.setBucketLifecycle(request);
+        log.info("临时文件生命周期规则已配置：7 天后自动删除");
+    }
+}
+```
+
+## 最佳实践
+
+### 1. 安全
+
+- **AccessKey 安全**：禁止硬编码，使用环境变量或密钥管理服务
+- **最小权限**：STS Token 限制具体的 Bucket 和路径
+- **Bucket 权限**：设为私有（private），通过签名 URL 访问
+- **上传校验**：校验文件类型和大小，防止恶意文件上传
+
+### 2. 性能
+
+- **大文件分片上传**：超过 100MB 的文件使用分片上传
+- **客户端直传**：使用 STS Token 方式，减轻服务端带宽压力
+- **CDN 加速**：静态资源配合 CDN 使用，降低 OSS 流量成本
+- **OSSClient 复用**：OSSClient 是线程安全的，全局复用，不要每次 new
+
+### 3. 可靠性
+
+- **异常处理**：捕获 OSSException 和 ClientException 分别处理
+- **分片上传清理**：失败时调用 abortMultipartUpload 清理碎片
+- **签名 URL 有效期**：下载 URL 1 小时，上传 URL 10 分钟
+- **文件存在性检查**：下载前使用 `doesObjectExist()` 检查
+
+### 4. 成本
+
+- **生命周期管理**：临时文件和日志设置自动过期
+- **存储类型**：不常访问的文件转为低频或归档存储
+- **签名 URL 替代公开访问**：避免 Bucket 设为 public-read
+
+## 常见问题
+
+### 1. AccessDenied（权限拒绝）
+
+**原因**：AccessKey 权限不足或 Bucket 策略限制
+
+**解决**：
+- 检查 AccessKey 是否有 OSS 操作权限
+- 检查 Bucket Policy 和 ACL 配置
+- STS Token 检查 Policy 中的 Resource 和 Action 是否匹配
+- 确认 AccessKey 未被禁用或过期
+
+### 2. 上传超时
+
+**原因**：文件过大或网络不稳定
+
+**解决**：
+- 大文件（>100MB）使用分片上传
+- 增大 OSSClient 超时配置
+- 检查网络带宽和稳定性
+- 使用客户端直传减轻服务端压力
+
+### 3. 签名 URL 无法访问
+
+**原因**：URL 已过期或签名方式不匹配
+
+**解决**：
+- 检查 URL 过期时间设置
+- 确保生成 URL 时的 endpoint 与实际访问一致
+- 检查是否使用了 HTTPS（endpoint 和访问方式要一致）
+- 验证 Bucket 名称和 objectKey 是否正确
+
+### 4. 分片上传碎片清理
+
+**原因**：分片上传未完成或失败后碎片未清理
+
+**解决**：
+- 上传失败时调用 `abortMultipartUpload` 清理
+- 配置 Bucket 生命周期规则自动清理碎片
+- 定期检查未完成的分片上传任务并清理
+
+### 5. 文件名中文乱码
+
+**原因**：文件名编码问题
+
+**解决**：
+- 使用 UUID 作为 OSS objectKey，不使用中文文件名
+- 原始文件名存储在数据库或 OSS 元数据中
+- 下载时通过 Content-Disposition 设置文件名，注意 URL 编码
+
+## 依赖版本
+
+- aliyun-sdk-oss: 3.18.1
+- Spring Boot: 3.5.3
+- Java: 21
+
+## 参考文档
+
+- [阿里云 OSS Java SDK 文档](https://help.aliyun.com/document_detail/32008.html)
+- [阿里云 OSS 最佳实践](https://help.aliyun.com/document_detail/31850.html)
+- [STS 临时授权访问](https://help.aliyun.com/document_detail/100624.html)