从零搭建Spring Boot项目骨架：UNK20 Day1实战复盘

各位开发者朋友，大家好。

最近在复盘一个很有意思的技术训练营项目“UNK20”，它的 Day1 课程是由 Simon Patterson 主讲的第七期内容（编号 VII）。这里先解释一下背景：UNK20 是一个偏实战的集中式学习项目，特点是节奏快、任务重、当天内容必须当天消化。而 Day1 往往决定整个训练营的体验，因为它要解决一个最核心的问题：如何在最短时间内，把一个空白项目变成一套可运行、可扩展、可维护的工程骨架。

很多自学 Java 或 Spring Boot 的朋友都有类似经历：看教程时每一步都懂，但合上教程自己从零建项目，却不知道该先建哪个文件、依赖怎么配、代码放哪里、启动报错怎么排查。Simon Patterson 在 Day1 中强调了一个观点：“先让代码跑起来，再让它变好。”这句话听起来朴素，但恰恰是很多初学者和中级开发者最容易忽略的。

本文将围绕 UNK20 Day1 的实战思路，完整还原一次从零搭建可运行项目的过程，包括环境准备、依赖管理、核心代码编写、测试验证、常见报错排查以及工程规范建议。无论你是刚接触后端开发的学生，还是工作中需要快速搭建项目骨架的工程师，这篇文章都能给你一套可以直接照做的方案。

1. 为什么 Day1 必须先解决“项目骨架”

1.1 什么是项目骨架

项目骨架，简单说就是“一个项目最开始的那套基础结构”。它包含：

• 统一的目录分层；
• 构建工具与依赖描述文件；
• 应用入口类；
• 基础配置（端口、日志、环境标识等）；
• 健康检查或示例接口；
• 测试目录与基础测试用例。

很多初学者觉得项目骨架不重要，认为“代码能跑就行”。但在训练营场景里，项目骨架直接决定了后续几天你写功能时是否顺手。如果骨架乱，每加一个功能都要调整目录、改配置、处理依赖冲突，一天下来大部分时间都耗在“环境问题”上，而不是真正的业务逻辑。

1.2 Simon Patterson 在 Day1 强调的核心思路

Simon Patterson 在 Day1 的讲解中，把第一天拆成了三个阶段：

1. 最小可运行：先不追求完美设计，只要项目能启动、能访问、能测试。
2. 结构规范化：在能运行的基础上，按照工程标准调整目录和命名。
3. 自动化验证：引入测试与静态检查，让项目从“能跑”变成“可靠”。

这三步对应三种心态：初学者心态、工程师心态、质量意识。Day1 的重点不是把每一步做到极致，而是让你在一天内同时体验这三种心态。

1.3 为什么推荐 Java + Spring Boot 作为实践载体

UNK20 Day1 使用的是 Java 与 Spring Boot 技术栈，原因很实际：

• Java 在企业级后端中主流且稳定，资料多、生态成熟；
• Spring Boot 的“约定优于配置”特性非常适合快速搭建骨架；
• Maven/Gradle 的依赖管理能帮助学员建立工程化思维；
• 由于 Spring Boot 内置 Tomcat，运行体验贴近真实线上服务。

本文的示例也以这套技术栈为主，但强调一点：思路是通用的。即使你用的是 Python FastAPI、Go Gin 或其他框架，骨架设计的核心逻辑仍然一致。

2. 环境准备与版本说明

在开始写代码之前，必须先把环境准备好。训练营第一天最容易翻车的就是环境不一致。这里我整理了一套相对稳妥的配置思路。

2.1 环境清单

以下是本文示例使用的环境，读者需要根据自己机器的实际情况调整：

版本需要根据你的项目实际情况调整，本文示例以常见环境为例，重点演示配置思路。

如果你本机还没有 JDK，可以通过命令行检查：

java -version mvn -version

如果命令不存在，需要先安装 JDK 和 Maven。Windows 用户配置环境变量时注意JAVA_HOME要指向 JDK 安装目录，而不是jre目录。

2.2 推荐的项目目录结构

项目骨架的核心之一是目录结构。下面是本文后续实战案例中使用的结构：

unK20-day1-demo ├── pom.xml ├── src │ ├── main │ │ ├── java │ │ │ └── com │ │ │ └── unk20 │ │ │ └── day1 │ │ │ ├── Unk20Day1Application.java │ │ │ ├── controller │ │ │ │ └── HelloController.java │ │ │ ├── service │ │ │ │ └── GreetingService.java │ │ │ └── model │ │ │ └── Greeting.java │ │ └── resources │ │ └── application.yml │ └── test │ └── java │ └── com │ └── unk20 │ └── day1 │ └── Unk20Day1ApplicationTests.java

这个结构看起来很普通，但它体现了两个原则：

• 按职责分包：controller负责接口层，service负责业务逻辑，model负责数据模型。后续加功能时，你知道代码该往哪里放。
• 主类放在根包下：Unk20Day1Application.java放在com.unk20.day1，这样 Spring Boot 的组件扫描默认范围正好覆盖整个项目。

3. 从零创建项目：核心步骤拆解

3.1 创建 Maven 项目

在 IDEA 中可以选择 Spring Initializr 创建项目，也可以手动创建 Maven 项目。手动创建能让你更清楚每一个文件的作用，所以这里推荐手动方式。

首先创建一个空的 Maven 项目，在pom.xml中引入 Spring Boot 依赖。

文件路径：pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.18</version> <relativePath/> </parent> <groupId>com.unk20</groupId> <artifactId>unk20-day1-demo</artifactId> <version>1.0.0</version> <name>unk20-day1-demo</name> <description>UNK20 Day1 Demo Project</description> <properties> <java.version>8</java.version> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>

这里引入的spring-boot-starter-web已经包含了内嵌 Tomcat、Spring MVC 和 Jackson 等基础依赖。也就是说，只要引入这一个 starter，我们就能启动一个 Web 应用。

spring-boot-starter-test是测试专用依赖，会在后续编写单元测试时用到。注意它的 scope 是test，不会打入最终的生产包。

3.2 编写应用入口类

Spring Boot 应用需要一个入口类，也就是带有main方法的类。

文件路径：src/main/java/com/unk20/day1/Unk20Day1Application.java

package com.unk20.day1; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class Unk20Day1Application { public static void main(String[] args) { SpringApplication.run(Unk20Day1Application.class, args); } }

@SpringBootApplication是一个组合注解，它等价于：

• @SpringBootConfiguration：标识这是一个 Spring Boot 配置类；
• @EnableAutoConfiguration：开启 Spring Boot 的自动配置；
• @ComponentScan：默认扫描当前包及其子包下的组件。

把入口类放在根包下，是为了让组件扫描不出问题。这是新手最容易犯的错误之一：主类放在com.unk20下，而 Controller 放在com.unk20.day1.controller下，结果导致 Controller 扫描不到。

3.3 添加基础配置文件

Spring Boot 支持application.properties和application.yml两种格式。本文使用application.yml，因为它的层级结构更清晰。

文件路径：src/main/resources/application.yml

server: port: 8080 spring: application: name: unk20-day1-demo logging: level: root: info com.unk20.day1: debug

上面的配置做了三件事：

1. 指定服务端口为8080。如果你本机端口被占用，可以改成8081等。
2. 指定应用名称为unk20-day1-demo。这个名称在日志和后续服务注册时会用到。
3. 配置日志级别。com.unk20.day1下的日志输出debug级别，方便开发时调试。

这里需要注意的是：spring.application.name不是必填项，但建议从一开始就写上。后续接入 Nacos、Consul、Apollo 等配置中心或注册中心时，这个名字会成为服务标识。

3.4 编写领域模型类

按照三层架构的习惯，我们先定义一个简单的模型类。

文件路径：src/main/java/com/unk20/day1/model/Greeting.java

package com.unk20.day1.model; public class Greeting { private String message; private String author; public Greeting() { } public Greeting(String message, String author) { this.message = message; this.author = author; } public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } public String getAuthor() { return author; } public void setAuthor(String author) { this.author = author; } }

这个类有两个字段：message和author。它会被 Jackson 自动序列化为 JSON 返回给前端。

注意：必须保留无参构造函数。虽然这里没写序列化框架代码，但 Jackson 等工具在反序列化时通常需要无参构造。有了它，后续扩展 POST 接口时会省掉很多麻烦。

3.5 编写 Service 层

Service 层承载业务逻辑。Day1 中我们不写复杂逻辑，只负责生成问候语。

文件路径：src/main/java/com/unk20/day1/service/GreetingService.java

package com.unk20.day1.service; import com.unk20.day1.model.Greeting; import org.springframework.stereotype.Service; @Service public class GreetingService { public Greeting getGreeting(String name) { String defaultName = (name == null || name.trim().isEmpty()) ? "UNK20" : name.trim(); String message = "Hello, " + defaultName + "! Welcome to UNK20 Day1."; return new Greeting(message, "Simon Patterson"); } }

这里有几个设计细节：

• 使用@Service注解将该类交给 Spring 容器管理。
• 对入参做了空值处理。如果调用方没有传name，就使用默认值UNK20，避免接口因入参为null出现不可预期行为。
• 返回的是Greeting对象，而不是直接返回字符串。这为后续接口扩展提供空间，比如增加时间戳、状态码等字段。

3.6 编写 Controller 层

Controller 暴露 HTTP 接口。

文件路径：src/main/java/com/unk20/day1/controller/HelloController.java

package com.unk20.day1.controller; import com.unk20.day1.model.Greeting; import com.unk20.day1.service.GreetingService; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { private final GreetingService greetingService; public HelloController(GreetingService greetingService) { this.greetingService = greetingService; } @GetMapping("/hello") public Greeting hello(@RequestParam(value = "name", required = false) String name) { return greetingService.getGreeting(name); } }

@RestController表示这是一个返回数据而非视图的控制器。@GetMapping("/hello")将 HTTP GET 请求映射到hello方法。

这里使用的是构造器注入，而不是@Autowired字段注入。构造器注入更推荐，原因有几点：

• 依赖关系显式化，创建对象时就能确定依赖；
• 方便写单元测试，可以直接传入 mock 对象；
• 避免字段注入在某些场景下导致的空指针问题。

3.7 运行项目

到这里，一个最小可运行项目已经完成了。在命令行项目根目录执行：

mvn spring-boot:run

如果使用 IDEA，也可以直接运行Unk20Day1Application主类。

启动成功后，日志中会出现类似下面的输出：

Tomcat started on port(s): 8080 (http) Started Unk20Day1Application in 2.5 seconds (JVM running for 3.1)

然后在浏览器访问：

http://localhost:8080/hello?name=CSDN

预期返回 JSON：

{ "message": "Hello, CSDN! Welcome to UNK20 Day1.", "author": "Simon Patterson" }

到这里，我们已经完成了 Day1 的第一阶段目标：让项目跑起来。

4. 加入自动化测试：让项目从“能跑”变成“可靠”

Simon Patterson 在 Day1 中反复强调，只做到“能跑”是不够的。一个工程化的项目，必须有自动化测试作为保障。测试的作用不是给自己看的，而是为了将来修改代码时不至于“改一处崩一片”。

4.1 编写单元测试

我们为GreetingService编写一个简单的单元测试。单元测试只关注单个类的逻辑，不启动 Spring 容器，所以速度很快。

文件路径：src/test/java/com/unk20/day1/service/GreetingServiceTest.java

package com.unk20.day1.service; import com.unk20.day1.model.Greeting; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class GreetingServiceTest { private final GreetingService greetingService = new GreetingService(); @Test void shouldReturnDefaultNameWhenNameIsBlank() { Greeting greeting = greetingService.getGreeting(null); assertEquals("UNK20", greeting.getMessage().contains("UNK20") ? "UNK20" : "FAIL"); } @Test void shouldReturnCustomNameWhenNameIsProvided() { Greeting greeting = greetingService.getGreeting("Java"); assertTrue(greeting.getMessage().contains("Java")); } }

上面的测试有两个用例：

• 当name为空时，返回的消息包含默认值UNK20；
• 当name为Java时，返回的消息包含Java。

如果你使用的是 Spring Boot 2.7.x，spring-boot-starter-test会默认引入 JUnit 5（Jupiter），所以可以直接使用org.junit.jupiter.api.Test注解。

运行测试命令：

mvn test

预期输出中会有类似：

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

4.2 编写 Web 层集成测试

单元测试之外，我们还可以写一个“启动容器但使用 Mock 环境”的集成测试，验证 HTTP 接口是否正常响应。Spring Boot 提供了@SpringBootTest和MockMvc来支持这种测试。

文件路径：src/test/java/com/unk20/day1/controller/HelloControllerTest.java

package com.unk20.day1.controller; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.web.servlet.MockMvc; import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; @SpringBootTest @AutoConfigureMockMvc class HelloControllerTest { @Autowired private MockMvc mockMvc; @Test void shouldReturnGreeting() throws Exception { mockMvc.perform(get("/hello").param("name", "CSDN")) .andExpect(status().isOk()) .andExpect(jsonPath("$.message").value("Hello, CSDN! Welcome to UNK20 Day1.")) .andExpect(jsonPath("$.author").value("Simon Patterson")); } }

这个测试的作用是：启动完整的 Spring 应用上下文，但使用 Mock 的 HTTP 环境发起请求，不需要真实占用8080端口。

jsonPath("$.message")表示从 JSON 响应中取message字段。如果你第一次看到这种写法，可以理解为“把 JSON 当作一棵树，用路径去取值”。

5. 项目体积膨胀后：如何配置分层与统一返回结构

基础骨架跑通以后，UNK20 Day1 花了一些时间讲解“接下来的几天你一定会遇到的扩展问题”。其中最典型的就是：当接口变多，每个接口返回格式如果不统一，前端对接会非常痛苦。

所以这里提前引入一个统一响应结构。这是一个非常实用的工程实践，建议在项目初期就落实。

5.1 定义统一响应类

文件路径：src/main/java/com/unk20/day1/model/ApiResponse.java

package com.unk20.day1.model; public class ApiResponse<T> { private int code; private String message; private T data; public ApiResponse() { } public ApiResponse(int code, String message, T data) { this.code = code; this.message = message; this.data = data; } public static <T> ApiResponse<T> success(T data) { return new ApiResponse<>(200, "success", data); } public static <T> ApiResponse<T> error(int code, String message) { return new ApiResponse<>(code, message, null); } public int getCode() { return code; } public void setCode(int code) { this.code = code; } public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } public T getData() { return data; } public void setData(T data) { this.data = data; } }

这个类使用了 Java 泛型，T代表任意数据类型。success和error两个静态方法让调用方写起来更简洁。

5.2 改造 Controller

改造HelloController，让它返回统一响应结构。

package com.unk20.day1.controller; import com.unk20.day1.model.ApiResponse; import com.unk20.day1.model.Greeting; import com.unk20.day1.service.GreetingService; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { private final GreetingService greetingService; public HelloController(GreetingService greetingService) { this.greetingService = greetingService; } @GetMapping("/hello") public ApiResponse<Greeting> hello(@RequestParam(value = "name", required = false) String name) { return ApiResponse.success(greetingService.getGreeting(name)); } }

此时再次启动项目并访问：

http://localhost:8080/hello?name=SpringBoot

返回结果变为：

{ "code": 200, "message": "success", "data": { "message": "Hello, SpringBoot! Welcome to UNK20 Day1.", "author": "Simon Patterson" } }

前端拿到这个结构后，不管后端的data是对象还是数组，都能按统一的规则处理。这也是 Simon Patterson 强调的“先定义规则，再实现功能”在工程上的体现。

6. 常见问题与排查思路

在 UNK20 Day1 的实操作业中，学员遇到的大多数问题都集中在环境、依赖和启动异常上。下面整理一份高频问题清单，供大家对照排查。

6.1 典型问题：Maven 依赖下载失败

很多新手在第一次mvn spring-boot:run时卡在依赖下载环节，日志中经常出现红色的ERROR或超时提示。解决办法通常是更换 Maven 镜像源。

在settings.xml中添加阿里云镜像：

<mirror> <id>alimaven</id> <name>aliyun maven</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror>

修改后重新执行mvn clean compile，依赖下载速度会有明显提升。

6.2 典型问题：接口返回 404

如果项目启动成功，但访问/hello返回 404 或 Whitelabel Error Page，大概率是 Controller 没有被扫描到。

排查顺序：

1. 确认HelloController上是否有@RestController注解；
2. 确认主类是否在包的根路径上；
3. 确认主类上是否有@SpringBootApplication注解；
4. 确认访问路径和方法上的@GetMapping路径一致。

这里最容易被忽略的是第 2 点：主类放在com.unk20包下，Controller 放在com.unk20.day1.controller包下，默认扫描范围只覆盖com.unk20的当前包及子包，所以com.unk20.day1.controller其实是在扫描范围内的。反过来说，如果 Controller 放在com.otherpackage下，就会扫描不到。

6.3 典型问题：Tomcat 端口被占用

Windows 下查看端口占用：

netstat -ano | findstr 8080

macOS / Linux 下查看端口占用：

lsof -i :8080

找到占用进程的 PID 后，确认进程类型再决定是否结束。如果是无关程序占用，可以修改端口号继续开发，不建议强制结束系统关键进程。

7. 工程化建议与最佳实践

UNK20 Day1 的内容虽然只是一个入门骨架，但已经涉及了很多工程化思维。这里把 Simon Patterson 在课程中强调的一些原则，结合我自己的开发经验，整理成几条建议。

7.1 命名规范从第一天就开始

很多人觉得“命名”是很虚的东西，等代码写多了再改。实际上，命名是项目可维护性的第一道防线。

• 包名统一小写，例如com.unk20.day1.controller；
• 类名使用大驼峰，例如HelloController；
• 方法名使用小驼峰，例如getGreeting；
• 常量使用全大写加下划线，例如MAX_RETRY_COUNT；
• 避免使用a、b、temp、data1这类无意义命名。

统一命名规范后，团队协作时不需要花时间猜测别人的代码意图。

7.2 使用构造器注入，而不是字段注入

Spring 开发中，依赖注入有三种常见方式：字段注入、Setter 注入、构造器注入。

字段注入写起来最简洁：

@Autowired private GreetingService greetingService;

但这种方式有两个问题：

• 依赖关系不直观，类与类之间的关系隐藏在字段里；
• 单元测试时需要依赖 Spring 容器，或者用反射修改私有字段，增加了测试成本。

构造器注入在 Spring 4.3+ 中，如果类只有一个构造器，甚至可以省略@Autowired注解。代码更干净，也方便测试。

7.3 配置信息不要硬编码

在application.yml中集中管理配置是基础工程素养。实际项目中，下面这些信息都不应该硬编码在 Java 代码里：

• 数据库连接地址；
• Redis 地址与密码；
• 第三方服务的 API Key；
• 业务开关与阈值参数；
• 文件存储路径。

正确的做法是先放到application.yml，然后使用@ConfigurationProperties或@Value注入到类中。更进一步，可以使用 Apollo 或 Nacos 这类配置中心实现动态调整。

7.4 日志策略：先打印关键链路，再优化性能

在 Day1 结束时，Simon Patterson 给学员留了一个思考题：“你的服务出问题时，你靠什么定位？”答案通常是日志。

建议在项目初期就引入统一的日志规范：

• 使用 SLF4J 门面记录日志，而不是System.out.println；
• 在入口方法、调用第三方接口、异常捕获处打印关键日志；
• 日志中输出请求参数和耗时，但不要输出密码、token 等敏感信息；
• 使用logger.debug输出调试信息，使用logger.warn输出可恢复的异常，使用logger.error输出严重错误。

示例：

private static final Logger logger = LoggerFactory.getLogger(HelloController.class); @GetMapping("/hello") public ApiResponse<Greeting> hello(@RequestParam(value = "name", required = false) String name) { long start = System.currentTimeMillis(); ApiResponse<Greeting> response = ApiResponse.success(greetingService.getGreeting(name)); logger.info("hello接口耗时: {} ms, name={}", System.currentTimeMillis() - start, name); return response; }

7.5 尽早引入检查工具

正规项目一般会集成 Checkstyle、SpotBugs 或 SonarQube 做代码质量检查。Day1 中不要求配置完整检查流程，但至少可以做到：

• 在 IDEA 中安装 Checkstyle 插件；
• 使用统一的代码格式化配置；
• 提交代码前运行mvn test确保测试通过。

如果团队开发，建议在 Git 提交前配置 pre-commit 钩子或 CI 流水线，让每个提交都经过自动化检查。

8. 总结与后续学习建议

UNK20 Day1 的核心目标不是教会你某一个 API 的用法，而是帮助你建立一套“让项目从零开始健康生长”的方法。回顾一下本文的内容：

• 了解了项目骨架的含义与重要性；
• 从零搭建了一个 Spring Boot 最小可运行项目；
• 划分了 controller、service、model 三层的目录结构；
• 编写了单元测试与 Web 集成测试；
• 引入了统一响应结构，为后续多接口开发打好基础；
• 整理了常见启动报错的排查方式；
• 总结了命名、注入、配置、日志等工程规范。

这些内容虽然以 Spring Boot 为例，但背后的思路可以迁移到任何后端技术栈。

Day1 之后，比较推荐的进阶方向是：

1. 深挖 Spring Boot 自动配置原理：为什么引入一个 starter 就能拥有完整 Web 能力？spring.factories和AutoConfiguration.imports是怎么生效的？
2. 掌握统一异常处理：在@RestControllerAdvice中定义全局异常处理器，把业务异常和系统异常转换成统一的响应结构。
3. 了解配置中心与分布式环境：把application.yml中的配置迁移到 Apollo 或 Nacos，体验配置灰度发布与动态刷新。
4. 数据库操作：在骨架基础上引入 MyBatis-Plus 或 Spring Data JPA，把接口数据持久化到 MySQL 中，并思考事务与连接池配置。
5. 项目瘦身与性能优化：学习 Maven 依赖分析，排除冗余依赖，理解spring-boot-maven-plugin的打包原理。

如果你按照本文的步骤成功让第一个接口返回了 JSON，那么恭喜你，UNK20 最重要的一天已经平稳落地了。接下来的每一天，都会在这个骨架的基础上继续加新东西，请一定确保你的项目结构和依赖保持整洁。

学习完 Day1 后，建议手动删掉项目重新建一次，不参考任何笔记，看看自己能否独立完成从创建项目到接口访问全流程。这个过程能帮你把“看完”变成“会做”。如果遇到任何问题，欢迎在评论区留言讨论。