自定义VariableListener异常排查及大学排课紧凑性优化求助

嘿，我之前帮不少人排查过OptaPlanner里这个让人头大的异常，结合你做大学排课优化、想提升课程紧凑性的需求，给你拆解清楚问题根源和落地的修复方案：

先搞懂为啥会触发这个异常 #

这个报错本质上是你的VariableListener违反了OptaPlanner的核心规则，常见的坑有这几个：

• 你在listener里直接修改了非影子变量——比如Lesson里的period、room这些标记为@PlanningVariable的字段，或者其他没加@ShadowVariable注解的普通字段
• 引发了循环更新：比如A课程的变更触发B的listener，B的变更又绕回来触发A的listener，形成死循环
• 没正确处理变量变更的前后事件，导致OptaPlanner内部状态乱掉了

针对你需求的具体修复步骤 #

你要更新同一天所有课程的列表来优化紧凑性，这完全符合OptaPlanner里**影子变量（Shadow Variable）**的使用场景——影子变量就是用来存储由其他规划变量推导出来的状态，不能手动修改，只能通过VariableListener维护。

1. 给需要的字段打上影子变量标记 #

先在你的Lesson类里加一个存储同一天课程列表的字段，用@ShadowVariable关联到period（因为日期是period的一部分，period变了，同一天的课程列表就得跟着变）：

@PlanningEntity
public class Lesson {
    private int id;
    private Course course;
    @PlanningVariable(valueRangeProviderRefs = {"periodRange"})
    private Period period;
    @PlanningVariable(valueRangeProviderRefs = {"roomRange"})
    private Room room;
    private int blockLength = 1;
    private boolean prime = false;
    private boolean uKW = false;
    private boolean gKW = false;
    private boolean FWP;

    // 新增：存储同一天的所有课程，标记为影子变量
    @ShadowVariable(sourceVariableName = "period", variableListenerClass = SameDayLessonsListener.class)
    private List<Lesson> sameDayLessons;

    // 别忘了加getter和setter
    public List<Lesson> getSameDayLessons() {
        return sameDayLessons;
    }

    public void setSameDayLessons(List<Lesson> sameDayLessons) {
        this.sameDayLessons = sameDayLessons;
    }
}

2. 正确实现VariableListener #

重点：这个listener只能更新影子变量，碰都不能碰period、room这些规划变量！而且必须用ScoreDirector的before/after方法来包裹变更，不然OptaPlanner会觉得状态乱了。给你写个可用的实现：

public class SameDayLessonsListener implements VariableListener<Lesson> {

    @Override
    public void beforeEntityAdded(ScoreDirector scoreDirector, Lesson lesson) {
        // 实体刚加进来的时候不用处理，除非你有初始化逻辑
    }

    @Override
    public void afterEntityAdded(ScoreDirector scoreDirector, Lesson lesson) {
        // 课程添加后，更新当天所有课程的sameDayLessons列表
        updateSameDayLessons(scoreDirector, lesson);
    }

    @Override
    public void beforeVariableChanged(ScoreDirector scoreDirector, Lesson lesson) {
        // 课程的period变之前，先把它从当天其他课程的列表里删掉
        removeLessonFromSameDayLists(scoreDirector, lesson);
    }

    @Override
    public void afterVariableChanged(ScoreDirector scoreDirector, Lesson lesson) {
        // period变完后，重新更新当天所有课程的列表
        updateSameDayLessons(scoreDirector, lesson);
    }

    @Override
    public void beforeEntityRemoved(ScoreDirector scoreDirector, Lesson lesson) {
        // 课程被删掉前，先从当天其他课程的列表里移除它
        removeLessonFromSameDayLists(scoreDirector, lesson);
    }

    @Override
    public void afterEntityRemoved(ScoreDirector scoreDirector, Lesson lesson) {
        // 删掉之后不用额外操作
    }

    private void removeLessonFromSameDayLists(ScoreDirector scoreDirector, Lesson lesson) {
        if (lesson.getPeriod() == null) {
            return; // 还没分配时间段的话直接跳过
        }
        // 拿到当天所有课程
        List<Lesson> sameDayLessons = getAllLessonsOnSameDay(scoreDirector, lesson);
        for (Lesson sameDayLesson : sameDayLessons) {
            if (sameDayLesson != lesson) {
                // 必须用scoreDirector的方法包裹变更，不然会触发异常
                scoreDirector.beforeVariableChanged(sameDayLesson, "sameDayLessons");
                sameDayLesson.getSameDayLessons().remove(lesson);
                scoreDirector.afterVariableChanged(sameDayLesson, "sameDayLessons");
            }
        }
    }

    private void updateSameDayLessons(ScoreDirector scoreDirector, Lesson lesson) {
        if (lesson.getPeriod() == null) {
            return;
        }
        List<Lesson> sameDayLessons = getAllLessonsOnSameDay(scoreDirector, lesson);
        // 先更新当前课程的列表
        scoreDirector.beforeVariableChanged(lesson, "sameDayLessons");
        lesson.setSameDayLessons(new ArrayList<>(sameDayLessons));
        scoreDirector.afterVariableChanged(lesson, "sameDayLessons");
        // 再更新当天其他课程的列表
        for (Lesson sameDayLesson : sameDayLessons) {
            if (sameDayLesson != lesson) {
                scoreDirector.beforeVariableChanged(sameDayLesson, "sameDayLessons");
                sameDayLesson.getSameDayLessons().add(lesson);
                scoreDirector.afterVariableChanged(sameDayLesson, "sameDayLessons");
            }
        }
    }

    private List<Lesson> getAllLessonsOnSameDay(ScoreDirector scoreDirector, Lesson lesson) {
        // 从当前工作解里筛选出同一天的课程
        return scoreDirector.getWorkingSolution().getLessonList().stream()
                .filter(otherLesson -> otherLesson.getPeriod() != null 
                        && otherLesson.getPeriod().getDate().equals(lesson.getPeriod().getDate()))
                .collect(Collectors.toList());
    }
}

3. 避坑关键提醒 #

• 绝对不能在listener里改规划变量：比如period、room这些用户能调整的变量，只能动影子变量
• 必须调用scoreDirector的before/after方法：这是OptaPlanner跟踪状态的核心，少了就会触发那个异常
• 处理空值：如果课程还没分配period，一定要跳过处理，不然会空指针
• 避免循环更新：确保你的listener不会引发A改B、B改A的死循环

额外给你提个排课紧凑性的优化建议 #

除了用影子变量跟踪同一天课程，你还可以写自定义评分规则——比如惩罚同一天内课程之间的空闲时间，让OptaPlanner在搜索时优先选择紧凑的排课方案；或者调整搜索启发式，比如用Late Acceptance或Tabu Search，效果会更好。

内容的提问来源于stack exchange，提问作者Robin Atherton