一、项目包结构（Package Naming）

com.yourcompany.projectname
├── controller          // 控制器层，接收请求
├── service             // 业务逻辑层
│   ├── impl            // 服务实现类
├── repository          // 数据访问层（DAO），或使用 mapper
├── model               // 实体类（与数据库表对应）
│   ├── dto             // 数据传输对象（API 进出参数）
│   ├── vo              // 视图对象（用于前端展示）
├── config              // 配置类（如 Redis、Swagger、Security）
├── common              // 通用工具、常量、异常、枚举
│   ├── constant
│   ├── enums
│   ├── exception
│   ├── utils
├── interceptor         // 拦截器
├── filter              // 过滤器
├── aspect              // AOP 切面
├── event               // 事件监听
└── Application.java    // 启动类

命名规则：

• 包名全小写，多个单词用 . 分隔，如 com.example.usercenter。
• 分层清晰，避免循环依赖。

---

二、常用类文件命名规范

类型	命名示例	说明
启动类	XxxApplication.java	唯一，包含 @SpringBootApplication
控制器（Controller）	UserController.java	处理 HTTP 请求，通常使用 @RestController
服务接口（Service）	UserService.java	业务逻辑接口
服务实现（Impl）	UserServiceImpl.java	放在 service.impl 包中，实现 UserService
数据访问（DAO）	UserRepository.java / UserMapper.java	继承 JPA Repository 或 MyBatis Mapper
实体类（Entity）	User.java	对应数据库表，一般与表名相同（驼峰映射）
DTO（数据传输对象）	UserCreateDTO.java, UserQueryDTO.java	用于接收前端参数或返回特定数据，与 Entity 解耦
VO（视图对象）	UserVO.java	用于最终返回前端展示，可组合多个字段
配置类	RedisConfig.java	标注 @Configuration，提供 Bean
常量类	Constants.java 或 RedisKeyConstants.java	存放静态 final 常量
枚举类	UserStatusEnum.java	定义状态、类型等枚举值
工具类	DateUtils.java	静态方法，通常标注 @UtilityClass（Lombok）
异常类	BusinessException.java	继承 RuntimeException，配合全局异常处理
拦截器/过滤器	LoginInterceptor.java, LogFilter.java	实现相应接口
切面类	LogAspect.java	标注 @Aspect，用于日志、权限等横切逻辑

命名约定：

• 接口与实现：接口不加 I 前缀（避免 C# 风格），实现类加 Impl 后缀。
• DTO 按用途命名：XxxRequest, XxxResponse, XxxQuery, XxxCommand。
• 测试类：XxxTest.java 或 XxxTests.java，放在 src/test/java 对应包下。

---

三、配置文件命名及作用

Spring Boot 项目通常使用 application.yml 或 application.properties，多环境配置遵循 application-{profile}.yml 模式。

文件名	用途
application.yml / application.properties	主配置文件，存放通用配置
application-dev.yml	开发环境配置
application-test.yml	测试环境配置
application-prod.yml	生产环境配置
bootstrap.yml	Spring Cloud 场景下，比 application 优先加载，用于配置中心（如 Nacos）
logback-spring.xml / log4j2-spring.xml	日志框架配置，Spring 可识别 -spring 后缀以支持 profile
application-{profile}.properties	与 yml 等价，视团队习惯选择
application-local.yml	本地专用配置（不提交到版本库，用于覆盖）

推荐：用 yml 格式，清晰层次，避免重复。

---

四、接口（API）编写规范

1. URL 命名（RESTful 风格）

• 使用名词复数，小写，用 / 分隔，如：
  • GET /api/users → 查询用户列表
  • GET /api/users/{id} → 查询单个用户
  • POST /api/users → 创建用户
  • PUT /api/users/{id} → 全量更新
  • PATCH /api/users/{id} → 部分更新
  • DELETE /api/users/{id} → 删除用户
• 使用 @RequestMapping("/api") 作为根路径。

2. HTTP 方法对应操作

方法	含义
GET	查询
POST	创建
PUT	全量更新
PATCH	部分更新
DELETE	删除

3. Controller 方法命名

• 方法名尽量体现业务，如 listUsers(), getUserById(), createUser(), updateUser(), deleteUser()。
• 使用 @GetMapping, @PostMapping 等注解，明确路径。

4. 参数接收

• 路径参数：@PathVariable
• 查询参数：@RequestParam
• 请求体：@RequestBody
• 混合使用 DTO 接收复杂对象。

5. 统一响应格式

建议封装一个通用 Result<T> 类，包含 code, message, data，让前端统一处理。

---

五、常用 Maven / Gradle 插件

Maven 插件（pom.xml）

插件	作用
spring-boot-maven-plugin	打包可执行 jar，支持 mvn spring-boot:run 运行
maven-compiler-plugin	指定 Java 编译版本（如 17）
maven-surefire-plugin	运行单元测试，可配置跳过测试
maven-resources-plugin	资源文件复制与过滤
lombok-maven-plugin	让 Lombok 在编译时生成 getter/setter（通常无需额外配置，仅需依赖）
maven-dependency-plugin	依赖分析，管理版本冲突
maven-jar-plugin / maven-assembly-plugin	自定义打包方式（如将依赖打进一个 jar）
spotless-maven-plugin / formatter-maven-plugin	代码格式化（统一风格）
jacoco-maven-plugin	代码覆盖率统计

Gradle 插件（build.gradle）

插件	对应作用
org.springframework.boot	同上，Spring Boot 支持
io.spring.dependency-management	依赖版本管理（BOM）
java / java-library	Java 编译
idea	IDEA 专属配置
lombok	Lombok 支持（或通过依赖启用）
com.diffplug.spotless	代码格式化
jacoco	覆盖率报告

---

六、常用 IDE 插件（以 IntelliJ IDEA 为例）

插件名称	用途
Lombok	支持 @Data, @Slf4j 等注解，减少样板代码
Spring Boot Assistant / Spring Initializr and Assistant	快速查看配置文件、运行端点，提供 Spring 相关提示
MyBatisX / MyBatis Log Free	MyBatis 项目必备，支持 XML 与 Mapper 跳转，日志 SQL 还原
Alibaba Java Coding Guidelines	代码规约检查，帮助写出更规范的代码
SonarLint	静态代码分析，实时提示潜在 bug 和异味
MapStruct Support	如果使用 MapStruct 做 DTO 转换，提供支持
Gradle / Maven Helper	查看依赖冲突，快速运行生命周期命令
GitToolBox / GitHub Copilot	提高 Git 效率或 AI 辅助编码（可选）
Rainbow Brackets	括号颜色高亮，便于阅读嵌套代码
Translation	英文翻译，帮助理解命名和注释

---

七、其他关键文件

文件名	用途
pom.xml / build.gradle	项目构建文件，管理依赖和插件
.gitignore	忽略编译输出、IDE 配置、日志等不应提交的文件
README.md	项目简介、启动说明、技术栈、API 文档链接
Dockerfile	构建 Docker 镜像，用于容器化部署
docker-compose.yml	本地开发环境编排（如 MySQL、Redis）
application.yml	见上文
logback-spring.xml	日志配置（若不使用默认）
config/ 或 src/main/resources	存放配置文件，注意 Maven 会打包进 classpath

---

八、命名总结（快速记忆口诀）

• 包：全小写，点分隔，分层清晰。
• 类：大驼峰（PascalCase），名词，表达实体或功能。
• 方法：小驼峰（camelCase），动词 + 名词，如 getUserById。
• 变量：小驼峰，名词，明确意义。
• 常量：全大写，下划线分隔，如 MAX_RETRY_COUNT。
• 枚举：类名大驼峰，枚举值全大写。
• 接口 URL：资源名词复数，小写，使用 / 层级。

---

九、给小白的一些额外建议

1. 遵循命名约定：团队内部统一，借助插件（如 Alibaba 规约）检查。
2. 多利用 IDE 模板：如 IDEA 的 live templates 创建快捷代码片段。
3. 善用依赖管理：使用 Spring Boot Starter 可以减少繁琐配置。
4. 环境分离：开发、测试、生产配置独立，避免混淆。
5. 日志留痕：使用 Lombok 的 @Slf4j，方便调试和问题定位。
6. 版本控制：及时提交，写好 commit message，遵循语义化版本。

---

这份清单涵盖了从项目结构到编码细节的大多数场景，希望它能帮助你快速上手并养成良好的习惯。如果你在具体使用中遇到问题，欢迎随时查阅官方文档或社区实践，也欢迎向我提问。祝编码愉快！🚀