数据库对象实例化流程模板 + 常见错误

[一. 数据库建表](#一. 数据库建表)

[二. 创建实体类](#二. 创建实体类)

[2.1 字段类型与数据库类型对应关系](#2.1 字段类型与数据库类型对应关系)

[2.2 常用注解](#2.2 常用注解)

[2.3 示例](#2.3 示例)

[三. 创建 Mapper 接口](#三. 创建 Mapper 接口)

[四. 创建 Mapper XML 映射文件](#四. 创建 Mapper XML 映射文件)

[五. 配置application.yml](#五. 配置application.yml)

[六. 编写测试用例](#六. 编写测试用例)

在Java项目中操作数据库要先将数据库对象实例化，其流程通常为：数据库建表------>创建实体类（PO/DO）------>创建 Mapper 接口------>创建 Mapper XML 映射文件------>配置application.yml------>编写测试用例

一. 数据库建表

这点没什么好说的，根据业务需求设计并创建数据库表，明确字段类型、主键、索引等约束。

二. 创建实体类

实体类（PO：Persistent Object / DO：Data Object）是数据库表在 Java 代码中的映射，一个表对应一个实体类，数据库字段对应实体类中的属性，表中的一行数据对应实体类的一个对象。有两个注意的点，一个是字段类型与数据库类型对应 ，一个是常用的注解。

2.1 字段类型与数据库类型对应关系

以下是字段类型与数据库类型对应关系的表格，常用的都在这里，但还是要根据业务规则有所调整

|--------------------------|--------------------|-----------------------------------------------------------------|
| 数据库类型（MySQL） | Java 类型（推荐） | 说明 |
| BIGINT | Long | 范围大（-922 亿～922 亿），适合主键、大数值 |
| INT | Integer | 范围适中（-21 亿～21 亿），适合普通数值 |
| TINYINT | Byte 或 Integer | -Byte：节省内存（范围 -128~127），适合状态码（0/1/2） -Integer：兼容性更好，无需考虑范围 |
| VARCHAR(n) | String | 字符串，适合名称、描述、ID 等文本 |
| TEXT / LONGTEXT | String | 长文本，适合大段内容 |
| DATETIME / TIMESTAMP | LocalDateTime | - 线程安全、API 简洁、无时区问题- 替代旧版 Date（线程不安全、API 繁琐） |
| DATE | LocalDate | 仅日期（年月日） |
| TIME | LocalDate | 仅时间（时分秒） |
| DECIMAL(m,n) | BigDecimal | 高精度数值，适合金额、价格（避免 Double/Float 精度丢失） |
| BIT(1) / BOOLEAN | Boolean | 布尔值（true/false） |

注意事项：

金额字段绝对不用 Double/Float ：必须用**BigDecimal**，否则会出现 0.1 + 0.2 = 0.30000000000000004 的精度问题
主键用 Long ：即使数据库是 INT，也建议用 Long，避免后续数据量超过 INT 范围（-21 亿～21 亿）
字段可空性 ：数据库字段允许 NULL 时，Java 类型用包装类 （如 Integer、Long），不用基本类型（如 int、long），因为基本类型不能存 NULL

2.2 常用注解

1. Lombok 注解（必用，简化代码）

Lombok 可以自动生成 getter/setter/toString/ 构造方法等，无需手动写。

|---------------------|-------------------------------------------------------|-----------------------------|
| 注解 | 作用 | 示例 |
| @Data | 自动生成：getter、setter、toString、equals、hashCode | 直接加在类上 |
| @NoArgsConstructor | 自动生成无参构造方法 | 必须加，MyBatis/Spring 实例化对象时需要 |
| @AllArgsConstructor | 自动生成全参构造方法 | 可选，方便创建对象时赋值 |
| @Builder | 支持链式调用创建对象 | 可选，代码更优雅 |

2. ORM 映射注解（根据框架选择）

如果是Spring Data JPA框架，则需要加以下注解

|-----------------------------------------------------|--------------------------------|-------------------------------------|
| 注解 | 作用 | 示例 |
| @Entity | 标识这是一个 JPA 实体类 | 加在类上 |
| @Table(name = "表名") | 指定实体类对应的数据库表名 | @Table(name = "group_buy_activity") |
| @Id | 标识主键字段 | 加在主键字段上 |
| @GeneratedValue(strategy = GenerationType.IDENTITY) | 主键自增策略（对应数据库 AUTO_INCREMENT） | 加在 @Id 下方 |
| @Column(name = "数据库字段名") | 显式指定字段映射（可选，默认自动下划线转驼峰） | @Column(name = "activity_id") |

如果用的是MyBatis，实体类不需要 ORM 注解 ，只需通过 XML 里的 resultMap 映射字段即可

2.3 示例

java 复制代码

package cn.qimingxing.infrastructure.dao.po;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDateTime;

/**
 * 拼团活动实体类（对应数据库表：group_buy_activity）
 */
@Data // 自动生成 getter/setter/toString/equals/hashCode
@Builder // 支持链式调用创建对象
@AllArgsConstructor // 自动生成全参构造方法
@NoArgsConstructor // 自动生成无参构造方法（必须加！）
public class GroupBuyActivity {

    /** 自增ID（对应数据库：id） */
    private Long id;

    /** 活动ID（对应数据库：activity_id） */
    private Long activityId;

    /** 来源（对应数据库：source） */
    private String source;

    /** 渠道（对应数据库：channel） */
    private String channel;

    /** 商品ID（对应数据库：goods_id） */
    private String goodsId;

    /** 折扣ID（对应数据库：discount_id） */
    private String discountId;

    /** 拼团方式（0自动成团、1达成目标拼团）（对应数据库：group_type） */
    private Integer groupType;

    /** 拼团次数限制（对应数据库：take_limit_count） */
    private Integer takeLimitCount;

    /** 拼团目标（对应数据库：target） */
    private Integer target;

    /** 拼团时长（分钟）（对应数据库：valid_time） */
    private Integer validTime;

    /** 活动状态（0创建、1生效、2过期、3废弃）（对应数据库：status） */
    private Integer status;

    /** 活动开始时间（对应数据库：start_time） */
    private LocalDateTime startTime; // 推荐用 LocalDateTime，替代 Date

    /** 活动结束时间（对应数据库：end_time） */
    private LocalDateTime endTime;

    /** 人群标签规则标识（对应数据库：tag_id） */
    private String tagId;

    /** 人群标签规则范围（对应数据库：tag_scope） */
    private String tagScope;

    /** 创建时间（对应数据库：create_time） */
    private LocalDateTime createTime;

    /** 更新时间（对应数据库：update_time） */
    private LocalDateTime updateTime;
}

java 复制代码

// 用 @Builder 链式调用创建对象，代码更优雅
GroupBuyActivity activity = GroupBuyActivity.builder()
        .activityId(1001L)
        .source("APP")
        .channel("WECHAT")
        .goodsId("G001")
        .discountId("D001")
        .groupType(0)
        .takeLimitCount(1)
        .target(3)
        .validTime(15)
        .status(1)
        .startTime(LocalDateTime.now())
        .endTime(LocalDateTime.now().plusDays(7))
        .build();

三. 创建 Mapper 接口

这一步主要是定义操作数据库的方法，注意方法的返回值一般需要用到上一步定义的实体类

要注意两点：

添加 @Mapper 注解，让 Spring 扫描并注册为 Bean
若接口不在启动类子包下，需在启动类添加 @MapperScan("包路径")

四. 创建 Mapper XML 映射文件

这里有标准模板

XML 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<!-- 1. namespace：必须是 Dao 接口的全类名（点分隔，不带 .java） -->
<mapper namespace="cn.qimingxing.infrastructure.dao.IGroupBuyActivityDao">

    <!-- 2. 结果映射：数据库字段 <-> 实体类字段 -->
    <resultMap id="BaseResultMap" type="cn.qimingxing.infrastructure.dao.po.GroupBuyActivity">
        <!-- 主键字段 -->
        <id column="id" property="id"/>
        <!-- 普通字段 -->
        <result column="activity_id" property="activityId"/>
        <result column="source" property="source"/>
        <result column="channel" property="channel"/>
        <result column="goods_id" property="goodsId"/>
        <result column="create_time" property="createTime"/>
    </resultMap>


    <!-- 4. 查询语句 -->
    <select id="queryGroupBuyActivityList" resultMap="BaseResultMap">
        select *
        from 表名
    </select>

</mapper>

XML 复制代码

<mapper namespace="cn.qimingxing.infrastructure.dao.IGroupBuyActivityDao">

namespace = 绑定 Dao 接口，MyBatis 根据这个路径找到对应的接口。

注意：

必须是 Dao 接口的全类名
必须用. 分隔，不能用 /
不能带 .java 后缀

XML 复制代码

<resultMap id="BaseResultMap" type="cn.qimingxing.infrastructure.dao.po.GroupBuyActivity">
    <id column="id" property="id"/>
    <result column="activity_id" property="activityId"/>
</resultMap>

作用：把 数据库下划线字段 自动映射成 Java 驼峰字段

属性解释

id：给这个映射规则起个名字（随便起，但要唯一）
type：对应的实体类全类名（必须正确，不能带 .java）

内部标签

<id>：主键字段
<result>：普通字段

两个关键属性

column="xxx" → 数据库字段名
property="xxx" → 实体类字段名

XML 复制代码

    <!-- 4. 查询语句 -->
    <select id="queryGroupBuyActivityList" resultMap="BaseResultMap">
        select *
        from 表名
    </select>

✔ 属性解释

id：必须和 Dao 接口方法名完全一样
resultMap：使用上面定义的映射规则
resultType：直接写实体类（二选一，不要同时写）

五. 配置application.yml

通用模板

java 复制代码

# ==========================================
# 1. Spring Boot 基础配置
# ==========================================
spring:
  # 应用名称（随便起，方便识别）
  application:
    name: your-application-name

  # ==========================================
  # 2. 数据库连接配置（核心，必须改占位符）
  # ==========================================
  datasource:
    # 数据库 URL：格式 jdbc:mysql://IP:端口/数据库名?参数
    url: jdbc:mysql://localhost:3306/your_database_name?useUnicode=true&characterEncoding=utf8&autoReconnect=true&useSSL=false&serverTimezone=Asia/Shanghai
    # 数据库账号（替换为你的账号）
    username: your_database_username
    # 数据库密码（替换为你的密码）
    password: your_database_password
    # MySQL 8+ 驱动（固定写法，不用改；MySQL 5.x 用 com.mysql.jdbc.Driver）
    driver-class-name: com.mysql.cj.jdbc.Driver

    # ==========================================
    # 3. HikariCP 连接池配置（Spring Boot 默认，优化性能，通用推荐值）
    # ==========================================
    hikari:
      # 连接池名称（随便起）
      pool-name: HikariCP-Pool
      # 最小空闲连接数（推荐 5-15）
      minimum-idle: 10
      # 最大连接数（推荐 10-50，根据服务器配置调整）
      maximum-pool-size: 20
      # 空闲连接存活时间（毫秒，默认 600000=10分钟）
      idle-timeout: 300000
      # 连接最长生命周期（毫秒，默认 1800000=30分钟）
      max-lifetime: 1800000
      # 连接超时时间（毫秒，默认 30000=30秒）
      connection-timeout: 30000
      # 连接有效性检测 SQL（MySQL 固定写 SELECT 1；Oracle 写 SELECT 1 FROM DUAL）
      connection-test-query: SELECT 1

# ==========================================
# 4. MyBatis 核心配置（最关键！）
# ==========================================
mybatis:
  # 【必配】指定 Mapper XML 文件的位置（classpath: 对应 src/main/resources 目录）
  mapper-locations: classpath:mapper/*.xml
  # 【推荐配】指定实体类所在包（替换为你的实体类包路径），简化 XML 中 resultType 的写法
  type-aliases-package: com.example.project.po
  # 【推荐配】MyBatis 全局配置
  configuration:
    # 【核心推荐】自动下划线转驼峰（开启后，数据库 activity_id 自动映射到实体类 activityId，不用写 resultMap）
    map-underscore-to-camel-case: true
    # 【调试用】打印 SQL 语句到控制台（方便看 SQL 有没有执行、参数对不对；生产环境可关闭）
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
    # 开启二级缓存（可选，提升性能）
    cache-enabled: true
    # 开启延迟加载（可选，提升性能）
    lazy-loading-enabled: true

# ==========================================
# 5. 服务端口配置
# ==========================================
server:
  # 服务端口（默认 8080，可改成任意未被占用的端口）
  port: 8080

# ==========================================
# 6. 日志配置（可选，方便调试）
# ==========================================
logging:
  level:
    # 配置 Mapper 接口所在包的日志级别为 DEBUG（打印更详细的 SQL 信息）
    com.example.project.dao: debug
    # 全局日志级别（INFO/WARN/ERROR）
    root: info
  # 日志文件路径（可选，生产环境建议配置）
  file:
    name: logs/your-application-name.log

这一点要注意配置数据库的四个主要字段

|-------------------|---------|
| 配置项 | 含义 |
| url | 数据库连接地址 |
| username | 数据库账号 |
| password | 数据库密码 |
| driver-class-name | 数据库驱动 |

MyBatis配置，主要作用是告诉 MyBatis 去哪里找 Mapper XML 文件、怎么映射字段、要不要打印 SQL。如果提前配置好XML文件地址，那么这一步可以提前做。

六. 编写测试用例

这点没啥好说的，用@Resource或@Autowired注入第三步编写的Mapper接口，调用里面的方法进行测试即可。