阿里巴巴Java开发规范下的实体类设计：Lombok + MyBatis Plu

概述

本文介绍如何结合阿里巴巴《Java开发手册》规范，使用 Lombok 简化样板代码，并通过 MyBatis Plus 注解完成数据库表映射，构建整洁、可维护的实体层。

一、依赖引入

<dependencies>
    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.30</version>
        <scope>provided</scope>
    </dependency>
    
    <!-- MyBatis Plus -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>3.5.5</version>
    </dependency>
</dependencies>

二、规范要点对照

规范条款	具体要求	实现方式
命名规范	类名驼峰，表名小写下划线	`@TableName("user_info")`
字段命名	数据库下划线，Java驼峰	自动映射 + `@TableField`
必须含主键	每张表必须有主键	`@TableId`
时间类型	使用 `java.time.LocalDateTime`	字段类型 + `fill` 自动填充
布尔类型	禁止以 `is` 开头	`deleted` 替代 `isDeleted`
注释完整	类、字段必须有 Javadoc	保留注释，Lombok不冲突

三、完整实体类示例

package com.example.entity;

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import lombok.experimental.Accessors;

import java.io.Serializable;
import java.time.LocalDateTime;

/**
 * 用户信息实体类
 * 
 * @author example
 * @since 2024-01-01
 */
@Data
@Accessors(chain = true)
@TableName("user_info")
public class UserInfo implements Serializable {

    private static final long serialVersionUID = 1L;

    /** 用户ID，主键，自增 */
    @TableId(value = "user_id", type = IdType.AUTO)
    private Long userId;

    /** 用户名 */
    @TableField("user_name")
    private String userName;

    /** 邮箱 */
    private String email;

    /** 手机号 */
    private String phone;

    /** 状态：0-禁用，1-启用 */
    private Integer status;

    /** 逻辑删除标志：0-未删除，1-已删除 */
    @TableLogic
    @TableField("deleted")
    private Integer deleted;

    /** 创建时间，插入时自动填充 */
    @TableField(value = "create_time", fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    /** 更新时间，插入和更新时自动填充 */
    @TableField(value = "update_time", fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
}

四、关键注解详解

4.1 主键策略

策略	说明	适用场景
`IdType.AUTO`	数据库自增	单机MySQL，推荐
`IdType.ASSIGN_ID`	雪花算法Long	分布式系统
`IdType.ASSIGN_UUID`	UUID字符串	无顺序要求
`IdType.NONE`	无策略，需手动赋值	特殊业务

4.2 字段映射

// 字段名不一致时显式映射
@TableField("gmt_create")
private LocalDateTime createTime;

// 排除非数据库字段
@TableField(exist = false)
private List<Order> orders;

// 字段更新策略：条件判断
@TableField(update = "now()")
private LocalDateTime lastLoginTime;

4.3 自动填充配置

@Component
public class MyMetaObjectHandler implements MetaObjectHandler {

    @Override
    public void insertFill(MetaObject metaObject) {
        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }

    @Override
    public void updateFill(MetaObject metaObject) {
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }
}

五、Lombok 选型建议

注解	作用	规范建议
`@Data`	生成 getter/setter/equals/hashCode/toString	实体类可用，避免与 `@Builder` 混用
`@Builder`	构建者模式	复杂对象构造，需配合 `@AllArgsConstructor`
`@Accessors(chain = true)`	链式调用 `user.setName().setAge()`	提升流畅性，团队统一即可
`@EqualsAndHashCode(callSuper = true)`	含父类字段比较	有继承时必须显式声明
`@ToString(exclude = "password")`	排除敏感字段	日志安全，强烈推荐

安全增强示例：

@Data
@EqualsAndHashCode(callSuper = true)
@ToString(exclude = {"password", "salt"})
@TableName("sys_user")
public class SysUser extends BaseEntity {
    // ...
}

六、通用基类设计

@Data
public abstract class BaseEntity implements Serializable {
    
    private static final long serialVersionUID = 1L;

    @TableId(type = IdType.ASSIGN_ID)
    private Long id;

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;

    @TableField(fill = FieldFill.INSERT)
    private Long createBy;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Long updateBy;

    @TableLogic
    @TableField(fill = FieldFill.INSERT)
    private Integer deleted;
}

七、避坑清单

问题	原因	解决
`isSuccess` 序列化异常	布尔 `is` 前缀与 getter 冲突	命名改为 `success` 或 `deleted`
`@Data` 循环引用栈溢出	`toString()` 双向引用	`@ToString.Exclude` 或自定义
字段未映射报错	下划线转驼峰未开启	配置 `map-underscore-to-camel-case: true`
主键回填失败	`IdType` 与数据库不一致	核对 `AUTO` 需数据库自增
`LocalDateTime` 存取异常	JDBC驱动版本低	升级 `mysql-connector-java` 至 8.x

八、完整配置（application.yml）

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0
  type-aliases-package: com.example.entity

结论

遵循阿里巴巴Java开发规范，结合 Lombok 消除样板代码、MyBatis Plus 注解驱动映射，可使实体层代码量减少 60% 以上，同时保证可读性与可维护性。核心原则：约定优于配置，显式优于隐式，安全优于便利。