对象存储 OSS#

PPT 第 40 页给出定义：

阿里云对象存储 OSS（Object Storage Service），是一款海量、安全、低成本、高可靠的云存储服务。使用 OSS，您可以通过网络随时存储和调用包括文本、图片、音频和视频等在内的各种文件。

PPT 第 40、41 页配的都是阿里云官网 OSS 产品页的截图，上面那两个数字最能说明”高可靠”是什么水平：

拿上一节那三个问题对照一下，OSS 是怎么解决的：

PPT 第 41 页画的是”上传”这个动作：本地文件 → 上传 → 存进 OSS。要理解这张图，得先记住 OSS 里的两个名词（PPT 第 43 页给的定义）：

一个账号下可以建多个 bucket（PPT 第 46 页的示意图里就画了三个 bucket），每个对象都放在某个 bucket 里；上传完拿到的访问地址长这样：

1
https://<bucket名>.<endpoint去掉协议头>/<对象路径>
2
例如：https://java-ai.oss-cn-beijing.aliyuncs.com/2026/09/8f0a2c1e-....png

（这个拼法不是猜的——课程工具类 AliyunOSSOperator 最后一行就是照这个规则拼出来的，下面”案例集成”里会拆开看。）

为什么接口要”返回 URL”#

看一下课程接口文档（资料/02. 接口文档）里这个接口的定义就明白了：

也就是说：前端上传图片的目的不只是”把文件存起来”，还要拿回一个地址——新增员工表单里要把这个地址填进 emp.image，页面上要能立刻预览、以后列表里也要能显示。这正是上一篇本地存储版接口做不到的地方（它返回的 data 是 null）。

工具类 AliyunOSSOperator#

课程工程 src/main/java/com/itheima/utils/AliyunOSSOperator.java（完整代码，逐段都有注释）：

1
@Component
2
public class AliyunOSSOperator {
3

4
    @Value("${aliyun.oss.endpoint}")
5
    private String endpoint;
6
    @Value("${aliyun.oss.bucketName}")
7
    private String bucketName;
8
    @Value("${aliyun.oss.region}")
9
    private String region;
10

11
    public String upload(byte[] content, String originalFilename) throws Exception {
12
        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
13
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
14

15
        // 填写Object完整路径，例如2024/06/1.png。Object完整路径中不能包含Bucket名称。
16
        //获取当前系统日期的字符串,格式为 yyyy/MM
17
        String dir = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM"));
18
        //生成一个新的不重复的文件名
19
        String newFileName = UUID.randomUUID() + originalFilename.substring(originalFilename.lastIndexOf("."));
20
        String objectName = dir + "/" + newFileName;
21

22
        // 创建OSSClient实例。
23
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
24
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
25
        OSS ossClient = OSSClientBuilder.create()
26
                .endpoint(endpoint)
27
                .credentialsProvider(credentialsProvider)
28
                .clientConfiguration(clientBuilderConfiguration)
29
                .region(region)
30
                .build();
31

32
        try {
33
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content));
34
        } finally {
35
            ossClient.shutdown();
36
        }
37

38
        return endpoint.split("//")[0] + "//" + bucketName + "." + endpoint.split("//")[1] + "/" + objectName;
39
    }
40
}

这份代码看着长，拆成六块就清楚了：

接口开发#

PPT 第 47 页给出的 UploadController：

1
@Autowired
2
private AliyunOSSOperator aliyunOSSOperator;
3

4
/**
5
 * 文件上传
6
 */
7
@PostMapping("/upload")
8
public Result upload(MultipartFile file) throws Exception {
9
    log.info("文件上传:{}", file);
10
    String url = aliyunOSSOperator.upload(file.getBytes(), file.getOriginalFilename());
11
    return Result.success(url);
12
}

课程工程里的完整版本（比 PPT 多一行”上传完打日志”）：

1
@Slf4j
2
@RestController
3
public class UploadController {
4

5
    @Autowired
6
    private AliyunOSSOperator aliyunOSSOperator;
7

8
    @PostMapping("/upload")
9
    public Result upload(MultipartFile file) throws Exception {
10
        log.info("文件上传: {}", file.getOriginalFilename());
11

12
        //将文件交给OSS存储管理
13
        String url = aliyunOSSOperator.upload(file.getBytes(), file.getOriginalFilename());
14
        log.info("文件上传OSS, url: {}", url);
15

16
        return Result.success(url);
17
    }
18
}

对照上一篇的本地存储版，变化只有两处：

（课程工程的 UploadController 里，本地存储那段代码注释保留着——对照着看这两种写法非常直观。）

依赖（pom.xml）#

工具类用到的 com.aliyun.oss.* 来自阿里云官方 SDK，pom.xml 里要加：

1
<!--阿里云OSS依赖-->
2
<dependency>
3
    <groupId>com.aliyun.oss</groupId>
4
    <artifactId>aliyun-sdk-oss</artifactId>
5
    <version>3.17.4</version>
6
</dependency>
7

8
<dependency>
9
    <groupId>javax.xml.bind</groupId>
10
    <artifactId>jaxb-api</artifactId>
11
    <version>2.3.1</version>
12
</dependency>
13
<dependency>
14
    <groupId>javax.activation</groupId>
15
    <artifactId>activation</artifactId>
16
    <version>1.1.1</version>
17
</dependency>
18
<!-- no more than 2.3.3-->
19
<dependency>
20
    <groupId>org.glassfish.jaxb</groupId>
21
    <artifactId>jaxb-runtime</artifactId>
22
    <version>2.3.3</version>
23
</dependency>

第 1 种：@Value 一个属性一个属性注入#

先在 application.yml 里写上这三项（就是 72 篇里那份配置文件的末尾再追加一段，课程工程的写法）：

1
#阿里云OSS
2
aliyun:
3
  oss:
4
    endpoint: https://oss-cn-beijing.aliyuncs.com
5
    bucketName: java-ai
6
    region: cn-beijing

再在类里逐个注入：

1
@Component
2
public class AliyunOSSOperator {
3

4
    @Value("${aliyun.oss.endpoint}")
5
    private String endpoint;
6
    @Value("${aliyun.oss.bucketName}")
7
    private String bucketName;
8
    @Value("${aliyun.oss.region}")
9
    private String region;
10
}

语法就一条：@Value("${配置项的完整路径}")，路径就是 yml 里的层级用 . 连起来（aliyun → oss → endpoint，所以是 aliyun.oss.endpoint）。字段名和配置项名不需要一样（这里恰好一样）。

@Value 的问题分析（PPT 第 50 页）#

PPT 第 50 页紧跟着就是批评：

使用 @Value 注解注入配置文件的配置项，如果配置项多，注入繁琐，不便于维护管理和复用。

“繁琐”在哪、“不便复用”在哪，说具体点：

• 繁琐：有几个配置项就要写几行 @Value（10 个参数就是 10 行注解 + 10 个字段）；
• 不便维护管理：改一个配置项的名字，所有写了 @Value("${...}") 的地方都要跟着改；
• 不便复用：另一个类也想用这组参数？只能把这一整段再抄一遍（PPT 第 50 页那张图演的就是这个场景）。

第 2 种：@ConfigurationProperties 批量注入#

PPT 第 51 页给出改进方案：建一个”属性类”，把一组配置项一次性绑定到它身上。

课程资料 资料/05. 阿里云OSS/AliyunOSSProperties.java：

1
@Data
2
@Component
3
@ConfigurationProperties(prefix = "aliyun.oss")
4
public class AliyunOSSProperties {
5
    private String endpoint;
6
    private String bucketName;
7
    private String region;
8
}

三个注解各管一件事：

绑定的规则很简单：配置项路径去掉 prefix 之后剩下的那一段，和字段名对上就绑定。aliyun.oss.endpoint 去掉 aliyun.oss 剩下 endpoint，正好对上字段 endpoint；bucketName、region 同理。所以字段名必须和配置项名一致（这点和 @Value 不同）。

用的时候，谁需要这组参数就注入这个属性类：

1
@Component
2
public class AliyunOSSOperator {
3

4
    @Autowired
5
    private AliyunOSSProperties aliyunOSSProperties;
6

7
    public String upload(byte[] content, String originalFilename) throws Exception {
8
        String endpoint = aliyunOSSProperties.getEndpoint();
9
        String bucketName = aliyunOSSProperties.getBucketName();
10
        // ...（region 同理：aliyunOSSProperties.getRegion()）
11
    }
12
}

好处一眼可见：再多的配置项，都只在属性类里出现一次；别的类想用这组参数，注入 AliyunOSSProperties 就行，不用重复写注解、也不会出现”两段一样的 @Value”。

两种方式对比（PPT 第 52 页）#

PPT 第 52 页的问答，就是这两种方式的总结：

再补一张对照表，做题时对着看：

本机实测：两种方式都能注入#

1
[实测]@ConfigurationProperties 批量注入 => endpoint=https://oss-cn-beijing.aliyuncs.com , bucketName=java-ai , region=cn-beijing

一、知识回顾（读完直接做下面的实践题）#

1. 阿里云与 OSS：阿里云是阿里巴巴集团旗下全球领先的云计算公司、国内最大的云服务提供商；对象存储 OSS（Object Storage Service） 是一款海量、安全、低成本、高可靠的云存储服务，可以通过网络随时存储和调用文本、图片、音频、视频等文件
2. Bucket 与 Object：Bucket（存储空间）是存储**对象（Object，就是文件）**的容器，所有对象都必须隶属于某个存储空间；一个账号下可以建多个 bucket
3. SDK：Software Development Kit 的缩写，软件开发工具包，包括辅助软件开发的依赖（jar 包）、代码示例等
4. 第三方服务的通用思路：准备工作——注册阿里云（实名认证）→ 充值 → 开通对象存储服务（OSS）→ 创建 bucket → 获取 AccessKey（秘钥）；开发工作——参照官方 SDK 编写入门程序 → 集成使用
5. OSS 使用步骤（PPT 第 43 页的七格）：① 注册阿里云（实名认证）② 充值 ③ 开通对象存储服务（OSS）④ 创建 bucket ⑤ 获取并配置 AccessKey（秘钥）⑥ 参照官方 SDK 编写入门程序 ⑦ 案例集成 OSS；其中第 ⑥ 步 PPT 特意强调”一定要参照对应的官方文档进行开发和测试”
6. 案例集成的三个动作：① 接收上传的图片 ② 将图片存储起来（OSS）③ 返回图片访问的 URL；做法是”引入由官方示例代码改造的工具类 + 开发上传接口”，接口 POST /upload 用 multipart/form-data 收 file，响应的 data 就是文件访问路径
7. 工具类的关键点：密钥从环境变量 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET 读（不写死在代码里）；objectName = 日期目录 yyyy/MM + UUID + 原扩展名（Object 完整路径中不能包含 Bucket 名称）；putObject(bucketName, objectName, new ByteArrayInputStream(content)) 上传；finally 里 shutdown() 关客户端；最后按 协议头 + bucket名 + "." + endpoint域名 + "/" + objectName 拼出访问 URL
8. 参数写死在代码里的问题：不便维护与管理——换 bucket / 换地域要改代码重新打包上线；多处使用要到处抄；开发/测试/生产环境没法切换
9. 参数配置化的两种方式：@Value("${配置项路径}") 一个属性一个属性注入（属性少时用）；@ConfigurationProperties(prefix = "...") 批量把多个属性注入到 bean 对象中（属性多、需要复用时用，类上要配 @Component，还要有 setter——课程用 Lombok 的 @Data，字段名必须与配置项名一致）
10. 本篇的实测边界：@Value 与 @ConfigurationProperties 两种注入方式本机实测（控制台打印 endpoint=https://oss-cn-beijing.aliyuncs.com , bucketName=java-ai , region=cn-beijing）、工程编译通过实测；OSS 上传没有实测（本机没有阿里云账号与 AccessKey 环境变量），这部分按 PPT 步骤 + 课程代码讲

二、裸写题#

• 2-1 把 OSS 的三个参数改成从配置文件读（逐个注入方式） 需求：下面这个工具类里的三项参数现在写死在代码里，请把它们挪到 application.yml 里，并让类从配置文件中读到值： ① 在 yml 里以 aliyun.oss 为前缀配置 endpoint、bucketName、region 三项（值用 https://oss-cn-beijing.aliyuncs.com、java-ai、cn-beijing）； ② 改造工具类，让三个字段的值来自配置文件（一个属性一个属性地注入，注入注解写在字段上）； ③ 说明：如果以后要换 bucket，改动落在哪里？

  1
  // 现在的样子：参数写死在代码里
  2
  @Component
  3
  public class AliyunOSSOperator {
  4
      private String endpoint = "https://oss-cn-beijing.aliyuncs.com";
  5
      private String bucketName = "java-ai";
  6
      private String region = "cn-beijing";
  7
  
  8
      // ... upload 方法省略
  9
  }

  （练习文件 test_73_参数配置化.java 与 test_73_OSS配置.yml 的题目2-1 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：yml 里按”层级”写（aliyun 下面套 oss，再写三项）；Java 里每个字段上面贴一行”取配置”的注解，注解里写这个配置项的完整路径（层级用 . 连接） 二级 · 方法：yml 用 aliyun: oss: endpoint/bucketName/region；字段上用 @Value("${aliyun.oss.xxx}") 三级 · 骨架：@Value("${aliyun.oss.____}") + private String ____;

  参考答案（做完再点开）

  ① application.yml：

  1
  #阿里云OSS
  2
  aliyun:
  3
    oss:
  4
      endpoint: https://oss-cn-beijing.aliyuncs.com
  5
      bucketName: java-ai
  6
      region: cn-beijing

  ② 工具类（课程工程的写法）：

  1
  @Component
  2
  public class AliyunOSSOperator {
  3
  
  4
      @Value("${aliyun.oss.endpoint}")
  5
      private String endpoint;
  6
      @Value("${aliyun.oss.bucketName}")
  7
      private String bucketName;
  8
      @Value("${aliyun.oss.region}")
  9
      private String region;
  10
  
  11
      // ... upload 方法不变
  12
  }

  ③ 换 bucket 只改 application.yml 里的 bucketName 一行——不用动 Java 代码、不用重新编译（重启应用即可）。这正是”参数配置化”要解决的问题（PPT 第 48 页说的”写在 java 代码中不便维护与管理”）。 补充：@Value 里 ${} 中的路径必须和 yml 的层级完全对上（aliyun.oss.endpoint），写错的话启动时会报”找不到占位符”。

• 2-2 改成批量绑定方式 需求：接着上一题，把”逐个注入”换成”批量绑定”： ① 新建一个属性类，把 aliyun.oss 开头的三项配置一次性绑定到它的三个字段上（要有 setter，用 Lombok 生成即可），并交给 Spring 管理； ② 在工具类里改成注入这个属性类，用它的 getter 取三项参数； ③ 回答：为什么说这种方式”便于复用”？字段名能不能随便起？

  （练习文件 test_73_参数配置化.java 与 test_73_OSS配置.yml 的题目2-2 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：把”一组配置”看成”一个对象”——先定义这个对象（属性类），绑定靠类上的一个注解，绑定范围靠 prefix 指定；用的人注入这个对象就行 二级 · 方法：属性类上 @Data + @Component + @ConfigurationProperties(prefix = "aliyun.oss")，字段名与配置项名一致；工具类里 @Autowired private AliyunOSSProperties aliyunOSSProperties;，取值用 getEndpoint() / getBucketName() / getRegion() 三级 · 骨架：@____ @Component @____(prefix = "____") public class AliyunOSSProperties { private String ____; … }；工具类里 @Autowired private ____ aliyunOSSProperties;

  参考答案（做完再点开）

  ① 属性类（课程资料 资料/05. 阿里云OSS/AliyunOSSProperties.java）：

  1
  @Data
  2
  @Component
  3
  @ConfigurationProperties(prefix = "aliyun.oss")
  4
  public class AliyunOSSProperties {
  5
      private String endpoint;
  6
      private String bucketName;
  7
      private String region;
  8
  }

  ② 工具类：

  1
  @Component
  2
  public class AliyunOSSOperator {
  3
  
  4
      @Autowired
  5
      private AliyunOSSProperties aliyunOSSProperties;
  6
  
  7
      public String upload(byte[] content, String originalFilename) throws Exception {
  8
          String endpoint = aliyunOSSProperties.getEndpoint();
  9
          String bucketName = aliyunOSSProperties.getBucketName();
  10
          String region = aliyunOSSProperties.getRegion();
  11
          // ... 后面照旧
  12
      }
  13
  }

  ③ 便于复用：别的类也想要这组参数时，注入 AliyunOSSProperties 就行，不用把 @Value 那几行再抄一遍（PPT 第 50 页配的图就是”重复抄写”的反例）；配置项再多，也只在属性类里出现一次。字段名不能随便起：绑定是靠”去掉 prefix 后的配置项名 ↔ 字段名”对应的（endpoint 对 endpoint、bucketName 对 bucketName），名字对不上就绑不进去（值为 null）。另外别忘了 @Data——绑定依赖 setter，没有 setter Spring 写不进值。 小结一句：属性少用 @Value，属性多、要复用就用 @ConfigurationProperties（PPT 第 52 页的结论）。

• 2-3 写一个”上传文件到 OSS 并返回访问地址”的接口 需求：工程里已经有工具类 AliyunOSSOperator（含 upload(byte[] content, String originalFilename) 方法，返回文件的访问 URL）。请写一个上传接口： ① 路径 POST /upload，接收前端提交的文件； ② 把文件交给工具类上传到 OSS（工具类要上传的是字节数组和原始文件名）； ③ 把上传得到的访问地址放进统一响应结果里返回给前端； ④ 用日志记录”上传的文件名”和”上传后的 URL”各一条。 （练习文件 test_73_参数配置化.java 的题目2-3 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：接口干三件事——接住文件、把文件转成工具类要的形式传进去、把返回的地址包进 Result 里给前端 二级 · 方法：文件参数 MultipartFile；转字节数组用 file.getBytes()；原文件名用 file.getOriginalFilename()；注入工具类用 @Autowired；返回 Result.success(url) 三级 · 骨架：@PostMapping("/____") public Result upload(____ file) throws Exception { String url = aliyunOSSOperator.____(file.____(), file.____()); return Result.____(url); }

  参考答案（做完再点开）

  1
  @Slf4j
  2
  @RestController
  3
  public class UploadController {
  4
  
  5
      @Autowired
  6
      private AliyunOSSOperator aliyunOSSOperator;
  7
  
  8
      /**
  9
       * 文件上传
  10
       */
  11
      @PostMapping("/upload")
  12
      public Result upload(MultipartFile file) throws Exception {
  13
          log.info("文件上传: {}", file.getOriginalFilename());
  14
  
  15
          //将文件交给OSS存储管理
  16
          String url = aliyunOSSOperator.upload(file.getBytes(), file.getOriginalFilename());
  17
          log.info("文件上传OSS, url: {}", url);
  18
  
  19
          return Result.success(url);
  20
      }
  21
  }

  显示更多显示更少

  要点：① file.getBytes() 把上传文件转成 byte[]（工具类的方法要的就是字节数组）；② file.getOriginalFilename() 传进去是为了取扩展名（工具类用它拼 UUID + 扩展名）；③ 返回的是 Result.success(url)——按接口文档，响应的 data 就是”文件访问路径”，前端拿它去预览/存进 emp.image；④ 课程工程的 UploadController 里保留着上一篇”本地存储版”的注释代码，两版对照着看变化只有”怎么存”和”返回什么”两处。

• 2-4 分析题：两种参数配置化方式怎么选 需求：项目里现在有这些参数要配置——aliyun.oss 的三个（endpoint/bucketName/region）、数据库连接的四项（url/driver-class-name/username/password）、一个”当前环境名称”。请回答： ① 分别用哪种注入方式更合适？为什么？ ② 两种方式各自”麻烦在哪、好在哪”（各写两条）？ ③ 用批量绑定那种方式时，有三个容易踩的坑，分别是什么？ （练习文件 test_73_参数配置化.java 的题目2-4 里给了写作区。）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：判断标准只有两条——参数个数和要不要被多个类复用；再想想”改配置项名字时，哪种方式要动的地方多” 二级 · 方法：@Value 逐个注入 vs @ConfigurationProperties 批量绑定；批量绑定要注意：类上要 @Component、要有 setter（@Data）、字段名必须与配置项名一致 三级 · 骨架：少 → ____；多/复用 → @____(prefix = "____")

  参考答案（做完再点开）

  ① aliyun.oss 三项：用 @ConfigurationProperties(prefix = "aliyun.oss")——三个参数成组出现，而且工具类和别的地方都可能用到（要复用）；数据库四项：SpringBoot 的 datasource 本来就是给自动配置用的，业务代码里很少自己注入，如果非要注入，四项也算”较多”，同样适合批量绑定；“当前环境名称”这一个：用 @Value 就够（属性少，为它单独建个类反而啰嗦）。 ② 对照：

  • @Value：麻烦在配置项一多就要写一堆注解、改个配置项名字要改所有引用处；好在简单直接、一个字段一行注解，字段名还能和配置项名不一样（路径写在注解里）。
  • @ConfigurationProperties：麻烦在要多写一个属性类（还得有 @Component 与 setter），字段名必须与配置项名严格对应；好在批量绑定、一处定义多处复用、不会出现”同一段注入抄两遍”。 ③ 三个坑：① 忘了 @Component（属性类没进 Spring 容器，注入不到、绑定也不生效）；② 忘了 setter（只写 private 字段没有 @Data/setter，Spring 写不进值，字段全是 null）；③ 字段名与配置项名不一致（比如配置项叫 bucketName、字段写成 bucket，绑定不上，值还是 null）。另外 prefix 写错（如写成 aliyun）也会导致”一项都绑不上”。 结论一句话：属性较少建议 @Value；属性较多、考虑复用建议 @ConfigurationProperties（PPT 第 52 页）。

三、综合题#

• 3-1 照着”第三方服务通用思路”把 OSS 集成进 Tlias 这一题把本节串起来：准备账号与 bucket → 写入门程序 → 集成工具类与接口 → 参数配置化 → 启动验证注入。做完后你会得到一条完整的上传链路（前端选图 → 接口 → OSS → 返回 URL）。

  1. 准备（对应 PPT 第 43 页前五步）：注册阿里云并实名认证 → 充值 → 开通对象存储服务（OSS）→ 创建一个 bucket（记住名字和地域）→ 获取 AccessKey，并把它配到环境变量 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET 里（别写进代码）。把每一步的产物记在练习文件里（bucket 名、地域、endpoint 域名）；
  2. 入门程序（对应第 ⑥ 步）：新建一个最简单的类（或单元测试），照着官方 SDK 的示例把 endpoint / bucketName / region 换成自己的，上传一个本地文件，确认能拿到访问地址。回答：为什么要先单独跑一遍入门程序，而不是直接改项目？
  3. 集成工具类：在 pom.xml 里加上 aliyun-sdk-oss 与 JAXB 三件套依赖；把 AliyunOSSOperator 放进 com.itheima.utils 包，读懂它的六块逻辑（凭证、对象路径、客户端、上传、关闭、拼 URL），并在注释里用自己的话写一遍 objectName 和返回 URL 是怎么拼出来的；
  4. 参数配置化：先在 yml 里配 aliyun.oss 三项，用 @Value 逐个注入跑一次；再改成 @ConfigurationProperties 批量绑定（新建属性类）跑一次。两次都启动工程，把控制台里打印出的三项配置值抄到练习文件里，并回答 PPT 第 52 页的两个问题（两种方式分别是什么？各自适用什么场景？）；
  5. 接口开发：把 UploadController 的 POST /upload 改成”调用工具类上传并返回 URL”的版本（参考接口文档：请求 multipart/form-data 带 file，响应的 data 是文件访问路径）；
  6. 验证与回答：有阿里云账号的同学，用课程资料 资料/04. 文件上传/upload.html 或 curl -F "file=@图片路径" 真传一张图，记录返回的 URL 并用浏览器打开它；没有账号的同学（比如本机这次整理笔记时就没有），写清”哪几步没做、为什么没做”，并把已经验证过的部分记下来（本机实测：两种注入方式都能取到配置值、工程编译通过）；
  7. 收尾：把 application.yml 里你写的配置与工具类整理干净（密钥仍然只留在环境变量里），删掉入门程序的临时类与测试文件。

  涉及知识点

  知识点	在这里的应用
  第三方服务通用思路	第 1、2 步——准备账号与秘钥，先写入门程序跑通
  Bucket / Object / endpoint / region	第 1、3 步——bucket 名与地域要对应上 endpoint
  工具类与接口集成	第 3、5 步——AliyunOSSOperator + UploadController 返回 URL
  参数配置化两种方式	第 4 步——@Value 逐个注入与 @ConfigurationProperties 批量绑定各跑一遍（本机实测注入成功）
  验证边界	第 6 步——实测的写实测、没条件的如实说明（OSS 上传本身本机没跑）

  提示（先自己想，实在想不出再点开）

  一级 · 思路：这条链路的顺序不能颠倒——先有 bucket 和密钥，才有入门程序；先跑通入门程序，才好往项目里搬；参数配置化那一步只是把工具类里写死的三个字符串换成”从配置文件读” 二级 · 方法：准备阶段用阿里云控制台；入门程序与工具类都用官方 SDK（OSSClientBuilder / putObject）；配置注入用 @Value("${aliyun.oss.xxx}") 或 @ConfigurationProperties(prefix = "aliyun.oss") + @Data + @Component；接口用 MultipartFile + file.getBytes() + Result.success(url) 三级 · 骨架：aliyun: oss: endpoint/bucketName/region；@____(prefix = "aliyun.oss") public class AliyunOSSProperties { private String ____; }；String url = aliyunOSSOperator.upload(file.____(), file.____());

  参考答案（做完再点开）

  1. 准备阶段的产物（示例，填你自己的）：bucket 名 java-ai、地域 cn-beijing、endpoint https://oss-cn-beijing.aliyuncs.com、AccessKey 已配到环境变量 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET。 2. 为什么先写入门程序：第三方服务最容易错的是参数与密钥，在几十行的小程序里调通比在项目里翻日志快；PPT 第 42 页把”参照官方 SDK 编写入门程序”和”集成使用”分成两格就是这个意思，第 44 页还特意强调”一定要参照对应的官方文档进行开发和测试”。 3. 工具类的两个拼法（用自己的话写）：

  • objectName：LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM")) 得到日期目录（如 2026/09），加上 UUID.randomUUID() + 原扩展名 得到不重复的文件名，两者用 / 连起来；Object 完整路径中不能包含 Bucket 名称；
  • 访问 URL：endpoint.split("//")[0] 是协议头（https:）、endpoint.split("//")[1] 是域名（oss-cn-beijing.aliyuncs.com），拼成 协议头 + "//" + bucketName + "." + 域名 + "/" + objectName → https://java-ai.oss-cn-beijing.aliyuncs.com/2026/09/xxx.png。 4. 两种配置化方式：

  1
  // 方式一：@Value 逐个注入
  2
  @Value("${aliyun.oss.endpoint}")
  3
  private String endpoint;
  4
  @Value("${aliyun.oss.bucketName}")
  5
  private String bucketName;
  6
  @Value("${aliyun.oss.region}")
  7
  private String region;
  8
  
  9
  // 方式二：@ConfigurationProperties 批量绑定（属性类）
  10
  @Data
  11
  @Component
  12
  @ConfigurationProperties(prefix = "aliyun.oss")
  13
  public class AliyunOSSProperties {
  14
      private String endpoint;
  15
      private String bucketName;
  16
      private String region;
  17
  }
  18
  // 使用方：@Autowired private AliyunOSSProperties aliyunOSSProperties; 然后 getEndpoint() 等

  显示更多显示更少

  本机实测：批量绑定组件启动后打印 [实测]@ConfigurationProperties 批量注入 => endpoint=https://oss-cn-beijing.aliyuncs.com , bucketName=java-ai , region=cn-beijing；@Value 注入的写法工程也能正常启动（两项都取到了值）。PPT 第 52 页的问答：两种方式——@Value 一个属性一个属性地注入、@ConfigurationProperties 批量将多个属性注入到 bean 对象中；适用场景——属性较少建议 @Value，属性较多、考虑复用建议 @ConfigurationProperties。 5. 接口：

  1
  @PostMapping("/upload")
  2
  public Result upload(MultipartFile file) throws Exception {
  3
      log.info("文件上传: {}", file.getOriginalFilename());
  4
      String url = aliyunOSSOperator.upload(file.getBytes(), file.getOriginalFilename());
  5
      log.info("文件上传OSS, url: {}", url);
  6
      return Result.success(url);
  7
  }

  6. 验证：有账号的同学这里应该能拿到形如 https://<bucket>.<endpoint域名>/2026/09/<uuid>.png 的地址并直接在浏览器打开。本机整理笔记时没有阿里云账号与 AccessKey，所以”OSS 上传”没有实测——本机实测过的只有：① @Value / @ConfigurationProperties 两种注入都能取到三项配置的值；② aliyun-sdk-oss 3.17.4 + jaxb-api / activation / jaxb-runtime 依赖齐全、工程能编译通过。把这两条和你自己做到的步骤分开写，才算把”验证边界”交代清楚。 7. 收尾：application.yml 里只留 aliyun.oss 三项配置，工具类与接口保持课程代码的写法，临时类删掉——密钥始终只存在环境变量里。