【持续更新】后端开发规范

1-DTO、Entity、VO

Entity：实体是直接映射到数据库表的Java类。

• 职责：

  1. 数据持久化： 专注于如何将对象状态保存到数据库以及如何从数据库加载。

  2. 定义数据模型： 精确地描述数据库表的结构（表名、列名、数据类型、关系、约束等）。

  3. 封装核心业务数据： 包含与数据库字段直接对应的属性。

DTO：根据接口需求定制字段，不应有业务逻辑。DTO是一种设计模式，用于在不同层（尤其是客户端与服务器之间）传输数据的对象。它不包含任何业务逻辑，只有数据（字段、getter、setter）。

DTO可以用lombok的@Data注解实现getter、setter等初始化方法。

• 职责：

  1. 数据封装与传输： 在网络间安全、高效地传输数据。

  2. 定制返回数据： 根据前端需求，组合、过滤、格式化数据，避免暴露内部实现细节和数据库结构。

  3. 减少网络请求次数： 通过组合多个实体的所需字段，一个DTO可以满足一个特定页面的所有数据需求，避免前端多次调用接口。

VO：高度定制，完全匹配前端页面需求，不应有业务逻辑。一般用于在Controller层返回HTTP请求。

2-POJO

DTO、Entity、VO都是属于POJO规范的。

2.1-POJO简介

在 Java 后端开发中，POJO（Plain Old Java Object） 是一个核心概念。它指的是一个普通的、不受任何特殊限制的 Java 对象，不继承特定的类，不实现特定的接口，也不被特定的注解所侵入。

然而，在实际开发中，我们会为不同用途的 POJO 制定详细的规范，以确保代码的清晰、可维护和高效。这些规范涵盖了命名、结构、编码实践以及特定类型 POJO（如 Entity, DTO, VO 等）的特定规则。

2.2-POJO类型

类型	英文全称	职责与用途	典型特征
PO/DO(Entity)	Persistent Object	数据持久化，与数据库表严格对应。	使用 JPA (@Entity, @Id, @Column) 或 MyBatis 注解。
DTO	Data Transfer Object	数据传输，用于服务层与控制器层、或跨系统之间的数据封装。	根据接口需求定制字段，不应有业务逻辑。
VO	Value Object / View Object	表现层对象，用于控制器向客户端（前端）返回的数据模型。	高度定制，完全匹配前端页面需求，不应有业务逻辑。
BO	Business Object	业务逻辑对象，在服务层内部使用，封装业务逻辑和操作。	可包含业务方法，可由多个 PO 聚合而成。
Query	Query Parameter Object	查询参数对象，专门用于接收前端复杂的查询条件。	包含各种过滤、分页、排序字段。

以上规范之间的关系：

Database Table <-> PO/DO(Entity) -> (聚合/转换) -> BO -> (转换) -> DTO -> (转换) -> VO -> Client

2.3-POJO开发规范

2.3.1-命名规范

类型	命名规则
类名	大驼峰式，名词，意义明确。User, Order, Product,UserDTO, UserVO, UserQuery
字段名	小驼峰式。userId, userName, createdAt
布尔类型字段	前缀使用 is, has, can 等。isDeleted, hasPermission, canExecute

2.3.2-结构规范

1. 属性私有：所有字段必须是 private。

2. 方法公开：使用Getter和Setter方法来访问和修改属性。推荐使用Lombok的 @Data 或 @Getter/@Setter 来生成，避免手动编写样板代码。

3. 实现序列化：如果对象需要网络传输（如RPC调用）或缓存（如Redis），必须实现 java.io.Serializable 接口，并定义一个 serialVersionUID。实现POJO的序列化就是为了让内存中的对象能够“超越”当前Java虚拟机（JVM）的生命周期和物理内存的限制，进行传输、存储和重建。

   • 序列化：指的是将对象的状态信息（即对象的属性/字段数据）转换为可以存储或传输的形式（通常是一个字节序列）的过程。

   • Serializable 是一个标记接口，它本身没有任何方法。实现这个接口的唯一目的，就是告诉 Java 虚拟机（JVM）：这个类的对象可以被序列化。

4. 基本数据类型陷阱：避免使用基本类型（如 int, long），因为它们有默认值（0），可能会影响 MyBatis 等ORM的查询映射。一律使用包装类型（如 Integer, Long）。

3-分层架构规范

分层架构的核心思想是关注点分离，将不同的功能逻辑划分到不同的层次中，每层只专注于自己的职责。这极大地提高了代码的可维护性、可测试性和可扩展性。

对于大多数 Web 应用，通常分为以下四层：

层级	英文名	核心职责	关键注解
表现层	Controller / Resource / Endpoint	处理HTTP请求，进行参数校验、数据序列化/反序列化，调用Service层并返回响应。	@RestController, @RequestMapping, @GetMapping, @PostMapping, @Valid
业务逻辑层	Service	应用的核心，包含复杂的业务逻辑、流程编排、事务控制、权限校验等。	@Service, @Transactional (事务应在此层控制)
持久层	Repository / DAO (Data Access Object)	负责与数据库进行交互，执行CRUD操作。屏蔽上层对数据库细节的感知。	@Repository, @Mapper (MyBatis)
模型层	Entity / DTO / VO	作为数据载体在各层之间传输。严格来说它不是一层，而是贯穿各层的对象。	@Entity, 无注解 (DTO/VO)

一个清晰的调用链：

HTTP Request -> Controller -> Service -> Repository -> Database

Database -> Repository (返回Entity) -> Service (处理业务, 转换为DTO) -> Controller (返回DTO/VO) -> HTTP Response

4-API接口规范

RESTful API 是一种广泛采用的设计风格，它利用 HTTP 协议的特性来表达资源和操作。

资源导向：API 的终点（Endpoint）应该是名词（资源），而不是动词。

• Bad: /getUsers, /createOrder
• Good: GET /users, POST /orders

HTTP 方法即操作：使用标准的 HTTP 方法来表达对资源的 CRUD 操作。

HTTP Method	操作	示例	说明
GET	读取/查询	GET /users	获取用户列表
POST	创建	POST /users	创建一个新用户
PUT	全量更新	PUT /users/{id}	更新指定用户的所有信息
PATCH	部分更新	PATCH /users/{id}	更新指定用户的部分信息
DELETE	删除	DELETE /users/{id}	删除指定用户

版本管理：API 一旦发布，就不能轻易破坏性变更。必须引入版本控制。

• URL Path 方式（最常用）：/api/v1/users, /api/v2/users
• Header 方式：Accept: application/vnd.example.v1+json

统一响应体：所有接口返回相同结构的 JSON。

{
  "code": 200,       // 业务状态码，200表示成功，非200表示失败
  "message": "成功", // 对状态的描述信息，错误时返回原因
  "data": { ... }    // 成功时返回的有效载荷数据
  // "timestamp": 1620000000000 // (可选) 服务器时间戳
}