full-stack-skills DDD4J 自定义校验规则
编码 DDD4J 项目中四个自定义 Bean Validation 约束的使用规则。LLM 不知道这些约束存在，会自己写校验逻辑。
为什么需要这个技能
LLM 会用 @Pattern(regexp="^1[3-9]\\d{9}$") 校验手机号——DDD4J 有 @PhoneNumber（基于 libphonenumber，支持国际化）。LLM 会用 @DateFormat 校验日期——DDD4J 有 @StringDateValue（空字符串静默通过）。这些自定义约束 LLM 完全不知道。
Capability Boundaries
✅ Strong Suits
- @AllowedValues — 字符串数组白名单校验，支持 nullable
- @PhoneNumber — Google libphonenumber 手机号校验
- @NumberValue — 正则数字格式校验
- @StringDateValue — 日期字符串格式校验（空串通过）
❌ Out of Scope
- 实体定义/返回值约定 → ddd4j-core
- Jackson 序列化校验 → ddd4j-jackson
LLM 最常犯的错误
| # | 错误 | 正确做法 |
|---|---|---|
| 1 | @Pattern(regexp="1[3-9]\\d{9}") 校验手机号 |
用 @PhoneNumber（libphonenumber，国际化） |
| 2 | @DateTimeFormat 校验日期 |
用 @StringDateValue(format="yyyy-MM-dd HH:mm:ss") |
| 3 | 自定义 Validator 类做校验 | 校验注解放在 Param/DTO 字段上 |
| 4 | 给 @StringDateValue 的字段传空字符串 | 空字符串静默通过，不是校验失败 |
| 5 | 不写 message 属性 | 所有自定义约束必须显式写 message |
| 6 | 用 @NotEmpty 代替 @AllowedValues.nullable=false |
nullable 控制空值行为 |
核心规则速查
// ✅ 正确：四个自定义约束
// @AllowedValues — 白名单校验
public class UserParam extends BaseParam {
@AllowedValues(values = {"MALE", "FEMALE", "OTHER"}, nullable = false,
message = "性别必须为 MALE/FEMALE/OTHER 之一")
private String gender;
@AllowedValues(values = {"ACTIVE", "INACTIVE"}, nullable = true,
message = "状态必须为 ACTIVE/INACTIVE")
private String status; // nullable=true → 空值通过校验
}
// @PhoneNumber — 手机号校验（libphonenumber）
public class RegisterParam extends BaseParam {
@PhoneNumber(lang = "CN", message = "手机号格式不正确")
private String phone;
@PhoneNumber(lang = "US", message = "Invalid US phone number")
private String usPhone;
}
// @NumberValue — 数字格式
public class IdParam {
@NumberValue(regex = "^[0-9\\-]+$", message = "ID只能包含数字和横线")
private String id;
}
// @StringDateValue — 日期字符串
public class DateParam {
@StringDateValue(format = "yyyy-MM-dd HH:mm:ss", message = "日期格式错误")
private String beginTime; // "" 空字符串 → 静默通过
// SimpleDateFormat.setLenient(false) → 严格模式
}
Gotchas
- @StringDateValue 空字符串静默通过 — 空值不触发校验，需要用 @NotEmpty 配合
- 所有自定义约束必须提供 message — 校验器
disableDefaultConstraintViolation禁用了默认消息 - @PhoneNumber 依赖 libphonenumber — 需要引入
com.googlecode.libphonenumber - @AllowedValues.nullable=true 时 null/空串都通过 — nullable=false 时空值不通过
- @NumberValue 默认正则
^[0-9\\-]+$— 只允许数字和横线 - 校验注解放在 Param/DTO 上 — 不要创建独立的 Validator 类
- @StringDateValue 使用严格模式 —
SimpleDateFormat.setLenient(false)，非严格日期不通过
Data Privacy
本技能不收集、存储或传输任何用户数据。