lumina: Skill for Claude Code

Lumina JSON 序列化规范

功能概述

本技能包用于确保 Lumina 框架项目统一使用 Jackson 进行 JSON 序列化和反序列化，包括注解使用、日期格式化、空值处理等。

核心原则

1. 统一使用 Jackson - 所有 JSON 序列化/反序列化使用 Jackson
2. 禁止使用 Fastjson2 - 项目中不再使用 Fastjson2
3. 统一配置 - 使用 Spring Boot 默认的 Jackson 配置
4. 注解优先 - 使用 Jackson 注解进行字段控制

Jackson 基础使用

DTO 中的注解使用

@Data
public class AgentVO {
    
    private Long agentId;
    
    private String agentName;
    
    // 日期格式化
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private LocalDateTime createTime;
    
    // 忽略字段
    @JsonIgnore
    private String internalField;
    
    // 字段重命名
    @JsonProperty("agent_type")
    private AgentType agentType;
    
    // 空值处理
    @JsonInclude(JsonInclude.Include.NON_NULL)
    private String description;
}

全局配置

@Configuration
public class JacksonConfig {
    
    @Bean
    @Primary
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        
        // 日期格式
        mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
        mapper.setTimeZone(TimeZone.getTimeZone("GMT+8"));
        
        // 空值处理
        mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
        
        // 忽略未知属性
        mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        
        // 美化输出（开发环境）
        mapper.enable(SerializationFeature.INDENT_OUTPUT);
        
        return mapper;
    }
}

常用注解

@JsonFormat

用于日期时间格式化：

@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private LocalDateTime createTime;

@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private LocalDate createDate;

@JsonIgnore

忽略字段：

@JsonIgnore
private String password;

@JsonIgnore
private String internalField;

@JsonProperty

字段重命名：

@JsonProperty("agent_id")
private Long agentId;

@JsonProperty("agent_name")
private String agentName;

@JsonInclude

空值处理：

@JsonInclude(JsonInclude.Include.NON_NULL)
private String description;

@JsonInclude(JsonInclude.Include.NON_EMPTY)
private List<String> tags;