搭建一个SpringBoot微服务项目写第一行代码并不难。难的是三个月后当团队从3人扩展到10人当服务从1个拆到8个代码库依然能保持清晰、一致、可维护。没有规范的微服务项目最终都会变成“能跑但没人敢改”的泥潭。以下这份代码规范是我们从多个生产项目中沉淀出来的从零搭建时照着做能帮你省下大量重构时间。一、项目结构按业务拆分而不是按技术分层很多项目习惯把所有Controller放一个模块、所有Service放另一个模块。这种按技术分层的做法在微服务下会带来灾难改一个业务功能要跨多个模块模块间依赖错综复杂。正确的做法是按业务领域拆分模块。一个典型的订单服务结构如下text复制下载order-service/ ├── order-api/ # 对外暴露的DTO和Feign接口 ├── order-domain/ # 领域模型、领域服务 ├── order-infrastructure/ # 数据库、缓存、消息队列实现 └── order-boot/ # 启动模块装配所有依赖每个业务模块内部再按controller、service、repository分层。这样拆的好处是业务边界清晰模块间依赖单向未来拆分成独立微服务时几乎不需要重构。二、命名规范让代码自己解释自己类名用大驼峰方法名和变量名用小驼峰常量全大写下划线分隔这些是基础。更重要的是语义化命名Controller以Controller结尾Service以Service结尾Repository以Repository结尾。布尔类型变量不要用is开头因为序列化时容易出问题用enabled、deleted更安全。DTO按用途命名OrderCreateRequest、OrderQueryResponse、OrderDetailVO不要用OrderDTO1、OrderDTO2。数据库表名用下划线分隔如order_detail实体类用大驼峰OrderDetail。三、统一返回格式与异常处理微服务对外返回的JSON必须结构统一否则前端要写无数个if-else。推荐格式json复制下载{ code: 0, message: success, data: { ... } }用RestControllerAdvice实现全局异常处理把业务异常、参数校验异常、系统异常分别映射为不同的错误码。永远不要在Controller里写try-catch业务异常直接抛出自定义BusinessException由全局处理器统一兜底。这样Controller代码干净异常逻辑集中管理。四、DTO、VO、Entity严格分离这是最容易偷懒的地方。很多项目直接用Entity接收前端参数、返回给前端结果导致数据库字段暴露、敏感信息泄露、前端传参污染数据库。规范做法Entity只用于数据库映射不对外暴露。DTO用于接收前端请求放在api模块。VO用于返回前端按需组装字段。转换用MapStruct或手动Builder不要用BeanUtils.copyProperties字段名不一致时它不会报错是线上事故的常客。五、配置与依赖管理所有配置项集中在application.yml敏感信息用环境变量或配置中心禁止硬编码密码和密钥。多环境用application-dev.yml、application-prod.yml区分。依赖管理上父POM统一管理版本号子模块只声明groupId和artifactId。禁止在子模块中随意引入新依赖而不经过父POM版本控制否则依赖冲突会让你在启动时收到一堆NoSuchMethodError。六、日志与监控日志用SLF4J禁止用System.out.println。关键业务节点必须打日志请求入口、外部调用前后、异常捕获处。日志格式统一包含traceId便于链路追踪。每个服务必须暴露/actuator/health和/actuator/metrics接入Prometheus和Grafana。没有监控的微服务等于裸奔。七、代码检查与测试集成Checkstyle和SpotBugs在CI流程中强制执行。单元测试覆盖Service核心逻辑集成测试覆盖Controller到数据库的完整链路。测试类命名XxxServiceTest方法命名should_do_something_when_condition。写在最后规范的价值不在于“看起来专业”而在于降低协作成本。当每个人都按同样的结构写代码Code Review会从“你这里为什么这么写”变成“这个逻辑有没有边界问题”。从零搭建时多花一天定规范未来能省下几十天的返工时间。这份规范建议直接放进项目根目录的CONTRIBUTING.md让新加入的人第一天就知道该怎么写。