项目介绍

graceful-code-workshop（代码实战工坊）由两部分组成：主模块是一套开箱即用的 Spring Boot 3 脚手架，可以直接拉下来用作新项目起点；各类子分支则是对最佳实践与“避坑”的独立探索，配合博客文章阅读。

主模块：开箱即用的脚手架

主分支（main / dev/*）下的工程是一个完整可启动的多模块 Maven 项目，已经把日常开发中重复抄写的样板代码沉淀为通用模块，你只需替换业务包名与启动配置即可投入新项目：

模块	内置能力
`forge-api`	统一 `Result` 响应、`BusinessException` 与错误枚举骨架、通用常量
`forge-core`	`@RestControllerAdvice` 全局响应包装与异常处理
`forge-processor`	自定义注解 + 编译期校验器（如 `@MyApiResponse` / `@RawResponse` 互斥检查）
`forge-swagger`	Swagger 3 + Knife4j 4.4 接入与定制
`forge-ddl`（本站当前主文档）	注解驱动的数据库自动建表，POJO 加注解即模型
`forge-samples-*`	业务示例：API 定义层 / 服务实现层 / 启动层

使用方式：

bash

git clone <repo-url>
cd graceful-code-workshop/forge && mvn clean install
cd ../forge-samples/forge-samples-boot && mvn spring-boot:run

完整步骤与启动日志参考 → 快速开始。

子分支：最佳实践的独立探索

工坊会持续以分支形式沉淀两类内容，每个分支只验证一个主题，互不交叉，便于挑感兴趣的逐条阅读：

`dp/*` —— 设计模式实战重构

不是教科书式定义，而是把每种模式用在一个真实业务场景里：

dp/bridge-basic、dp/composite-basic、dp/decorator-basic、dp/proxy-basic、dp/facade-basic、dp/strategy-basic、dp/template-basic、dp/iterator-basic ……

`craft/*` —— 真实生产事故与避坑

把曾经踩过的坑还原成可运行代码，配合复盘文章理解“为什么不能这么写”：

锁与并发：craft/lock-misuse-four / craft/threadlocal-leak / craft/threadlocal-ghosts / craft/reentrantlock-in-practice ……
Spring 陷阱：craft/transactional-bombs / craft/aop-tx-order-bug / craft/restcontrolleradvice-traps / craft/spring-web-traps ……
Redis / IO / 数据：craft/redis-snowball-avalanche / craft/redis-triple-kill / craft/file-io-traps / craft/db-cpu100-bestpractice ……
代码规范：craft/final-defensive-coding / craft/new-wrapper-bans / craft/naming-rules / craft/best-practice-myths ……

完整分支索引（含每条对应的博客原文链接）见项目根目录 README.md。

怎么选

你的诉求	看哪里
拿一份能直接启动的脚手架做新项目	主分支 + 本文档站点
想用某个模块的能力但只用其中一两个	使用指南选模块
想理解某个模块为什么这么设计	设计文档选模块
想研究某个设计模式 / 真实事故	切到对应 `dp/` / `craft/` 分支看代码与提交日志
看到陌生的 Java / Spring 概念	前置知识

适用人群

写过 1–3 年 Spring Boot、想跳出“会用 API”的舒适区的开发者
在团队里维护脚手架、想抄一份能落地的“约定”出来
学设计模式时找不到真实业务场景的，参照 dp/* 分支的实战重构

技术栈

维度	选型
Java	JDK 17
框架	Spring Boot 3.5.4
构建	Maven
工具	Lombok
API 文档	Swagger3 + Knife4j 4.4.0
注解处理	自定义注解处理器（编译时检查）

项目结构

graceful-code-workshop/
├── forge/                  # 框架核心（脚手架的"工具箱"）
│   ├── forge-api/
│   ├── forge-core/
│   ├── forge-processor/
│   ├── forge-swagger/
│   └── forge-ddl/
├── forge-samples/                       # 业务示例聚合（脚手架的"模板项目"）
│   ├── forge-samples-api/
│   ├── forge-samples-core/
│   └── forge-samples-boot/              # 启动模块
└── forge-docs/                       # 本文档站点

下一步

想 5 分钟把整个工坊跑起来 → 快速开始
想直接接入某个模块到自己的项目 → 使用指南
想看某个模块为什么这么设计 → 设计文档

项目介绍 ​

主模块：开箱即用的脚手架 ​

子分支：最佳实践的独立探索 ​

dp/* —— 设计模式实战重构 ​

craft/* —— 真实生产事故与避坑 ​

怎么选 ​

适用人群 ​

技术栈 ​

项目结构 ​

下一步 ​