Spring Hateoas调试报错：uriTemplate must not be null问题排查

这问题我之前踩过坑，本质是Spring Hateoas里ControllerLinkBuilder的动态代理机制和调试器的行为冲突导致的，下面给你拆解清楚：

1. 为什么调试单步执行会触发异常？ #

ControllerLinkBuilder.methodOn(Plans.class)其实是生成了一个动态代理对象，这个对象的作用不是真正执行getPlans()方法，而是用来捕获你调用的方法签名、参数信息，为后续生成链接做准备。

当你在methodLinkPlans或plansLink的赋值行添加断点并单步执行时，调试器会自动尝试展示这些变量的详情（比如调用对象的toString()方法或者访问属性），这个操作会触发代理对象的额外方法调用。但这个代理本身没有真实的业务实现，这种额外调用会破坏ControllerLinkBuilder内部用来存储方法元数据的上下文，导致后续linkTo()方法找不到对应的请求路径模板，最终抛出'uriTemplate' must not be null的异常。

而如果直接在return plansLink;行加断点，中间没有触发调试器对代理对象的额外访问，linkTo()就能正常从之前捕获的元数据中拿到uriTemplate，自然不会报错。

2. uriTemplate和ControllerLinkBuilder的关系 #

uriTemplate就是你Controller方法对应的请求路径模板（比如/plans/{id}），它是ControllerLinkBuilder生成HATEOAS链接的核心依据：

• 第一步，methodOn()生成代理对象，捕获你调用的getPlans(requestParam.getID())的方法签名和参数；
• 第二步，linkTo()会根据代理对象记录的方法信息，从Spring维护的请求映射元数据中找到对应的uriTemplate；
• 最后填充参数、设置rel和请求类型，生成完整的Link对象。

简单说，uriTemplate是ControllerLinkBuilder构建链接的“蓝图”，没有它就没法生成有效的HATEOAS链接。

调试时的解决建议 #

• 尽量避免在methodOn()或linkTo()的赋值行加断点单步执行，直接跳到return行查看结果；
• 如果必须查看中间状态，不要通过调试器展开代理对象查看详情，改用日志打印关键信息（比如参数ID）；
• 也可以把代码拆分成更细的步骤，调试时忽略代理对象的展示：

public Link getPlansLink(RequestParam requestParam, String linkName){
    // 生成代理对象，调试时不要展开这个变量
    Plans plansProxy = ControllerLinkBuilder.methodOn(Plans.class);
    // 捕获方法调用信息，同样不要在调试时展开
    ResponseEntity<Plans> methodLinkPlans = plansProxy.getPlans(requestParam.getID());
    Link plansLink = ControllerLinkBuilder.linkTo(methodLinkPlans)
            .withRel(linkName)
            .withType(GET);
    return plansLink;
}

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