当前位置：首页 > news >正文

Spring Boot 3与Kotlin构建现代博客系统：DDD架构与AI辅助开发实践

news 2026/5/7 6:24:47

1. 项目概述：一个由AI驱动的现代博客系统

最近在折腾一个个人博客项目，想找一个既能练手Kotlin和Spring Boot，又能体现现代开发范式的完整案例。在GitHub上翻了一圈，最终锁定了doljae/vibe-coding这个仓库。这不仅仅是一个简单的“增删改查”Demo，而是一个架构清晰、功能完备的博客平台，更重要的是，它的诞生过程本身就很有意思——很大程度上是借助了AI编程工具（比如Cursor）来辅助完成的。这让我这个老码农也来了兴趣，想深入看看在AI的“加持”下，一个项目的代码质量和工程实践能达到什么水平。

简单来说，Vibe Coding Blog System是一个基于Spring Boot 3和Kotlin构建的全栈博客系统。它提供了完整的博客功能，包括文章管理、图片附件、用户系统、分类、嵌套评论和点赞，同时配备了现代化的韩语Web界面和一套规范的RESTful API。但它的价值远不止于此。项目严格遵循了领域驱动设计（DDD）和整洁架构（Clean Architecture），将代码清晰地分层，这对于学习和理解如何在复杂业务中组织代码非常有帮助。无论你是想学习Kotlin+Spring Boot的现代技术栈，还是想研究DDD和整洁架构的落地实践，亦或是好奇AI辅助编程的边界在哪里，这个项目都是一个绝佳的“标本”。

接下来，我会带你从零开始，深入这个项目的每一个角落。我们不仅会把它跑起来，更会拆解它的设计思路、技术选型背后的考量，并分享我在复现和探索过程中踩过的坑、总结的技巧。你会发现，一个好的项目，其价值不仅在于功能，更在于它如何思考问题、组织代码。

2. 技术栈深度解析与选型逻辑

2.1 核心框架：为什么是Spring Boot 3 + Kotlin？

看到技术栈的第一眼，Spring Boot 3 + Kotlin的组合就让我觉得选型很“正”。这不是一个随意的选择，背后有充分的理由。

Kotlin 2.1.20：作为JVM平台上的现代语言，Kotlin的空安全、扩展函数、数据类、协程等特性，能极大提升开发效率和代码健壮性。在这个项目中，空安全特性避免了大量的NullPointerException，数据类（data class）让领域模型的定义简洁明了，而DSL风格的代码也让Gradle构建脚本和测试代码更易读。选择2.x版本而非1.x，意味着项目拥抱了Kotlin K2编译器，在编译速度和语言特性上都有更好的体验。

Spring Boot 3.5.0：这是目前Spring Boot的稳定主版本。选择3.x意味着项目基于Spring Framework 6和Jakarta EE 9+，告别了古老的javax包，全面转向jakarta。这对于一个新项目来说是明智的，避免了未来升级的麻烦。Spring Boot 3.5.0带来了更好的性能、更模块化的设计以及对GraalVM原生镜像更完善的支持（虽然本项目未使用）。它的自动配置、起步依赖和Actuator监控端点，是快速构建生产级应用的基础。

JDK 21 (Temurin)：JDK 21是当前的长期支持（LTS）版本。Temurin是Eclipse Adoptium提供的，经过TCK认证的OpenJDK发行版，社区支持好，是生产环境的可靠选择。JDK 21带来的虚拟线程（协程）等特性，虽然在本项目的同步Web应用中未直接使用，但为未来性能优化留下了空间。

这个技术栈组合，可以说是当前JVM生态中构建Web后端服务的“黄金组合”，兼顾了开发效率、运行性能、现代特性和社区生态。

2.2 架构模式：DDD与整洁架构的落地实践

这是本项目最值得深究的部分。很多教程只讲概念，而这个项目提供了一个清晰的、可运行的范例。

领域驱动设计（DDD）：项目的domain目录下，清晰地定义了Post、User、Comment、Category、Like等核心领域实体（Entity）和值对象（Value Object）。每个实体都有其唯一标识（ID）和内在的业务规则。例如，Post实体包含了标题、内容、作者等核心属性，并定义了与之相关的行为边界。DDD的核心“通用语言”在这里得到了体现，代码中的术语（如Post, Comment）与业务概念高度一致。

整洁架构（Clean Architecture）：项目结构完美体现了整洁架构的同心圆分层思想：

Domain层（最内层）：位于domain目录，包含纯粹的实体和定义仓储接口（Repository Interface）。它不依赖任何外部框架或库，是业务核心。
Application层（用例层）：位于application目录，包含服务类（Service）。它协调领域对象完成特定的业务用例（如“发布文章”、“添加评论”）。它依赖Domain层，但实现细节（如数据库）通过接口注入。
Infrastructure层（最外层）：位于infrastructure目录，提供技术实现。例如，InMemoryPostRepository实现了PostRepository接口，LocalFileStorageService实现了文件存储逻辑。这一层依赖框架（Spring）和具体技术。
Presentation层（接口适配层）：位于presentation目录，主要是Controller和DTO。它负责将HTTP请求转换为对Application层的调用，并将结果封装成JSON响应。它依赖Application层。

这种分层带来的最大好处是可测试性和可维护性。Domain层和Application层的业务逻辑可以完全脱离Spring容器进行单元测试。技术细节（如换数据库、换存储方式）被隔离在Infrastructure层，变更时对核心业务代码影响最小。

注意：项目中使用了“In-Memory”仓储实现，这意味着数据在应用重启后会丢失。这非常适合演示、测试和快速原型开发。在实际生产中，你需要将infrastructure/repository下的实现替换为基于JPA/Hibernate、JDBC或NoSQL客户端的版本。这种替换正是整洁架构优势的体现——你只需要修改Infrastructure层的具体实现，上层业务代码几乎无需变动。

2.3 关键依赖与工具链

除了核心框架，其他依赖的选择也体现了项目的专业性：

SpringDoc OpenAPI UI：自动生成API文档（Swagger UI）。这对于后端API项目至关重要，既方便前端开发者查阅，也便于自己测试。访问/swagger-ui/index.html即可获得交互式文档。
MockK & Kotest：Kotlin生态中首选的测试库。MockK用于模拟（Mock）依赖，语法更符合Kotlin习惯；Kotest提供了丰富多样的断言风格和属性测试等功能，比JUnit更强大。它们的组合让编写Kotlin单元测试变得愉快。
Spring Boot Actuator：提供生产就绪的特性，如健康检查（/actuator/health）、指标收集（/actuator/metrics）。这是将应用部署到云环境或进行监控的基础。
Gradle Kotlin DSL：使用Kotlin语言编写构建脚本，比传统的Groovy DSL更类型安全，IDE支持更好，代码提示和重构能力更强。

3. 从零开始：环境搭建与项目启动

3.1 开发环境准备

工欲善其事，必先利其器。要顺畅地运行和开发这个项目，你需要准备好以下环境：

JDK 21：这是硬性要求。我强烈推荐使用SDKMAN!（Mac/Linux）或直接下载安装包来管理多个JDK版本。
```
# 使用SDKMAN安装Temurin JDK 21 sdk install java 21.0.3-tem sdk use java 21.0.3-tem
```
安装后，在终端验证：
```
java -version
```
应输出包含“openjdk version “21.0.3” 2024-10-15 LTS”等信息。
IntelliJ IDEA：JetBrains出品，对Kotlin和Spring Boot的支持是“亲儿子”级别的。社区版（免费）已足够开发此项目。安装时确保勾选Kotlin和Spring Boot相关插件。
Git：用于克隆代码和版本管理。通常系统已自带或可轻松安装。

3.2 项目克隆与导入

有了环境，我们先把代码拉下来。

# 克隆项目到本地 git clone https://github.com/doljae/vibe-coding.git cd vibe-coding

接下来，用IntelliJ IDEA打开项目：

打开IDEA，选择 “Open” 或 “File -> Open”。
导航到刚才克隆的vibe-coding文件夹，选择项目根目录下的build.gradle.kts文件，点击“Open”。
IDEA会自动识别这是一个Gradle项目，并开始导入依赖。这个过程会下载所有必需的库，第一次可能需要几分钟，请耐心等待网络和索引完成。

实操心得：如果遇到依赖下载慢或失败，可以配置国内镜像。在项目根目录的gradle.properties文件（如果没有就创建）中添加：
systemProp.http.proxyHost=mirrors.aliyun.com systemProp.http.proxyPort=80 systemProp.https.proxyHost=mirrors.aliyun.com systemProp.https.proxyPort=80
或者在build.gradle.kts的repositories块中，将mavenCentral()替换为阿里云镜像maven { url = uri(“https://maven.aliyun.com/repository/public/”) }。

3.3 构建与运行

依赖导入成功后，就可以尝试构建和运行了。

方式一：使用IDEA内置功能

在IDEA右侧的Gradle工具窗口（通常靠右），展开vibe-coding -> Tasks -> application -> bootRun，双击即可运行。
或者，找到主类VibeCodingApplication.kt，点击其旁边的绿色三角运行按钮。

方式二：使用命令行（更接近生产环境）在项目根目录打开终端，执行：

# 清理并构建项目 ./gradlew clean build # 运行应用 ./gradlew bootRun

如果一切顺利，你将在控制台看到Spring Boot的启动日志，最后一行通常是Started VibeCodingApplication in X.XXX seconds。

3.4 验证与初探

应用默认运行在http://localhost:8080。

访问Web界面：打开浏览器，输入http://localhost:8080。你会看到一个韩语的欢迎页面。虽然语言是韩语，但界面布局清晰，可以直观地点击“글 목록”（文章列表）、“글 작성”（写文章）等链接进行体验。这是一个纯前端的单页应用（通过HTML/JS/CSS实现），与后端API交互。
查看API文档：访问http://localhost:8080/swagger-ui/index.html。这里是自动生成的Swagger UI界面，列出了所有REST API端点。你可以在这里直接尝试调用API，比如点击POST /api/posts，填入JSON数据，点击“Execute”来创建一篇博客文章。这是测试后端功能最快捷的方式。
检查健康状态：访问http://localhost:8080/actuator/health，会返回一个简单的JSON：{“status”: “UP”}，表示应用运行健康。

至此，你已经成功将项目运行起来了。但作为一个开发者，我们不能只满足于“跑起来”，更要理解它是如何工作的。接下来，我们将深入核心功能模块。

4. 核心功能模块拆解与实现细节

4.1 领域模型设计：实体与聚合根

一切业务逻辑的起点都是领域模型。我们来看看项目中几个核心的实体是如何设计的。

Post（文章）实体：位于domain/post/Post.kt。它是博客系统的核心聚合根（Aggregate Root）。一个Post聚合了Comment和Like，并包含了对User和Category的引用。

// 简化示意 data class Post( val id: PostId, val title: String, val content: String, val authorId: UserId, val categoryId: CategoryId?, val images: List<Image> = emptyList(), // 内嵌值对象 val createdAt: Instant, val updatedAt: Instant ) { // 领域行为：添加图片（有业务规则，如最多3张） fun addImage(image: Image): Result<Post> { ... } // 领域行为：更新内容 fun update(title: String?, content: String?): Post { ... } }

关键点：

使用值对象（PostId,UserId,Image）而非基本类型（Long,String），增强了类型安全和业务语义。
images作为值对象列表直接内嵌在Post中，体现了“文章拥有图片”的聚合关系。
业务规则（如添加图片的逻辑）被封装在实体方法内，而不是散落在服务层。

Comment（评论）实体：评论支持嵌套结构。Comment实体包含一个可空的parentCommentId字段来实现树形结构。在application/comment层的服务中，会处理这种父子关系的逻辑，比如删除父评论时对子评论的处理策略。

Like（点赞）实体：它是一个简单的记录，关联userId和postId。它的存在确保了用户不能重复点赞，也便于查询点赞数。这里的设计选择是将Like作为独立的实体/聚合，而不是在Post中简单维护一个likeCount计数器和一个likedUserIds列表。这样做的好处是查询点赞列表、实现“取消点赞”逻辑更清晰，且符合“一件事一个实体”的原则。

4.2 应用服务层：协调业务用例

领域实体定义了数据和基本规则，而应用服务（Service）则协调多个实体和仓储，完成一个完整的业务用例。以PostApplicationService为例：

// 简化示意 @Service class PostApplicationService( private val postRepository: PostRepository, private val userRepository: UserRepository, private val fileStorageService: FileStorageService ) { fun createPost(command: CreatePostCommand): Result<PostResponse> { // 1. 验证作者存在 val author = userRepository.findById(command.authorId) ?: return Failure(UserNotFound) // 2. 创建领域实体 val post = Post.create( id = PostId.generate(), title = command.title, content = command.content, authorId = author.id, categoryId = command.categoryId ) // 3. 处理图片上传（基础设施调用） command.images?.forEach { imageFile -> val storedImage = fileStorageService.store(imageFile) post.addImage(storedImage.toDomainImage()) // 调用领域行为 } // 4. 持久化 postRepository.save(post) // 5. 返回DTO return Success(post.toResponse()) } }

这个createPost方法清晰地展示了一个用例的步骤：参数校验 -> 创建实体 -> 执行业务操作（上传图片）-> 持久化 -> 返回结果。服务层不关心数据如何存储（PostRepository接口），也不关心文件具体存到哪（FileStorageService接口），它只负责业务流程的编排。这种设计让服务层的测试变得非常容易，你可以轻松地Mock掉仓储和文件服务。

4.3 基础设施层：技术细节的实现

这一层是“脏活累活”聚集地，但至关重要。

InMemoryRepository：项目为了简洁，使用了内存存储。例如InMemoryPostRepository用一个ConcurrentHashMap来存储Post对象。这在生产环境中是不可用的，但它完美地演示了仓储模式的抽象价值。当你需要换成MySQL时，只需创建一个JpaPostRepository实现相同的PostRepository接口，然后在Spring配置中替换掉Bean即可，上层的PostApplicationService一行代码都不用改。

LocalFileStorageService：负责将用户上传的图片保存到服务器本地磁盘。代码中会处理文件名冲突（使用UUID重命名）、创建存储目录、验证文件类型（MIME Type）等。这里有一个重要配置在application.yml中：

app: image: storage: path: ./uploads # 图片存储路径 max-file-size: 5MB # 单文件大小限制

你需要确保运行应用的进程对./uploads目录有读写权限。在生产环境中，你可能会将其改为云存储服务（如AWS S3、阿里云OSS）的实现。

4.4 表现层：REST API与异常处理

presentation/controller下的控制器（Controller）是系统的门面。它们非常“薄”，主要职责是：

接收HTTP请求，通过注解（@GetMapping,@PostMapping）绑定路由。
数据转换与验证，使用@Valid注解验证请求体（DTO），并将JSON映射为对象。
调用应用服务，传入命令或查询对象。
处理响应，将服务层返回的结果或异常转换为合适的HTTP状态码和JSON响应。

统一的异常处理：在presentation/exception包下，有一个GlobalExceptionHandler。它使用@ControllerAdvice注解，可以捕获整个应用中抛出的特定异常，并返回结构化的错误信息。例如，当PostApplicationService中因为找不到用户而返回Failure(UserNotFound)时，控制器可以抛出UserNotFoundException，最终被GlobalExceptionHandler捕获，返回HTTP 404状态码和{“message”: “User not found”}的JSON。这为API客户端提供了清晰、一致的错误反馈。

DTO（Data Transfer Object）的使用：控制器绝不直接接收或返回领域实体（Post,User）。而是定义专门的请求DTO（如CreatePostRequest）和响应DTO（如PostResponse）。这样做的好处是：

解耦：API的变更不会直接影响领域模型。
安全：可以隐藏领域模型中的敏感字段（如用户的密码哈希）。
定制：可以根据不同API的需求，组装不同的响应字段。

5. 前端界面解析与前后端交互

虽然项目后端是重点，但其提供的前端界面是一个完整可用的单页应用（SPA），非常适合理解前后端分离的协作模式。

5.1 前端技术栈与结构

前端没有使用React、Vue等现代框架，而是采用了最基础的HTML + CSS + 原生JavaScript，并搭配了Bootstrap 5作为UI框架。这种选择有其道理：

零构建依赖：无需npm install或webpack配置，开箱即用，与Spring Boot的静态资源服务无缝集成。
简单直接：对于这样一个以演示和API为核心的项目，轻量级的前端足以完成任务，避免复杂性喧宾夺主。
易于理解：代码直观，任何开发者都能一眼看懂交互逻辑。

前端资源存放在src/main/resources/static/目录下。这是Spring Boot的默认静态资源目录，其中的文件可以通过根路径直接访问（如/posts.html）。

5.2 核心页面与交互流程

首页 (index.html)：简单的介绍页面，提供导航链接。
文章列表页 (posts.html)：
- 加载时：页面通过fetchAPI调用GET /api/posts，获取所有文章数据。
- 渲染：使用JavaScript动态生成HTML，将文章标题、作者、摘要等信息填入表格或卡片。
- 交互：点击文章标题，会导航到post-detail.html?id=<文章ID>。
文章详情页 (post-detail.html)：
- 获取数据：从URL参数中提取文章ID，调用GET /api/posts/{id}获取详情，同时调用GET /api/posts/{postId}/comments获取评论列表。
- 渲染：展示文章全文、图片、作者、时间等信息。递归渲染嵌套的评论树。
- 交互：
  - 点赞：点击“좋아요”（喜欢）按钮，触发POST /api/posts/{id}/like，成功后更新前端计数。
  - 评论：在表单中输入内容，提交到POST /api/posts/{postId}/comments。
  - 删除评论：每条评论旁可能有删除按钮（如果当前用户是作者），调用DELETE /api/comments/{id}。
文章创建/编辑页 (post-form.html)：
- 表单：包含标题、内容、分类下拉框、图片上传（<input type=”file” multiple>）等字段。
- 提交：表单提交被JavaScript拦截，构造一个FormData对象，因为包含文件。然后通过fetch发送POST /api/posts请求。
- 图片预览：JavaScript会监听文件选择事件，在页面上预览选中的图片。

5.3 前后端数据格式约定

前后端通过JSON进行通信，格式在DTO中定义。

请求示例 (创建文章)：

POST /api/posts Content-Type: application/json { “title”: “我的第一篇博客”, “content”: “这是博客内容...”, “authorId”: 1, “categoryId”: 2 }

带图片的请求：由于包含文件，需要使用multipart/form-data格式，前端用FormData对象构建，后端用@RequestPart接收。

响应示例：

{ “id”: 123, “title”: “我的第一篇博客”, “content”: “这是博客内容...”, “author”: { “id”: 1, “displayName”: “张三” }, “category”: { “id”: 2, “name”: “技术” }, “images”: [ {“id”: “uuid1”, “url”: “/api/posts/123/images/uuid1”} ], “likeCount”: 5, “createdAt”: “2024-01-01T10:00:00Z”, “updatedAt”: “2024-01-01T10:00:00Z” }

这种清晰、一致的API设计，使得前端开发可以独立进行，后端只需保证API契约不变。

实操心得：在开发类似项目时，即使前端很简单，也建议先使用Swagger UI或Postman把后端所有API调通，定义好请求/响应格式。然后再着手前端开发，这样可以避免很多前后端联调时的低级错误。这个项目提供的api-tests/目录下的.http文件，就是非常好的API测试用例，可以直接在IDEA的HTTP Client中运行。

6. 测试策略与代码质量保障

一个严肃的项目离不开完善的测试。Vibe Coding的测试覆盖了从单元测试到集成测试的各个层次，是学习测试实践的优秀模板。

6.1 单元测试：聚焦核心逻辑

单元测试的目标是验证单个类或方法的行为，通常需要隔离外部依赖（如数据库、文件系统、网络）。

领域实体测试：位于test/kotlin/.../domain。这些测试不依赖Spring，只测试实体自身的业务规则。例如，测试Post.addImage()方法是否正确地执行了“最多添加3张图片”的规则。

@Test fun `게시글에 이미지를 3개 초과하여 추가할 수 없다`() { // Given: 一个已有3张图片的文章 val post = createPostWithImages(3) val newImage = Image(ImageId(“new-id”), “new.jpg”, “image/jpeg”) // When & Then: 添加第4张图片应该失败 val result = post.addImage(newImage) result shouldBeInstanceOf Failure::class (result as Failure).error shouldBe PostError.TooManyImages }

这里使用了Kotest的shouldBeInstanceOf等流畅断言，代码可读性很高。

应用服务测试：位于test/kotlin/.../application。测试服务类时，需要Mock掉所有的仓储和外部服务依赖。这里使用了MockK。

@Test fun `존재하지 않는 사용자로 게시글 생성 시 실패해야 한다`() { // Given: Mock仓储返回null（用户不存在） every { userRepository.findById(any()) } returns null every { postRepository.save(any()) } just Runs // 确保save不会被调用 // When: 调用服务 val result = service.createPost(createCommand) // Then: 应该返回失败 result shouldBeInstanceOf Failure::class verify(exactly = 0) { postRepository.save(any()) } // 验证save未被调用 }

every用于设定Mock行为，verify用于验证预期交互是否发生。这种测试确保了业务逻辑的纯净性。

6.2 集成测试：验证组件协作

集成测试位于test/kotlin/.../integration和test/kotlin/.../presentation。它们会启动一个接近真实的Spring应用上下文（但可能使用测试数据库或内存仓储），测试多个组件如何协同工作。

API集成测试：使用@SpringBootTest和@AutoConfigureMockMvc，测试整个HTTP层。

@SpringBootTest @AutoConfigureMockMvc class PostControllerIntegrationTest { @Autowired lateinit var mockMvc: MockMvc @Test fun `GET api-posts should return ok`() { mockMvc.perform(get(“/api/posts”)) .andExpect(status().isOk) .andExpect(jsonPath(“$”).isArray) } }

这种测试会经过完整的HTTP栈、控制器、服务层，最终到达内存仓储，是验证API契约是否正确的有力手段。

6.3 测试资源与配置

项目根目录下的api-tests/文件夹里有一系列.http文件。这是IntelliJ IDEA内置的HTTP Client的脚本文件，可以直接在IDE中运行，像调用真实API一样测试后端。例如，blog-api-tests.http里可能包含：

### Create a new post POST http://localhost:8080/api/posts Content-Type: application/json { “title”: “Test Post”, “content”: “This is a test.”, “authorId”: 1 }

点击旁边的“Run”按钮，就能发送请求并看到响应。这是契约测试和开发期快速验证的利器。

注意事项：运行测试前，请确保没有其他应用实例占用8080端口，否则集成测试可能会失败。另外，由于项目使用了内存仓储，每次测试启动都是全新的环境，测试之间是隔离的，这很好。但在测试文件上传等功能时，要注意清理测试生成的临时文件，避免污染后续测试或磁盘空间。

7. 配置、部署与监控

7.1 应用配置详解

Spring Boot的配置中心是src/main/resources/application.yml。这个文件管理着应用的所有外部化配置。

server: port: 8080 # 服务器端口 servlet: context-path: / # 应用上下文路径，可以改为 /api 等 spring: application: name: vibe-coding # 应用名称，会用于Actuator端点等 servlet: multipart: max-file-size: 10MB # HTTP multipart请求（文件上传）的最大文件大小 max-request-size: 10MB # 整个请求的最大大小 app: # 自定义配置项 image: storage: path: ./uploads # 图片存储目录 max-file-size: 5MB # 业务层限制的单图片大小

配置优先级：Spring Boot支持多种配置源（如环境变量、系统属性、命令行参数），其优先级高于application.yml。这意味着你可以在不修改代码的情况下，通过环境变量来覆盖配置。例如，在生产环境，你可以设置环境变量APP_IMAGE_STORAGE_PATH=/data/uploads来改变图片存储位置。

多环境配置：你可以创建application-dev.yml（开发环境）、application-prod.yml（生产环境）。通过启动时指定spring.profiles.active=prod来激活对应的配置。在application-prod.yml中，你可能会配置真实的数据库连接、关闭Swagger UI、调整日志级别等。

7.2 构建与打包

项目使用Gradle，打包非常简单：

./gradlew clean bootJar

这个命令会生成一个可执行的“fat JAR”文件，位于build/libs/vibe-coding-0.0.1-SNAPSHOT.jar。这个JAR包内嵌了Tomcat服务器和所有依赖，只需要JDK环境即可运行：

java -jar build/libs/vibe-coding-0.0.1-SNAPSHOT.jar

你可以通过命令行参数覆盖配置：

java -jar vibe-coding.jar --server.port=9090 --app.image.storage.path=/var/uploads

7.3 监控与运维

Spring Boot Actuator提供了生产环境所需的监控和管理端点。默认情况下，/actuator/health和/actuator/info是开放的。

健康检查 (/actuator/health)：可用于Kubernetes的存活探针（liveness probe）和就绪探针（readiness probe）。如果集成了数据库，这里还会显示数据库的连接状态。
应用信息 (/actuator/info)：可以展示应用版本、构建时间等，需要在application.yml中配置info.*属性。
指标 (/actuator/metrics)：提供JVM内存、线程、HTTP请求计数等丰富的指标，可以集成到Prometheus和Grafana中做可视化监控。
日志管理：你可以通过logging.level.com.example.vibecoding=DEBUG来动态调整特定包的日志级别，无需重启应用（需要额外配置）。

安全警告：除了/health和/info，其他Actuator端点（如/actuator/env,/actuator/loggers）可能暴露敏感信息。在生产环境中，务必通过Spring Security保护这些端点，或通过management.endpoints.web.exposure.include属性严格控制暴露的范围。

8. 常见问题排查与开发技巧

在复现和开发类似项目的过程中，你可能会遇到以下问题。这里记录了我的排查思路和解决方法。

8.1 环境与启动问题

问题1：./gradlew bootRun失败，提示 “Could not find tools.jar” 或 JDK 版本错误。

原因：系统默认的JAVA_HOME指向了错误的JDK版本（比如JDK 8或11）。
解决：
1. 确认已安装JDK 21：java -version。
2. 在项目根目录创建或修改gradle.properties文件，指定Gradle使用的JVM：org.gradle.java.home=/path/to/your/jdk21。或者，在IDEA中，进入File -> Project Structure -> Project，确保“Project SDK”和“Project language level”都设置为21。
3. 对于命令行，可以临时设置环境变量：export JAVA_HOME=/path/to/jdk21。

问题2：应用启动后，访问localhost:8080报Whitelabel Error Page。

原因：Spring Boot默认的静态资源映射可能有问题，或者你的请求路径不对。
解决：
1. 首先检查应用是否真的启动成功。查看控制台日志，确认没有异常。
2. 访问http://localhost:8080/swagger-ui/index.html，如果能打开，说明后端API是正常的。
3. 前端页面在/static目录下，直接访问http://localhost:8080/posts.html。如果还是404，检查src/main/resources/static目录下是否存在posts.html文件。
4. 检查浏览器控制台（F12）的网络请求，看是否是前端JS/CSS加载失败。

8.2 功能与API问题

问题3：上传图片失败，提示“文件大小超出限制”或“存储路径错误”。

原因：文件大小超过了Spring MVC或自定义配置的限制。
解决：
1. 检查application.yml中的两个配置：spring.servlet.multipart.max-file-size（Spring全局限制）和app.image.storage.max-file-size（业务逻辑限制）。确保它们足够大。
2. 检查app.image.storage.path配置的目录是否存在，且应用进程有读写权限。可以在启动时打印这个路径的绝对位置进行调试。
3. 在LocalFileStorageService的store方法中打上断点，查看上传流程在哪里失败。

问题4：API返回415 Unsupported Media Type。

原因：HTTP请求的Content-Type头与后端Controller期望的不匹配。
解决：
1. 对于接收JSON的POST/PUT请求，确保请求头包含Content-Type: application/json。
2. 对于文件上传（multipart/form-data），后端方法参数应使用@RequestPart注解，而不是@RequestBody。检查你的Controller方法定义。
3. 使用Swagger UI或Postman测试时，它们通常会自动设置正确的Content-Type。如果是自己写的客户端代码，请仔细检查。

问题5：内存数据在应用重启后丢失。

原因：项目默认使用了InMemoryRepository，数据存储在内存的HashMap中。
解决：这是设计使然，用于演示。要持久化数据，你需要实现基于真实数据库的Repository。这是一个很好的扩展练习：
1. 添加Spring Data JPA和H2/MySQL依赖。
2. 将领域实体加上JPA注解（@Entity,@Id等）。
3. 创建JpaPostRepository接口，继承JpaRepository<Post, PostId>和自定义的PostRepository接口。
4. 在配置类中，用@Bean注解提供一个JpaPostRepository的实例，替换掉原来的内存实现。

8.3 开发与调试技巧

技巧1：利用.http文件进行快速API测试。IDEA内置的HTTP Client非常强大。你可以在api-tests/目录下的文件里，直接点击“运行”按钮发送请求。更棒的是，你可以使用变量和环境管理。例如，在.http文件顶部定义：

### 定义变量 @baseUrl = http://localhost:8080 @postId = {{createPost.response.body.id}}

然后在请求中使用{{baseUrl}}/api/posts。IDEA会自动记录上一个请求的响应，并将postId变量替换为实际值，方便你进行一系列链式测试（创建文章 -> 获取文章 -> 评论 -> 点赞）。

技巧2：开启详细的SQL日志（当接入数据库后）。在application-dev.yml中添加：

logging: level: org.hibernate.SQL: DEBUG # 打印所有SQL语句 org.hibernate.type.descriptor.sql.BasicBinder: TRACE # 打印SQL参数值

这能帮你快速定位N+1查询问题或验证复杂的查询是否正确。

技巧3：编写“切片测试”（Slice Test）提高测试速度。对于只测试Web层或只测试JPA层的场景，可以使用Spring Boot的切片测试注解，它们比@SpringBootTest启动更快。

@WebMvcTest(PostController::class)：只加载Web MVC相关的Bean，用于测试Controller。
@DataJpaTest：只加载JPA相关的Bean，用于测试Repository。
@JsonTest：只加载JSON序列化相关的Bean，用于测试DTO的序列化/反序列化。

这个项目不仅是一个可运行的程序，更是一个精心设计的教学范例。它展示了如何用现代Java/Kotlin技术栈，结合DDD和整洁架构思想，构建一个结构清晰、易于测试和维护的应用程序。从环境搭建到核心原理，从功能实现到测试部署，我希望这篇拆解能帮助你不仅仅是“运行”它，更是“理解”和“掌握”它。当你下次需要自己设计一个服务时，不妨回想一下这个项目的结构，思考如何将业务逻辑、技术实现和代码组织进行清晰的分离。

查看全文

http://www.jsqmd.com/news/768420/