一个SpringBoot项目从零开始搭建，真正的分水岭往往不在业务代码的复杂度，而在最初那十几个基础文件里。有人用三分钟初始化一个工程，后续却要花三个月为当初的随意填坑；有人小心翼翼搭骨架，却因为一个包名设计失误，让整个团队在几个月后陷入重构的地狱。基础结构不是束缚，而是你为未来混乱埋下的免疫系统。
第一技：先画边界，再写代码——包结构不是文件夹排列
很多人搭建SpringBoot时，习惯性地按技术分层建包：controller、service、dao、entity、config、common……这个套路看似清晰，实际上是一个巨大的陷阱。当项目只有几十个类时，这种结构还勉强可用；一旦业务扩张到上百个类，所有controller堆在一起，所有service挤作一团，你面对的就是一个无法快速定位业务入口的“大杂烩”。
更合理的做法是“按业务模块划分包结构”。比如一个电商项目，可以拆成order、product、user、pay四大模块，每个模块内部再按层次组织：controller、service、mapper、domain。这样一来，新增一个订单功能，你只需要在order包下动手，改动范围被牢牢锁在一个模块的边界内。模块之间通过接口通信，而不是通过互相new对象来耦合。
边界就是权限。当你把包结构设计成模块化时，后续排查问题、做代码审查、分配开发任务都会变得异常顺畅。更关键的是，这种结构让团队成员自然地形成了“领域意识”——没人愿意在自己的模块边界外乱写代码，因为那样会导致代码落位不当，review时一眼就会被指出来。所以，搭建项目的第一个动作，不是选择依赖，而是定义边界。花半小时梳理业务域和包结构，远比花半小时挑选漂亮的前端模板有价值。
第二技：统一返回体与全局异常——别让每个接口自己定义风格
很多新手项目里，一个接口返回Map<String, Object>，另一个接口返回自定义的Result类，还有的索性直接返回裸实体User，当出错时又抛出各种莫名其妙的异常片段。前端接到这些响应根本无从下手，只能靠猜。没有统一返回体的项目，本质上就是在向调用方甩锅。
请务必在项目第一天就定义一个全局返回体，比如ApiResponse<T>，包含code、message、data三个核心字段。所有接口的返回值必须是这个包装类，哪怕接口确实没有数据，也要用ApiResponse.success(null)来占位。同时，定义一个GlobalExceptionHandler，用@RestControllerAdvice拦截所有异常，把业务异常、参数校验异常、未知异常全部翻译成标准格式。最重要的原则是：异常信息不要原封不动堆给前端，必须经过一层“脱敏”和“翻译”。
这里有个金句值得记住：异常是接口契约的一部分，而不是流程中的意外。如果你在写接口时只考虑“正常情况”下的返回，那么你的接口文档就是残缺的。全局异常处理不是可有可无的装饰，它决定了你的接口在恶劣环境下是否仍然保持可预测性。当后端出现NullPointerException时，前端接到的应该是一个友好且带有错误码的JSON，而不是一坨堆栈信息。不统一错误码的项目，迟早会在联调时变成一场互相推诿的辩论赛。
第三技：配置文件要分层拆分，而不是把所有密钥塞进一个application.yml
SpringBoot默认的application.yml承载着端口、数据库连接、Redis、日志级别、第三方API秘钥等五花八门的配置。随着项目长大，这个文件会变成几百行的“乱葬岗”，每次改配置都心惊胆战。配置管理的核心原则是：让机密和可变性分离。
首先，建议将配置文件按环境拆分为application-dev.yml、application-test.yml、application-prod.yml，主配置只保留公共项。然后，再进一步拆分成模块化配置：比如application-db.yml管数据源，application-redis.yml管缓存，application-api.yml管第三方接口。我们在主配置中用spring.profiles.include来组合激活。这样做的好处是：你永远不会在主配置里看到某个测试环境的数据库密码，也不会因为改一个Redis端口而误伤数据源配置。
更进一步，任何涉及秘钥、密码、Token的配置项，应该立刻接入配置中心或环境变量。开发本地可以使用env变量占位，生产环境接入Nacos或Spring Cloud Config。把密码写在application.yml里提交到Git仓库，无异于把家门的备用钥匙贴在楼道里。很多人觉得“反正项目是内网”，但供应链攻击和离职员工泄露远比想象中频繁。牢记：配置文件也是代码的一部分，它需要像代码一样被审查、被版本控制、被审计。
第四技：参数校验不要依赖手写if——让注解替你说话
Controller层最常见的脏代码就是一连串的if (name == null || name.isEmpty())，然后挨个返回错误信息。这种写法不仅冗长，而且极易遗漏边界条件。SpringBoot默认集成了Hibernate Validator，你只需要在实体字段上标注约束注解，就能完成绝大部分参数校验。
请把@Validated或@Valid用在Controller方法参数上，并在DTO中声明@NotNull、@NotBlank、@Size、@Pattern等注解。加上全局异常处理器后，校验失败会自动抛出MethodArgumentNotValidException，此时你可以统一提取错误消息并返回给前端。这段逻辑一旦写好，后续新接口的参数校验近乎零成本——你只需要在字段上声明规则。
更高级的用法是自定义校验注解。比如一个“创建订单”接口，需要校验订单金额必须大于0且小于某个上限，同时状态码必须是合法枚举。你可以写一个@OrderAmountValid注解，配合ConstraintValidator实现复杂逻辑。自定义注解的威力在于：它把业务规则的表达从代码逻辑中抽离出来，变成字段上的一行声明。这会让代码可读性提升一个量级，也让代码审查变得极为轻松——审查者无需阅读一整个校验方法，只需要扫一眼字段注解，就能知道这个参数有哪些约束。
校验的终极目标不是“防住坏人”，而是让合法数据更顺畅地通过。当你把校验逻辑从方法体挪到字段声明上，你会惊讶地发现，原来几十行的防御性代码，最后只简化为三五个注解。这种减法式的优化，才是工程素养的体现。
第五技：用AOP统一记录接口日志与耗时，而不是四处打印System.out
新手项目中，你经常能看到这样的代码：进入方法时System.out.println("开始查询用户")，结束时System.out.println("查询完成")，出错了e.printStackTrace()。这些碎日志不仅毫无检索价值，还会直接把单测输出刷成乱码。对SpringBoot而言，日志是基础设施，绝不是业务代码的附属品。
建议在项目启动初期就引入AOP切面，定义@Around("@within(org.springframework.web.bind.annotation.RestController)")这样的切点，自动获取接口的URL、HTTP方法、请求参数、响应结果、处理耗时等信息，然后使用log.info输出到统一日志文件。你还可以通过logback-spring.xml按天滚动、按大小切分，并把日志同步到ELK或Loki供可视化检索。没有搜索能力的日志，等于没有日志。
尤其重要的一点是：记录日志时禁止打印请求体中的敏感字段，比如密码、Token、手机号。你可以写一个脱敏工具，把这类字段替换成。很多人觉得这只是“谨慎”，但实际上这是法律法规的硬性要求。留痕不是目的，可追溯才是。当你线上出现问题时，一份结构化的日志能帮你快速定位是哪个接口慢、哪个参数非法、哪次调用依赖超时。而如果你只在业务方法里随意打印几句，那么排查问题的成本会高到让你怀疑人生。
与其相信团队成员的自我约束，不如用AOP统一强制约束。这也是一个实用技巧：在使用AOP时，把日志切面做成一个独立的starter模块，任何新项目集成时只需两行配置即可生效。这从根本上杜绝了“项目里有人不写日志”的隐患。
技巧之外：别忽视启动时的“体检”和依赖管理
除了上面五个核心技巧，还有两个细节值得顺带提一下。第一，要在主启动类上使用@SpringBootApplication时，注意扫描包的默认规则——它只扫描主类所在包及子包。如果你把主类放在com.example.demo，却把业务模块放在com.example.foo，那么所有Bean都会注入失败。解决方法是精心设计包根路径，或者使用@ComponentScan显式指定。第二，依赖版本管理一定要交给SpringBoot BOM，自己手动指定版本是升级时的噩梦。引入Spring Cloud时，还要用spring-cloud-dependencies来统一版本，不要自己随便填写一个版本号。
搭建项目本质上是在搭建协作规则。每一个看似琐碎的配置，最终都决定了团队在半年后的生产体验。你不必一次做到完美，但至少要在第一天就把上面五件事落实——因为后续的每一次功能迭代都在这个地基上加速，而地基里的任何裂缝，都会随着时间变成无底洞。最贵的不是写代码的工时，而是你为当初的“图省事”所付出的返工成本。从零搭建一个SpringBoot项目，技术上不难，难的是克制住“先跑起来再说”的冲动，愿意在动手前多思考五分钟的结构设计。这五分钟，就是你作为工程师与“代码搬运工”之间最本质的区别。
