项目开发规范

在开发项目时，合理的命名规范和清晰的项目结构可以显著提高代码的可读性、可维护性和团队协作效率。以下是一个常见的 Java 项目命名方案、代码风格、包结构和代码规范，适用于大多数基于 Spring Boot、MyBatis、Spring MVC 等技术栈的项目。

1. 命名方案

项目名

• 项目名应简洁、易懂且具描述性，通常使用小写字母并可以用短横线 - 分隔。
  • 示例：online-bookstore（在线书店）

Controller 类名

• 控制器类通常以 Controller 结尾，表示它是负责处理用户请求的类。
  • 示例：BookController（处理图书相关请求）

Service 类名

• 服务类通常以 Service 结尾，表示它封装了业务逻辑。
  • 示例：BookService（处理图书相关的业务逻辑）

DAO 类名

• DAO（Data Access Object）类通常以 Dao 结尾，负责与数据库进行交互。
  • 示例：BookDao（图书数据访问对象）

Mapper 类名

• Mapper 类用于与 MyBatis 映射 SQL 操作，通常以 Mapper 结尾。
  • 示例：BookMapper（图书 SQL 映射）

实体参数类名

• 实体类通常使用与数据库表相同的名称，并使用大写驼峰命名法。
  • 示例：Book（图书实体类）

方法名

• 方法名采用小写字母开头的驼峰命名法，确保方法名具描述性。
  • 示例：getBookById()（根据 ID 获取图书）

参数名

• 参数名采用小写字母开头的驼峰命名法，尽量保持简洁且具描述性。
  • 示例：bookId（图书的 ID）

2. 代码风格

缩进和格式化

• 每个代码块使用 4 个空格进行缩进。
• 方法之间应留有空行以提高可读性。
• 每行代码长度不应超过 120 个字符。

空格与换行

• 运算符前后应有空格（例如：if (x == 0)）。
• 左右大括号 { 和 } 应放在新的一行（即 K&R 风格）。
• 控制语句（if, else, for, while）的大括号即使在一行也要写上。

注释

• 对于类、方法和复杂的代码块，务必添加说明性注释。
• 使用 Javadoc 注释风格（/** ... */）来为公共类和方法提供详细的文档。
• 注释应简洁明了，避免重复明显内容。

命名规范

• 变量和方法使用小驼峰命名（camelCase）。
• 类名和接口名使用大驼峰命名（PascalCase）。
• 常量名使用全大写字母，并用下划线分隔（UPPER_SNAKE_CASE）。

3. 项目的包结构

推荐的包结构

com
 └── yourcompany
      ├── api           // 接口层（Controller）
      │    └── BookController.java
      ├── service       // 业务逻辑层（Service）
      │    └── BookService.java
      ├── dao           // 数据访问层（DAO）
      │    └── BookDao.java
      ├── mapper        // MyBatis 映射器（Mapper）
      │    └── BookMapper.java
      ├── model         // 实体类
      │    └── Book.java
      ├── util          // 工具类
      │    └── DateUtil.java
      ├── exception     // 异常类
      │    └── ServiceException.java
      ├── config        // 配置类
      │    └── AppConfig.java
      ├── enum          // 枚举类
      │    └── BookCategory.java
      ├── dto           // 数据传输对象（DTO）
      │    └── BookDTO.java
      └── test          // 测试代码
           └── BookServiceTest.java

包层次结构说明：

• api: 控制器层，处理 HTTP 请求与响应。此层一般依赖于 service 层。
• service: 业务逻辑层，处理核心业务逻辑，与 dao 层交互。
• dao: 数据访问层，通常通过 Mapper 或直接 JDBC 与数据库交互。
• mapper: 用于 MyBatis 的 SQL 映射接口。
• model: 数据模型类，通常与数据库表一一对应，包含字段和 getter/setter 方法。
• util: 工具类，提供常用的静态方法，如日期处理、文件操作等。
• exception: 自定义异常类，封装业务逻辑相关的错误。
• config: 配置文件，例如数据库连接配置、Spring 配置等。
• enum: 枚举类型，定义常量集合。
• dto: 数据传输对象，用于在不同层之间传输数据，通常是 service 层与 api 层之间的数据对象。
• test: 测试相关的代码，如单元测试、集成测试等。

4. 代码规范

命名规范

• 类名、接口名采用大驼峰（PascalCase）。
• 方法名、变量名采用小驼峰（camelCase）。
• 常量采用全大写，单词间用下划线分隔。

类的设计

• 每个类只负责一个职责。遵循单一职责原则（SRP）。
• 避免过长的类，类的行数应保持在 200 行以内。

方法设计

• 每个方法应尽量小而简单，避免过长的方法。推荐方法行数小于 30 行。
• 方法尽量具有明确的功能，并且方法名能清晰表达其意图。

异常处理

• 在 service 层和 controller 层处理异常并提供用户友好的错误消息。
• 尽量使用自定义异常来捕获业务异常。

依赖注入

• 使用构造函数注入代替字段注入，以便于测试和解耦。

日志记录

• 使用 SLF4J 和 Logback 作为日志框架。
• 在 service 层和关键业务逻辑中记录日志。

5. 其他建议

• 版本控制: 使用 Git 进行版本控制，并遵循 Git 分支管理策略，如 Git Flow。
• 依赖管理: 使用 Maven 或 Gradle 进行项目的依赖管理，确保每个模块的依赖都明确、版本一致。
• 单元测试: 每个业务逻辑类都应当有对应的单元测试，确保功能的正确性。