注解使用示例

本章按场景给出注解组合写法，覆盖框架支持的所有类型与高级特性。

完整示例

package com.demo.app.model;

import cn.cvking.forge.ddl.annotation.DateType;
import cn.cvking.forge.ddl.annotation.Field;
import cn.cvking.forge.ddl.annotation.Model;
import cn.cvking.forge.ddl.annotation.ModelTypeEnum;

import java.math.BigDecimal;
import java.time.LocalDateTime;

@Model(name = Order.MODEL_NAME, displayName = "订单", summary = "电商业务订单实体")
@Model.Advanced(type = ModelTypeEnum.STORE, table = "t_order")
public class Order {

    public static final String MODEL_NAME = "order";

    @Field(displayName = "主键")
    @Field.Long
    private Long id;

    @Field(displayName = "订单号", summary = "对外可见的订单号")
    @Field.String(length = 32)
    @Field.Advanced(column = "order_no")
    private String orderNo;

    @Field(displayName = "客户ID")
    @Field.Long
    private Long customerId;

    @Field(displayName = "订单金额")
    @Field.BigDecimal(precision = 14, scale = 2)
    private BigDecimal amount;

    @Field(displayName = "备注")
    @Field.Text
    private String remark;

    @Field(displayName = "扩展数据")
    @Field.LongText
    private String extData;

    @Field(displayName = "是否已支付")
    @Field.Boolean
    private Boolean paid;

    @Field(displayName = "创建时间")
    @Field.Date(type = DateType.DATETIME)
    private LocalDateTime createTime;

    @Field
    @Field.Advanced(store = false)
    private transient String runtimeToken;
}

按字段类型对照

字符串

@Field
@Field.String(length = 64)
private String name;

@Field
@Field.Text             // 对应 TEXT 列
private String remark;

@Field
@Field.LongText         // 对应 LONGTEXT / TEXT 长字段
private String extData;

数值

@Field
@Field.Integer
private Integer age;

@Field
@Field.Long
private Long userId;

@Field
@Field.BigDecimal(precision = 14, scale = 2)
private BigDecimal amount;

布尔

@Field
@Field.Boolean
private Boolean enabled;

日期时间

@Field
@Field.Date(type = DateType.DATE)
private LocalDate birthday;

@Field
@Field.Date(type = DateType.DATETIME)
private LocalDateTime createTime;

@Field
@Field.Date(type = DateType.TIMESTAMP)
private LocalDateTime updateTime;

@Field
@Field.Date(type = DateType.TIME)
private LocalTime workHourStart;

省略类型子注解（隐式推导）

如果不写类型子注解，框架会按 Java 类型推导：

@Field 
private String name;      // 推导为 STRING（注意：无 length → length=null）

@Field 
private Integer age;      // 推导为 INTEGER

@Field 
private Long userId;      // 推导为 LONG

@Field 
private Boolean enabled;  // 推导为 BOOLEAN

@Field 
private BigDecimal price; // 推导为 BIG_DECIMAL（无 precision/scale）

@Field 
private LocalDateTime ct; // 推导为 DATE（无 dateType，将兜底为 DATETIME）

何时显式标类型子注解

• 需要指定 length / precision / scale / dateType 等参数
• 字段 Java 类型不在兜底表里（比如 byte[]），必须显式标注，否则启动期抛 IllegalStateException
• 同一 Java 类型在不同字段需要不同语义（如同样 String，业务上一个是 VARCHAR、一个是 TEXT）

不持久化某个字段

store = false 的字段、或非存储模型不会进入数据库列。

@Field
@Field.Advanced(store = false)
private transient String runtimeToken;

显式表名与列名

@Model(name = "user")
@Model.Advanced(table = "t_user_v2")   // 表名不再走 camelToUnderscore
public class User {

    @Field
    @Field.Advanced(column = "u_name") // 列名不再走 camelToUnderscore
    @Field.String(length = 64)
    private String name;
}

如果不显式声明：

• modelName=user → 表名 user
• fieldName=registerTime → 列名 register_time

详细命名规则见 扫描机制 · 命名转换。

常见陷阱

不要 import 嵌套注解

错误写法：

import cn.cvking.forge.ddl.annotation.Field.String;  // 否 与 java.lang.String 冲突

正确写法：直接复合引用

import cn.cvking.forge.ddl.annotation.Field;

@Field.String(length = 64)  // 是
private String name;

别忘了字段必须有外层 @Field 或类型子注解

仅有 @Field.Advanced 时不会被识别为 DDL 字段。buildFieldDefinition 要求至少有一个：

• @Field
• @Field.Advanced
• 任一类型子注解（@Field.String / @Field.Integer …）

静态字段会被跳过

parseFields 显式跳过 static 字段，不会进入注册中心。

附录：注解字段速查

@Model

cn.cvking.forge.ddl.annotation.Model，@Target(TYPE)，标注 POJO 为业务实体。

字段	类型	默认值	必填	说明
name	String	—	是	模型唯一标识
displayName	String	""	否	展示名
summary	String	""	否	描述摘要

@Model.Advanced

字段	类型	默认值	说明
type	ModelTypeEnum	STORE	模型类型
table	String	""	显式表名；为空时由 modelName 驼峰转下划线推导

@Field

cn.cvking.forge.ddl.annotation.Field，@Target(FIELD)。

字段	类型	默认值	说明
displayName	String	""	展示名
summary	String	""	描述摘要

@Field.Advanced

字段	类型	默认值	说明
store	boolean	true	是否持久化
column	String	""	显式列名；为空时由 fieldName 驼峰转下划线推导

类型子注解一览

注解	字段	默认值	对应 FieldType
@Field.String	length: int	255	STRING
@Field.Text	—	—	TEXT
@Field.LongText	—	—	LONG_TEXT
@Field.Integer	—	—	INTEGER
@Field.Long	—	—	LONG
@Field.Boolean	—	—	BOOLEAN
@Field.BigDecimal	precision: int scale: int	19 4	BIG_DECIMAL
@Field.Date	type: DateType	DATETIME	DATE

ModelTypeEnum

取值	含义
STORE	持久化存储模型（默认）
TRANSIENT	传输模型，不落库
ABSTRACT	抽象模型，仅供继承
PROXY	代理模型