SKILL.md
DDD4J Jackson 序列化规则
编码 DDD4J 项目中 Jackson 的使用规则。LLM 训练数据中的 Jackson 用法会与项目约定冲突。
为什么需要这个技能
LLM 会用 ISO-8601 格式 2024-03-15T10:30:00Z 序列化日期——DDD4J 要求 2024-03-15 10:30:00。LLM 不会给 null 数组返回 []——DDD4J 前端期望 null 数组永远不出现。这些规则 LLM 不知道。
Capability Boundaries
✅ Strong Suits
- 日期格式规则 — yyyy-MM-dd HH:mm:ss（非ISO-8601）
- Null值规则 — 数组→[]、字符串→""、数字→保持null、布尔→保持null
- @Sensitive 脱敏 — 5种策略(手机/身份证/姓名/地址/邮箱)
- JacksonKit — Redis/缓存专用的独立ObjectMapper(DefaultTyping.NON_FINAL)
- ToLongDeserializer — 处理前端JS大数字精度丢失
❌ Out of Scope
- 实体继承/返回值约定 → ddd4j-core
- MyBatis JSON字段处理 → ddd4j-mybatis
- API签名/安全 → ddd4j-satoken
LLM 最常犯的错误
| # | 错误 | 正确做法 |
|---|---|---|
| 1 | 日期用 ISO-8601 2024-03-15T10:30:00Z |
用 yyyy-MM-dd HH:mm:ss |
| 2 | null 数组返回 null |
返回 [] |
| 3 | null 字符串返回 null |
返回 "" |
| 4 | 给 null 数字返回 0 |
数字/布尔保持 null，不转化 |
| 5 | 手动写脱敏逻辑 | 用 @Sensitive(strategy = SensitiveStrategy.PHONE) |
| 6 | 缓存用 Web ObjectMapper | 用 JacksonKit（DefaultTyping.NON_FINAL + ALL visibility） |
| 7 | 大数字直接返回 Long | 用 ToLongDeserializer 处理精度丢失 |
核心规则速查
// ❌ 错误：LLM会这样写
@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
private LocalDateTime createTime;
// ✅ 正确：DDD4J 已全局配置
private LocalDateTime createTime; // 序列化为 "2024-03-15 10:30:00"
// ✅ Null 处理：前端收到的 JSON
// null 数组 → [] (默认开启)
// null 字符串 → "" (默认开启)
// null 对象 → {} (默认开启)
// null 数字 → null (不转化)
// null 布尔 → null (不转化)
// ✅ 敏感数据脱敏
public class UserVO {
@Sensitive(strategy = SensitiveStrategy.PHONE)
private String phone; // 185****1653
@Sensitive(strategy = SensitiveStrategy.ID_CARD)
private String idCard; // 1234****5678
@Sensitive(strategy = SensitiveStrategy.USERNAME)
private String name; // 张*三
@Sensitive(strategy = SensitiveStrategy.EMAIL)
private String email; // r*****[email protected]
@Sensitive(strategy = SensitiveStrategy.ADDRESS)
private String address; // 北京市****海淀区****
}
// ✅ 两个 ObjectMapper
// Web用：JacksonAutoConfiguration 自动配置的，用于 HTTP 请求响应
@Autowired private ObjectMapper objectMapper;
// 缓存用：JacksonKit 独立 ObjectMapper，带 DefaultTyping.NON_FINAL
JacksonKit.toJson(obj); // 序列化时写入类型信息
JacksonKit.fromJson(json, Type.class); // 反序列化时根据类型信息恢复Gotchas
- 不要自己配置 Jackson2ObjectMapperBuilderCustomizer — DDD4J 已预配置，冲突会导致日期格式错乱
- 对象存 Redis 必须用 JacksonKit 不是 ObjectMapper — Web ObjectMapper 没有 DefaultTyping，多态反序列化会丢类型
- 数字 null 不会转 0 — 前端需处理数字可能为 null 的情况（与数组/字符串不同）
- @Sensitive 只对 String 类型生效 — 其他类型忽略
- ToLongDeserializer 接受字符串转 Long — 前端传
"1234567890123456789"也能正确解析 - 日期格式同时影响序列化和反序列化 — 前端提交的日期也必须
yyyy-MM-dd HH:mm:ss
Data Privacy
本技能不收集、存储或传输任何用户数据。@Sensitive 注解仅用于在序列化时脱敏已存在的敏感数据。