从零搭建一个SpringBoot项目需要注意什么

很多人在新建一个Spring Boot项目时第一个动作就是去start.spring.io点几下生成一个压缩包解压导入IDE然后对着教程敲代码。但等到项目真正运行起来才发现问题接踵而至依赖冲突、配置失效、数据库连接超时、打包体积巨大……这些痛苦往往源于一开始的“随意”。从零搭建不是把骨架拉下来就完事而是一次对工程根基的审视。项目从零开始的那一刻你做的每一个选择都会在半年后十倍地回报你或报复你。版本选择不是小事它决定了你的“命运”很多人直接选择最新版本认为新即好。但Spring Boot的版本迭代极快最新版往往意味着最少的资料、最容易踩坑的兼容性问题和最激进的生态迁移。选版本的本质是选生态的成熟度而不是选数字的新鲜度。比如Spring Boot 3.x强制要求Java 17而2.7.x则是2.x系列的最后一个稳定分支大量老项目沉淀的解决方案都适用。如果你在写一个新项目技术栈完全可控那么建议直接上3.x但如果你的团队对Java 8依赖极深或者要接入某些老旧的中间件SDK请老老实实选2.7.x。更关键的是版本的锁定必须贯穿所有依赖。Spring Boot的parent POM已经帮你管理了大部分依赖版本可一旦你引入了第三方库很容易出现“隐式升级”或“隐式降级”的混乱。请务必在根POM中用属性统一管理关键版本并且用mvn dependency:tree排查冲突。不要相信IDE的“自动修复”那只是掩盖问题。启动类的摆放位置是新手最易忽略的“致命陷阱”Spring Boot的自动配置全靠SpringBootApplication注解这个注解里包含了ComponentScan和EnableAutoConfiguration。它的扫描范围默认是启动类所在的包及其子包。如果你把启动类放在com.example.demo而把业务类放在com.other.service对不起Spring根本扫描不到。这听起来像个小问题但实际造成的后果是莫名其妙的NullPointerException和NoSuchBeanDefinitionException。正确的做法是包结构必须遵循“启动类在顶层其他类在子包”的原则。比如com.company.project作为根包启动类放com.company.project下其他所有类放com.company.project.controller、com.company.project.service等。不要为了美观搞出多个顶层包。另一个细节是你最好不要在启动类里写业务代码。有些人喜欢在Application类里写定时任务或者初始化数据这会让启动逻辑变得不可测试而且容易在打包后引发奇怪的类加载问题。启动类只负责启动任何初始化逻辑交给CommandLineRunner或专门配置类。依赖引入的原则宁缺毋滥按需取用Spring Boot的starter机制极大简化了依赖配置但这也带来了“随手抄”的恶习。很多项目的pom文件里躺着一堆从不使用的依赖spring-boot-starter-data-jpa、spring-boot-starter-security、spring-boot-starter-thymeleaf……每一个多余的依赖都是潜在的攻击面和构建负担。更严重的是不同的starter可能引入同一个底层库的不同版本直接导致运行时NoSuchMethodError。正确的姿势是先问自己需要什么功能再去搜索对应的starter。同时尽量使用官方提供的starter而非第三方的所谓“增强版”。官方starter经过充分测试且版本与父POM同步贵一点但放心。如果你要引入非官方依赖请在Maven仓库里确认其维护活跃度并锁定版本。另外不要忽略编译期的依赖范围。lombok是providedh2是runtimejunit是test。如果全写默认的compile最终打包的jar会无谓地膨胀。配置文件的学问别把一切塞进application.yml启动一个Spring Boot项目配置文件是你的“控制面板”。但很多人把所有的配置都堆在application.yml里导致文件动辄几百行改参数时胆战心惊。配置管理的核心原则是区分环境、区分来源、区分敏感度。首先至少要有application-dev.yml、application-prod.yml这样的多环境文件然后在主配置里用spring.profiles.active来激活。其次不应该把数据库密码、Redis密码、API密钥直接写进配置文件。Spring Boot支持环境变量注入也支持config server。在简单项目里至少要用${SOME_ENV_VAR}这样的占位符配合IDE的启动环境变量或部署平台的secret管理。第三类目清晰的配置要用自定义前缀比如myapp.order.timeout: 1000然后通过ConfigurationProperties绑定到一个POJO类。这样可以避免到处用Value散落魔法值。最后配置文件的编码必须统一为UTF-8否则中文注释或某些特殊字符可能导致启动直失败。日志体系别让System.out在凌晨三点刺痛你的眼新手最爱用System.out.println()打印调试信息这在本地跑通阶段没问题但一旦上了生产你的唯一救命稻草就是日志。Spring Boot默认使用SLF4J Logback你必须从一开始就养成用Logger的习惯。在类中声明private static final Logger log LoggerFactory.getLogger(Xxx.class)或者用Lombok的Slf4j注解后者更简洁。但要注意Lombok对日志的支持依赖运行时日志实现如果你用了log4j2需要额外注意适配。日志配置上至少要做到按天滚动、保留30天、单个文件大小限制、以及不同级别的日志输出到不同文件或者控制台和文件分开。这些在logback-spring.xml中配置spring的profile可以让你在dev环境只输出INFO到控制台而在prod环境输出ERROR到文件。另外日志不能记录敏感信息比如密码、身份证号、支付凭证。这不仅是安全性问题也是法律合规问题。数据访问层的选择JPA还是MyBatis这不是偏好问题Spring Boot对数据访问提供了多套方案。spring-boot-starter-data-jpa封装了Hibernate崇尚“面向对象”但很多中国开发者对MyBatis情有独钟因为SQL可控且灵活。选择数据持久层的标准不是你熟悉哪个而是你的团队规模、项目复杂度和数据库特点。如果项目有大量复杂的多表关联查询、报表统计MyBatis的XML可以在SQL层面精细优化。如果项目以CRUD为主实体关系清晰JPA能极大减少样板代码。但无论选哪个都要配置好数据库连接池。Spring Boot默认使用HikariCP这是目前性能最好的连接池但你得设置恰当的参数如maximum-pool-size、connection-timeout、minimum-idle否则默认值在并发场景下会拖垮你。另一个大坑是数据库方言和事务管理。使用JPA时实体类映射的驼峰命名字段与数据库的下划线命名冲突你需要在配置里开启spring.jpa.hibernate.naming.physical-strategy的正确策略。而事务务必在Service层使用Transactional不要放在Controller层同时要理解readOnly和rollbackFor的用法。异常处理前端收到的应该是有意义的消息而不是白屏Spring Boot的默认错误页面在前后端分离的场景下几乎不可用。你需要一个全局的异常处理器用RestControllerAdvice拦截异常并统一返回格式。很多项目把异常处理放在Controller里try-catch每段代码都重复这非常糟糕。全局异常处理器的核心是区分业务异常和系统异常。业务异常如参数校验失败、用户不存在应该给出友好的提示信息HTTP状态码可以设为200或400系统异常如数据库宕机、空指针则应该仅返回“服务器开小差了”而详细堆栈只记录在日志中。另外不要直接向外暴露内部异常类名和堆栈那简直是在给黑客递刀。对于参数校验Spring Boot支持Bean Validation你可以在DTO字段上加NotNull、Size然后在Controller参数前加Validated异常处理会自动收集错误消息。测试从零搭建时就要植入测试基因很多人觉得测试是“以后有时间再补”但没有测试的项目每次改动都是对未知风险的赌博。Spring Boot的测试支持非常完善你应该在骨架建立时就加入测试依赖并至少写几个冒烟测试确保能跑通上下文加载。这里要注意的是测试类必须和主启动类在同一个包或子包下否则SpringBootTest找不到应用配置。对于数据库依赖可以用H2内存数据库或测试容器但不要在生产配置的环境变量里跑测试以免污染真实数据。另外测试不能只测“正常逻辑”要测边界值和异常分支。比如分页参数为负数、用户ID不存在、并发重复提交等。这些测试用例一开始可能觉得浪费时间但在你重构代码时会救你命。打包与部署可执行jar不只是双击运行那么简单当你在IDE里点击Run成功启动后问题才刚开始。生产环境需要部署你需要了解Spring Boot的打包过程。Spring Boot的Maven插件spring-boot-maven-plugin的repackage目标是关键它会把项目打包成一个可执行的fat jar内含所有依赖。但注意这个jar并不适合作为依赖被其他模块引用所以如果你的项目是多模块结构需要额外配置classifier。还有fat jar体积很大你需要考虑是否需要分离依赖和业务代码比如使用COPY到Docker镜像的多个分层以利用缓存。对于Docker部署你需要一个合适的Dockerfile。首先基础镜像要选择包含对应JRE版本的eclipse-temurin这类官方镜像不要用带JDK的镜像来节省空间。其次在Dockerfile中设置合理的JVM参数如-Xms、-Xmx、-XX:MetaspaceSize以及-Djava.security.egdfile:/dev/./urandom加速启动随机数生成。最后健康检查机制必不可少。在Spring Boot 2.3以上可以引入spring-boot-starter-actuator并开启health端点Dockerfile添加HEALTHCHECK指令这样编排系统才能知道你的应用是否真的“活”着。别忘了那些“空气类”基础设施Actuator、优雅停机与配置热更新一个健壮的项目除了业务代码还必须有可观测性。Spring Boot Actuator是生产环境的照妖镜它提供了/actuator/health、/actuator/metrics、/actuator/env等端点。但注意生产环境不能盲目暴露所有端点否则会泄露你的数据源密码和内部配置。你应该用management.endpoints.web.exposure.includehealth,info来限制。另一个容易被遗忘的是优雅停机。默认情况下Spring Boot应用收到SIGTERM信号后会直接退出正在处理的请求会被中断这会造成数据不一致。你需要在application.yml里设置server.shutdowngraceful并配置一个合适的spring.lifecycle.timeout-per-shutdown-phase。这样负载均衡器在摘除节点后应用会等待在途请求完成再退出。还有一个细节是外部化配置。不要把应用配置硬编码在jar里而是通过--spring.config.location或环境变量指向外部文件。这样你可以不重新打包就去修改生产参数这在线上应急时无比重要。依赖管理从“看似可以运行”到“真的能运行”之间是BOM与元数据回到pom.xml本身你不应该只是机械地使用spring-boot-starter-parent。实际上你可以不用parent而采用spring-boot-dependencies的BOM导入这样你的项目可以继承自己的企业父POM。这个区别尤其在大型公司中非常关键。统一依赖版本管理是解决依赖冲突的唯一解。当你的项目引入了hutool、guava、commons-lang3等多个工具库时它们往往传递依赖了不同版本的jackson或netty。你必须在根POM中用dependencyManagement显式声明你想要的版本。但这还不够你要学会使用dependency:tree结合-Dverbose来查看冲突的根源然后决定是用exclusion排除还是提升版本。记住把依赖项全凭直觉写在pom里而不做排查看项目的运行状态就好比“薛定谔的启动”不跑到一半你不会知道问题在哪。结语搭建项目是一次系统性思考而不是工具操作从零搭建一个Spring Boot项目表面上是一件“照葫芦画瓢”的事情但实际上它检验的是你对工程化、可维护性和生产环境的理解。最贵的代码是以后维护时阅读的代码最慢的启动是带着隐患上线的启动。你没有在开始阶段做的那些“小事”——版本锁定、包结构规划、日志规范、异常处理、测试骨架——都会在未来某个凌晨的故障中变成巨大代价。所以当你的应用第一次运行起来时请不要高兴得太早。请检查一下热部署是否生效看下Actuator是否安全暴露试着用java -jar在没有IDE的环境跑一次再去看一轮日志格式是否合理。一个优秀的Spring Boot项目不是“写”出来的而是“戒”戒掉随意与捷径出来的。愿你在每个零点字节中都为生产环境预留一份敬畏。